Quickstart guide for modular Slack apps

In the following guide, you'll install the Slack CLI and authorize it in your workspace. Then, you'll use the CLI to scaffold a fully-functional next generation app and run it locally.

In order to complete this quickstart guide, your workspace must be on a paid plan. Check out our FAQ for more details.

Step 1: Install the Slack CLI

MacOS & Linux installer Windows installation Manual installation

Run the automated installer from your terminal window:

curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash

This will install the Slack CLI and all required dependencies, including Deno — the runtime environment for our next generation platform. If you have VSCode installed, the VSCode Deno extension will be installed.

Optional: Use an alias for the Slack CLI binary

The installation script will detect existing binaries named slack and bail if it finds one; it will not overwrite your existing slack binary.

If you want to install the CLI as anything other than slack, you can do so by passing the -s argument to the installer script:

curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s <your-preferred-alias>

Run the automated installer from Windows PowerShell:

irm https://downloads.slack-edge.com/slack-cli/install-windows.ps1 | iex

This will install the Slack CLI and all required dependencies, including Deno — the runtime environment for our modular platform. If you have VSCode installed, the VSCode Deno extension will also be installed.

Custom installation

There are several flags available to customize the installation. Since flags cannot be passed to remote scripts, you must first download the installation script to a local file:

irm https://downloads.slack-edge.com/slack-cli/install-windows.ps1 -outfile 'install-windows.ps1'

The available flags are:

Flag	What it does	Example
`-Alias`	Installs the Slack CLI as the provided alias	`-Alias slackcli` will create a binary named `slackcli.exe` and add it to your path
`-Version`	Installs a specific version of the Slack CLI	`-Version 2.1.0` installs version `2.1.0` of the Slack CLI
`-SkipGit`	If true, will not attempt to install Git when Git is not present	`-SkipGit $true`
`-SkipDeno`	If true, will not attempt to install Deno when Deno is not present	`-SkipDeno $true`

You can also see all available flags by passing -? to the installation script:

.\install-windows.ps1 -?

Here's an example invocation using every flag:

.\install-windows.ps1 -Version 2.1.0 -Alias slackcli -SkipGit $true -SkipDeno $true

Not working? You may need to update your session's Language Mode.

For the installer to work correctly, your PowerShell session's language mode will need to be set to FullLanguage.

To check your session's language mode, run the following in your PowerShell window:

$ExecutionContext.SessionState.LanguageMode

To run the installer, your session's language mode will need to be FullLanguage. If it's not, you can set your session's language mode to FullLanguage with the following command:

$ExecutionContext.SessionState.LanguageMode = "FullLanguage"

1. Download and install Deno.

2. Verify that Deno is installed and in your path:

$ deno --version
deno 1.25.* (release, x86_64-apple-darwin)
v8 10.*
typescript 4.*

3. Download and install Git, a dependency of the slack CLI.

4. Download the Slack CLI installer for your environment.

The slack CLI is currently at version v2.3.0. See the changelog for details.

Download for macOS (.tar.gz)

Download for Linux (.tar.gz)

Download for Windows (.zip)

5. Add the slack CLI to your path.

Existing slack binary in path?

If you have another CLI tool in your path called slack, we recommend renaming our slack binary to a different name before adding it to your path.

Mac/Linux: Copy the CLI into any folder that is already in your path—such as /usr/local/bin—or add a new folder to your path by listing whatever folder you installed the CLI to in /etc/paths.
Windows: Copy the CLI into any folder that is already in your path, or add a new folder to your path by listing whatever folder you installed the CLI to in your Environment Variables. You may not have access to edit System variables, so you might need to add it to your account's User variables. You can open the Environment Variables dialog by pressing the Win+R keys to open the Run window, and entering the following command: rundll32.exe sysdm.cpl,EditEnvironmentVariables.

6. Verify that slack is installed and in your path:

$ slack version
Using slack v2.3.0

7. Verify that all dependencies have been installed:

$ slack doctor

8. Download the VSCode extension for Deno (recommended, but optional).

Step 2: Authorize the CLI

With the CLI freshly installed, authorize the CLI in your workspace with the following command:

