Developing automations requires a paid plan. Don't have one? Join the Developer Program and provision a sandbox with access to all Slack features for free.
In the following guide, you'll install the Slack CLI and authorize it in your workspace. Then, you'll use the Slack CLI to scaffold a fully-functional automations app and run it locally.
Don't have a workspace yet? You can get up and running by provisioning a sandbox with an associated workspace by following this guide. Come on back when you're ready!
The minimum required Slack CLI version for Enterprise Grid as of September 19th, 2023 is v2.9.0. If you attempt to log in with an older version, you'll receive a cli_update_required error from the Slack API. Run slack upgrade to get the latest version.
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 workflow apps. If you have VSCode installed, the VSCode Deno extension will be installed.
If you have another CLI tool in your path called slack, you can rename the slack binary to a different name before you add it to your path.
To do this, pass the -s argument to the installer script:
curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s <your-preferred-alias>
The alias you use should come after any flags used in the installation script. For example, if you use both flags noted below to pass a version and skip the Deno installation, your install script might look like this:
curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v 2.1.0 -d <your-preferred-alias>
You can also copy the Slack CLI into any folder that is already in your path (such as /usr/local/bin—you can useecho $PATH to find these), or add a new folder to your path by listing the folder you installed the Slack CLI to in /etc/paths.
If you don't rename the slack binary to a different name, the installation script will detect existing binaries named slack and bail if it finds one—it will not overwrite your existing slack binary.
There are two optional flags available to customize the installation.
-v. The absence of this flag will ensure the latest Slack CLI version is installed.curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v 2.1.0
-d flag, like this:curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -d
Error: Failed to create a symbolic link! The installer doesn't have write access to /usr/local/bin. Please check permission and try again...
Solution: Sudo actions within the scripts were removed so as not to create any security concerns. The $HOME env var is updated to /root — however, the installer is using $HOME for both Deno and the SDK install, which causes the whole install to be placed under /root, making both Deno and the SDK unusuable for users without root permissions.
sudo mkdir -p -m 775 /usr/local/bin, then sudo ln -sf "$slack_cli_bin_path" "/usr/local/bin/$SLACK_CLI_NAME" where $slack_cli_bin_path is typically $HOME/.slack/bin/slack and $SLACK_CLI_NAME is typically the alias (by default it’s slack).sudo curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash. In this case, the script is executed as root.Run the automated installer from Windows PowerShell:
irm https://downloads.slack-edge.com/slack-cli/install-windows.ps1 | iex
PowerShell is required for installing the Slack CLI on Windows machines; an alternative shell will not work.
This will install the Slack CLI and all required dependencies, including Deno, the runtime environment for workflow apps. If you have VSCode installed, the VSCode Deno extension will be installed.
If you have another CLI tool in your path called slack, you can rename the slack binary to a different name before you add it to your path.
To do this, copy the Slack CLI into any folder that is already in your path, or add a new folder to your path by listing the folder you installed the Slack 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 then entering the following command:
rundll32.exe sysdm.cpl,EditEnvironmentVariables
You can also use the -Alias flag as decribed within Optional: customize installation using flags.
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
Error: Not working? You may need to update your session's Language Mode.
Solution: 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: ps $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: ps $ExecutionContext.SessionState.LanguageMode = "FullLanguage"
1. Download and install Deno. Refer to Install Deno for more details.
2. Verify that Deno is installed and in your path.
The minimum version of Deno runtime required for developing workflow apps is currently at version 1.37.0.
$ deno --version
deno 1.31.1* (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.
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. See your OS-specific installation tab for more details.
6. Verify that slack is installed and in your path.
$ slack version
Using slack v2.31.0
7. Verify that all dependencies have been installed.
Run the following command:
$ slack doctor
A few notes about hooks
If you have upgraded your CLI version but your deno-slack-hooks version is less than v1.3.0, when running slack doctor, you will see the following near the end of the output:
✔ Configurations (your project's CLI settings)
Project ID: 1a2b3c4d-ef5g-67hi-8j9k1l2m3n4o
✘ Runtime (foundations for the application)
Error: The `doctor` hook was not found (sdk_hook_not_found)
Suggestion: Ensure this hook is implemented in your `slack.json`
✔ Dependencies (requisites for development)
deno_slack_hooks: 1.2.3 → 1.3.0 (supported version)
In addition, if you attempt to run the slack run command without this dependency installed, you will see a similar error in your console:
🚫 The `start` script was not found (sdk_hook_not_found)
💡 Suggestion
Hook scripts are defined in the Slack configuration file ('slack.json').
Every app requires a 'slack.json' file and you can find a working example at:
https://github.com/slack-samples/deno-starter-template/blob/main/slack.json
Ensure that deno-slack-hooks is installed at the project level and that the version is not less than v1.3.0.
8. Install the VSCode extension for Deno (recommended).
With the Slack CLI installed, authorize the Slack 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 challenge 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 Slack 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 Slack 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
Authorization Level: Workspace
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 workfow apps! In the next step, we'll get started with a sample app.
Evaluate third-party apps
Exercise caution when using third-party applications and automations (those outside of slack-samples). Review all source code created by third-parties before running slack create or slack deploy.
The create command is how you create a workflow 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 Slack 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.
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 or organization
Since you've not installed your app to any workspaces, select Install to a new workplace. Then select the workspace you authenticated in.
The Slack CLI will attempt to list any triggers, and in this case, will inform you there are no existing 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 Slack CLI will then 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)
Collaborators:
You! @You U123ABC456DE
Can be found and used by:
everyone in the workspace
https://slack.com/shortcuts/Ft0123ABC456/XYZ123
The Slack 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.
Grab the Shortcut URL you generated in the previous step and paste 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.
At this point your Slack 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 workflow apps. Learn how to:
Each tutorial will expose you to many aspects of the workflow automations. If you'd rather explore the documentation on your own, here are a few places to start. You can learn how to:
Have 2 minutes to provide some feedback?
We'd love to hear about your experience building Slack automations. Please complete our short survey so we can use your feedback to improve.