From c0e93b153e085fd19c6d8300b390a2f3df1eeb6f Mon Sep 17 00:00:00 2001 From: Ale Mercado Date: Tue, 12 May 2026 15:04:04 -0400 Subject: [PATCH 1/6] docs: add Slack CLI setup instructions to README --- README.md | 104 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 84 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 48acdfd..9d9b0e9 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,52 @@ This is a generic Bolt for Python template app used to build out Slack apps. -Before getting started, make sure you have a development workspace where you have permissions to install apps. If you don’t have one setup, go ahead and [create one](https://slack.com/create). +## Setup + +Before getting started, make sure you have a development workspace where you have permissions to install apps. If you don't have one setup, go ahead and [create one](https://slack.com/create). + +### Developer Program + +Join the [Slack Developer Program](https://api.slack.com/developer-program) for exclusive access to sandbox environments for building and testing your apps, tooling, and resources created to help you build and grow. + ## Installation -#### Create a Slack App +
Using Slack CLI + +Install the latest version of the Slack CLI for your operating system: + +- [Slack CLI for macOS & Linux](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux/) +- [Slack CLI for Windows](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-windows/) + +You'll also need to log in if this is your first time using the Slack CLI. + +```sh +slack login +``` + +#### Initializing the project + +```sh +slack create my-bolt-python-app --template slack-samples/bolt-python-starter-template +cd my-bolt-python-app +``` + +#### Creating the Slack app + +Use the following command to add your new Slack app to your development workspace. Choose a "local" app environment for upcoming development: + +```sh +slack install +``` + +After the Slack app has been created you're all set to start developing! + +
+ +
Using Terminal + +#### Create Your Slack App + 1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and choose "From an app manifest" 2. Choose the workspace you want to install the application to 3. Copy the contents of [manifest.json](./manifest.json) into the text box that says `*Paste your manifest code here*` (within the JSON tab) and click *Next* @@ -13,10 +55,11 @@ Before getting started, make sure you have a development workspace where you hav 5. Click *Install to Workspace* and *Allow* on the screen that follows. You'll then be redirected to the App Configuration dashboard. #### Environment Variables + Before you can run the app, you'll need to store some environment variables. -1. Open your apps configuration page from this list, click **OAuth & Permissions** in the left hand menu, then copy the Bot User OAuth Token. You will store this in your environment as `SLACK_BOT_TOKEN`. -2. Click ***Basic Information** from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the `connections:write` scope. Copy this token. You will store this in your environment as `SLACK_APP_TOKEN`. +1. Open your apps configuration page from [this list](https://api.slack.com/apps), click **OAuth & Permissions** in the left hand menu, then copy the Bot User OAuth Token. You will store this in your environment as `SLACK_BOT_TOKEN`. +2. Click **Basic Information** from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the `connections:write` scope. Copy this token. You will store this in your environment as `SLACK_APP_TOKEN`. ```zsh # Replace with your app token and bot token @@ -24,35 +67,56 @@ export SLACK_BOT_TOKEN= export SLACK_APP_TOKEN= ``` -### Setup Your Local Project -```zsh -# Clone this project onto your machine -git clone https://github.com/slack-samples/bolt-python-starter-template.git +#### Initializing the project -# Change into this project directory -cd bolt-python-starter-template +```sh +git clone https://github.com/slack-samples/bolt-python-starter-template.git my-bolt-python-app +cd my-bolt-python-app +``` -# Setup your python virtual environment +#### Setup your python virtual environment + +```sh python3 -m venv .venv -source .venv/bin/activate +source .venv/bin/activate # for Windows OS, .\.venv\Scripts\Activate instead should work +``` -# Install the dependencies +#### Install dependencies + +```sh pip install -r requirements.txt +``` -# Start your local server +
+ +## Development + +### Starting the app + +#### Slack CLI + +```sh +slack run +``` + +#### Terminal + +```sh python3 app.py ``` -#### Linting +### Linting + ```zsh # Run ruff from root directory for linting -ruff check . +ruff check # Run ruff from root directory for code formatting -ruff format . +ruff format ``` -#### Testing +### Testing + ```zsh # Run pytest from root directory for unit testing pytest . @@ -70,7 +134,7 @@ pytest . ### `/listeners` -Every incoming request is routed to a "listener". Inside this directory, we group each listener based on the Slack Platform feature used, so `/listeners/shortcuts` handles incoming [Shortcuts](https://api.slack.com/interactivity/shortcuts) requests, `/listeners/views` handles [View submissions](https://api.slack.com/reference/interaction-payloads/views#view_submission) and so on. +Every incoming request is routed to a "listener". Inside this directory, we group each listener based on the Slack Platform feature used, so `/listeners/shortcuts` handles incoming [Shortcuts](https://docs.slack.dev/interactivity/implementing-shortcuts/) requests, `/listeners/views` handles [View submissions](https://api.slack.com/reference/interaction-payloads/views#view_submission) and so on. ## App Distribution / OAuth @@ -78,7 +142,7 @@ Only implement OAuth if you plan to distribute your application across multiple When using OAuth, Slack requires a public URL where it can send requests. In this template app, we've used [`ngrok`](https://ngrok.com/download). Checkout [this guide](https://ngrok.com/docs#getting-started-expose) for setting it up. -Start `ngrok` to access the app on an external network and create a redirect URL for OAuth. +Start `ngrok` to access the app on an external network and create a redirect URL for OAuth. ``` ngrok http 3000 From 4a4e63e90f89d148563000ed24cf6530054cbd79 Mon Sep 17 00:00:00 2001 From: Ale Mercado Date: Tue, 12 May 2026 16:15:23 -0400 Subject: [PATCH 2/6] chore: add project dependencies to pyproject.toml and remove requirements.txt --- pyproject.toml | 10 ++++++++++ requirements.txt | 3 --- 2 files changed, 10 insertions(+), 3 deletions(-) delete mode 100644 requirements.txt diff --git a/pyproject.toml b/pyproject.toml index b800495..ded3d93 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,13 @@ +[project] +name = "bolt-python-starter-template" +version = "0.1.0" +requires-python = ">=3.9" +dependencies = [ + "slack-sdk==3.41.0", + "slack-bolt>=1.28.0", + "slack-cli-hooks<1.0.0", +] + [tool.ruff] line-length = 125 exclude = [".venv", "venv"] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 43177ce..0000000 --- a/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -pytest==9.0.3 -ruff==0.15.12 -slack-bolt==1.28.0 From 6baf48561f65ce3d0f9009a522ca15bec8a1f777 Mon Sep 17 00:00:00 2001 From: Ale Mercado Date: Tue, 12 May 2026 16:17:21 -0400 Subject: [PATCH 3/6] fix: update README install command now that requirements.txt is removed --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9d9b0e9..f3a6554 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ source .venv/bin/activate # for Windows OS, .\.venv\Scripts\Activate instead sh #### Install dependencies ```sh -pip install -r requirements.txt +pip install . ``` From b3a03525a35ecdf765b50fa0422800f49a46918f Mon Sep 17 00:00:00 2001 From: Ale Mercado Date: Tue, 12 May 2026 16:18:45 -0400 Subject: [PATCH 4/6] chore: restore requirements.txt for CI compatibility --- requirements.txt | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 requirements.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..43177ce --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +pytest==9.0.3 +ruff==0.15.12 +slack-bolt==1.28.0 From cf2e5c2740edecb358ff6a6408cc67f656188555 Mon Sep 17 00:00:00 2001 From: Ale Mercado Date: Tue, 12 May 2026 16:34:27 -0400 Subject: [PATCH 5/6] chore: pin all dependencies and remove slack install step --- README.md | 10 +--------- pyproject.toml | 4 ++-- 2 files changed, 3 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f3a6554..e9742f8 100644 --- a/README.md +++ b/README.md @@ -32,15 +32,7 @@ slack create my-bolt-python-app --template slack-samples/bolt-python-starter-tem cd my-bolt-python-app ``` -#### Creating the Slack app - -Use the following command to add your new Slack app to your development workspace. Choose a "local" app environment for upcoming development: - -```sh -slack install -``` - -After the Slack app has been created you're all set to start developing! +After cloning, you're all set to start developing! diff --git a/pyproject.toml b/pyproject.toml index ded3d93..5f14b2d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,8 +4,8 @@ version = "0.1.0" requires-python = ">=3.9" dependencies = [ "slack-sdk==3.41.0", - "slack-bolt>=1.28.0", - "slack-cli-hooks<1.0.0", + "slack-bolt==1.28.0", + "slack-cli-hooks==0.3.0", ] [tool.ruff] From e05577f0c2e72c3acacae06da2b8deb245aa289a Mon Sep 17 00:00:00 2001 From: Ale Mercado Date: Thu, 14 May 2026 10:00:24 -0400 Subject: [PATCH 6/6] chore: revert pyproject.toml to tool config only, keep requirements.txt for now --- README.md | 2 +- pyproject.toml | 10 ---------- 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/README.md b/README.md index e9742f8..c726123 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ source .venv/bin/activate # for Windows OS, .\.venv\Scripts\Activate instead sh #### Install dependencies ```sh -pip install . +pip install -r requirements.txt ``` diff --git a/pyproject.toml b/pyproject.toml index 5f14b2d..b800495 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,13 +1,3 @@ -[project] -name = "bolt-python-starter-template" -version = "0.1.0" -requires-python = ">=3.9" -dependencies = [ - "slack-sdk==3.41.0", - "slack-bolt==1.28.0", - "slack-cli-hooks==0.3.0", -] - [tool.ruff] line-length = 125 exclude = [".venv", "venv"]