DOCSEARCHbyAlgolia
Submit Docs

Slack CLI

repository·main·Indexed 42 days ago

https://github.com/slackapi/slack-cli

A command-line tool for managing Slack application lifecycles. It allows developers to call any Slack API method via the `api` command, manage app installations and deletions with the `app` command, and link local projects to existing Slack apps.

Tokens
98.7K
Snippets
370
Records
452
Agent score
51%

What's inside Slack CLI

  1. Overview of the Slack CLI

    main
    The Slack CLI is a command-line tool used to create and manage Slack apps. It is designed to be used alongside the Bolt frameworks (for JavaScript and Python) or the Deno Slack SDK to streamline the app development lifecycle.

  2. Use the Slack CLI

    main

    The slack command-line tool is used to create, run, and deploy Slack apps. The general syntax for the CLI is:

    slack <command> <subcommand> [flags]

    Common workflows include:

    • Authentication: slack login to authenticate your account.
    • Project Setup: slack create to start a new app or slack init to initialize an existing one.
    • Development: slack run to start a local development server.
    • Deployment: slack deploy to push your app to the Slack Platform.
    • Documentation: slack docs to open the official developer documentation.
    $ slack login   # Log in to your Slack account
$ slack create  # Create a new Slack app
$ slack init    # Initialize an existing Slack app
$ slack run     # Start a local development server
$ slack deploy  # Deploy to the Slack Platform
$ slack docs    # Open Slack developer docs

  3. Manage app functions with `slack function`

    main

    The slack function command allows you to inspect, configure, and manage the custom functions included in a Slack app. Functions are logic components used as steps within Workflow Builder. You can use this command to distribute functions to teammates or a workspace and lookup their distribution status.

    slack function <subcommand> [flags]

  4. Overview of Slack CLI Hooks

    main

    Hooks are the mechanism through which the Slack CLI and various SDKs (Deno, Bolt for JavaScript, Bolt for Python, Bolt for Java) communicate. Different CLI commands trigger specific hooks to perform tasks like deploying, running, or checking for updates.

    Common CLI commands and their associated hooks:

    CommandHook(s)
    slack deployget-manifest, build, deploy
    slack doctorcheck-update, doctor
    slack manifest infoget-manifest
    slack runget-manifest, start
    slack trigger createget-trigger
    slack upgradecheck-update, install-update

  5. Discovering hooks via the `get-hooks` hook

    main

    To support various SDKs (like Deno, Bolt, or Python) without hardcoding their specific requirements, the CLI uses a service-discovery pattern centered on the get-hooks hook.

    How it works

    1. The project contains a .slack/hooks.json file. By default, this file contains only the get-hooks definition.
    2. When the CLI needs to know what functionality an SDK supports, it invokes the get-hooks hook.
    3. The SDK responds with a JSON object containing all available hook definitions and their default configurations.

    Developer Workflow

    • Upgrading SDKs: You generally do not need to manually edit hooks.json when upgrading your SDK, as the SDK dictates the interface via get-hooks.
    • Overriding Hooks: If you need to provide a custom implementation for a specific hook, you can override that specific section within your hooks.json file.
    # Example structure of .slack/hooks.json
{
  "get-hooks": {
    "command": "path/to/your/sdk-hook-script"
  }
}

  6. Understand the Admin Approval flow for Enterprise Grid apps

    main

    By default, Admin Approval of Apps is enabled for all Slack Enterprise Grid organizations. When you attempt to install an app via the CLI, the following flow occurs:

    1. Request: The CLI prompts you to request access. A request containing the app's OAuth scopes and outgoing domains is sent to the Org Admin.
    2. Notification: Slackbot confirms the request was sent to you and notifies the Org Admin.
    3. Approval: An Org Admin approves the request.
    4. Completion: Slackbot notifies you of the approval. You can then attempt the installation again, and it should succeed.

    If your organization has disabled Admin Approval, the first installation attempt will succeed immediately.

  7. How the CLI resolves hook commands

    main

    When the CLI needs to execute a hook, it follows this resolution priority:

    1. hooks.json Override: If the hook key exists in the local hooks.json file, the CLI uses that command directly and stops.
    2. SDK Response: If the hook is not in hooks.json, the CLI looks for the hook in the hooks object returned by the get-hooks command. If found, it executes that command.
    3. Error: If the hook is found in neither location, the CLI returns an sdk_hook_not_found error.

  8. How hooks facilitate CLI-SDK communication

    main

    The Slack CLI and application SDKs communicate through a system of hooks defined in a project-level hooks.json file (typically located in the .slack directory).

    Mental Model

    • CLI Role: The CLI acts as the orchestrator. When specific events occur (e.g., generating a manifest, bundling code, or handling local development events), the CLI spawns a separate process to execute a hook script.
    • SDK Role: The SDK implements these scripts. This allows the CLI to remain language-agnostic, delegating complex, project-specific tasks to the SDK.
    • Execution: The CLI communicates with the hook process via STDIN (passing JSON objects) and command-line flags. It receives responses via the process's STDOUT.
    • Success/Failure: The CLI relies on the hook process's exit code. An exit code of 0 signals success; any other exit code signals failure, causing the CLI to surface an sdk_hook_invocation_failed error.

  9. CLI-SDK protocol negotiation

    main

    The rules for how the CLI and SDK communicate (how data is shaped and how diagnostic logs are separated from responses) are negotiated during the initial get-hooks handshake using the protocol-version field.

    Supported Protocol Versions

    • v1: The base and default protocol.
    • v2: Implements message boundaries. This version allows the SDK to clearly delineate actual hook responses from diagnostic data or logging sent to STDOUT.

    If protocol negotiation fails or the SDK does not adhere to the negotiated rules, the CLI will automatically fall back to the default protocol.

  10. Best practices for service tokens

    main

    Because service tokens are tied to the developer who requested them, it is recommended to create a dedicated "Slack service account" within your workspace. Using a service account instead of an individual user account:

    • Reduces security risks if a developer's token is compromised.
    • Prevents service interruptions when an individual leaves the organization.

  12. Install the Slack CLI on Windows via Automated Installation

    main

    The easiest way to install the Slack CLI on Windows is to run the automated installer from Windows PowerShell. This process installs the CLI and configures the command in your path.

    Note: PowerShell is a required prerequisite. If you do not have PowerShell 7 installed, you must install it first.

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