slack login

In your terminal window, you should see an authorization ticket in the form of a slash command, and a prompt to enter a challenge code:

$ slack login

📋 Run the following slash command in any Slack channel or DM
   This will open a modal with user permissions for you to approve
   Once approved, a challege code will be generated in Slack

/slackauthticket ABC123defABC123defABC123defABC123defXYZ

? Enter challenge code

Copy the slash command and paste it into any Slack conversation in the workspace you will be developing in.

When you send the message containing the slash command, a modal will pop up, prompting you to grant certain permissions to the CLI. Click the Confirm button in the modal to move to the next step.

A new modal with a challenge code will appear. Copy that challenge code, and paste it back into your terminal:

? Enter challenge code eXaMpLeCoDe

✅ You've successfully authenticated! 🎉
   Authorization data was saved to ~/.slack/credentials.json

💡 Get started by creating a new app with `slack create my-app`
   Explore the details of available commands with `slack help`

Verify that your CLI is set up by running slack auth list in your terminal window:

$ slack auth list

myworkspace (Team ID: T123ABC456)
User ID: U123ABC456
Last updated: 2023-01-01 12:00:00 -07:00

You should see an entry for the workspace you just authorized. If you don't, get a new authorization ticket with slack login to try again.

You're now ready to begin building next generation Slack apps! In the next step, we'll use a sample app to get started.

Step 3: Create a Slack app from a template

The create command is how you create a next generation Slack app.

For this guide, we'll be creating a Slack app using the Deno Starter Template as a template:

slack create my-app --template https://github.com/slack-samples/deno-starter-template

The CLI creates an app project folder and fills it with the sample app code. Once it has finished, cd into your new project directory:

cd my-app

Then continue to the next step.

Step 4: Run the app in local development mode

While building your app, you can see your changes propagated to your workspace in real-time by running slack run within your app's directory.

slack run

When you execute slack run, you'll be asked to select a local environment:

? Choose a local environment
> Install to a new workspace

Since you've not installed your app to any workspaces, select Install to a new workplace. Then select the workspace you authenticated in.

The CLI will inform you there are no triggers installed for the app. Triggers are what cause workflows to run. A link trigger generates a Shortcut URL which, when posted in a channel or added as a bookmark, becomes a link.

Triggers are created from trigger definition files. The CLI will look for any trigger definition files and prompt you to select one. In this case, there is only one trigger: sample_trigger.ts. Select it.

? Choose a trigger definition file:
> triggers/sample_trigger.ts
  Do not create a trigger

Once your app's trigger is created, you will see the following output:

⚡ Trigger successfully created!

  Sample trigger (local) Ft0123ABC456 (shortcut)
  Created: 2023-01-01 12:00:00 -07:00 (1 second ago)
  Runnable by: everyone
  https://slack.com/shortcuts/Ft0123ABC456/XYZ123
...

The CLI will also start a local development server, syncing changes to your workspace's development version of your app. You'll know your local development server is up and running when your terminal window tells you it's Connected, awaiting events.

Step 5: Use your app

Grab the Shortcut URL you generated in the previous step and post it in a public channel in your workspace. You will see the shortcut unfurl with a "Start Workflow" button. Click the button to execute the shortcut.

In the modal that appears, select a channel, and enter a message. When you click the "Send message" button, you should see your message appear in the channel you specified.

When you want to turn off the local development server, use Ctrl+c in the command prompt.

Onward

At this point your CLI is fully authorized and ready to create new projects. It's time to choose the next path of adventure.

We have curated a collection of sample apps. Many have tutorials. All highlight features of next generation Slack apps. Learn how to:

design datastores to store data with the Virtual Running Buddies app.
send event-triggered automated messages with the Welcome Bot app.
create forms to receive user input with the Give Kudos app.

Each tutorial will expose you to many aspects of the next generation Slack platform. If you'd rather explore the documentation on your own, here are a few places to start. You can learn how to:

deploy your app so you don't need to run it locally.
build an app from scratch.
use next generation Slack apps in conjunction with other services, whether that's with third-party API calls or external authentication.