Skip to content

docs: add Slack CLI setup instructions to README.md #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
srtaalej merged 6 commits into from
May 15, 2026
Merged

docs: add Slack CLI setup instructions to README.md #80

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c0e93b1
docs: add Slack CLI setup instructions to README
srtaalej May 12, 2026
4a4e63e
chore: add project dependencies to pyproject.toml and remove requirem…
srtaalej May 12, 2026
6baf485
fix: update README install command now that requirements.txt is removed
srtaalej May 12, 2026
b3a0352
chore: restore requirements.txt for CI compatibility
srtaalej May 12, 2026
cf2e5c2
chore: pin all dependencies and remove slack install step
srtaalej May 12, 2026
e05577f
chore: revert pyproject.toml to tool config only, keep requirements.t…
srtaalej May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 85 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 +2,121 @@

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
<details><summary><strong>Using Slack CLI</strong></summary>

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
```

Comment on lines +22 to +27

@zimeg zimeg May 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You'll also need to log in if this is your first time using the Slack CLI.
```sh
slack login
```

🪓 suggestion: We can perhaps remove this too! I found it confusing when searching for the first step to use this template

@srtaalej srtaalej May 15, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm i think we should keep for now.login is important for new user setup 💭

#### 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!

@zimeg zimeg May 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### 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!

🪓 question: Might we remove this in favor of the run command installs?

</details>

<details><summary><strong>Using Terminal</strong></summary>

#### 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*
4. Review the configuration and click *Create*
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
export SLACK_BOT_TOKEN=<your-bot-token>
export SLACK_APP_TOKEN=<your-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 dependencies

```sh
pip install .
```

</details>

## Development

# Install the dependencies
pip install -r requirements.txt
### Starting the app

# Start your local server
#### 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 .
Expand All @@ -70,15 +134,15 @@ 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

Only implement OAuth if you plan to distribute your application across multiple workspaces. A separate `app_oauth.py` file can be found with relevant OAuth settings.

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
Expand Down
10 changes: 10 additions & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,13 @@
[project]

@zimeg zimeg May 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

(.venv) $ pip install .
Processing /Users/eden.zimbelman/programming/samples/bolt-python-starter-template
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error

  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [14 lines of output]
      error: Multiple top-level packages discovered in a flat-layout: ['logs', 'listeners'].

      To avoid accidental inclusion of unwanted files or directories,
      setuptools will not proceed with this build.

      If you are trying to create a single distribution with multiple packages
      on purpose, you should not rely on automatic discovery.
      Instead, consider the following options:

      1. set up custom discovery (`find` directive with `include` or `exclude`)
      2. use a `src-layout`
      3. explicitly set `py_modules` or `packages` with a list of names

      To find more information, look for "package discovery" on setuptools docs.
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.

[notice] A new release of pip is available: 24.3.1 -> 26.1.1
[notice] To update, run: pip install --upgrade pip
error: subprocess-exited-with-error

× Getting requirements to build wheel did not run successfully.
│ exit code: 1
╰─> See above for output.

note: This error originates from a subprocess, and is likely not a problem with pip.

⚠️ issue: This might find conflict in new virtual environments? I'm wondering if we want to keep these changes focused to requirements.txt in this PR and follow up to favor pyproject.toml afterward

@srtaalej srtaalej May 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah thanks for catching that! will do 🫡

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",

@zimeg zimeg May 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔬 suggestion: We should pick one of these options of versioning? I'd suggest exact pins because @dependabot should be checking back often!

]

[tool.ruff]
line-length = 125
exclude = [".venv", "venv"]
Expand Down