diff --git a/docs/_sidebar.json b/docs/_sidebar.json index 05e65583..e69cbdec 100644 --- a/docs/_sidebar.json +++ b/docs/_sidebar.json @@ -14,12 +14,10 @@ "tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux", "tools/slack-cli/guides/installing-the-slack-cli-for-windows", "tools/slack-cli/guides/authorizing-the-slack-cli", - "tools/slack-cli/guides/using-slack-cli-with-bolt-frameworks", "tools/slack-cli/guides/using-slack-cli-on-an-enterprise-grid-organization", "tools/slack-cli/guides/running-slack-cli-commands", "tools/slack-cli/guides/developing-locally", "tools/slack-cli/guides/using-environment-variables-with-the-slack-cli", - "tools/slack-cli/guides/troubleshooting-slack-cli-errors", "tools/slack-cli/guides/setting-up-ci-cd-with-the-slack-cli", "tools/slack-cli/guides/deploying-with-the-slack-cli-and-github-actions", "tools/slack-cli/guides/removing-an-app", @@ -54,7 +52,7 @@ }, { "type": "doc", - "id": "tools/slack-cli/reference/hooks/index", + "id": "tools/slack-cli/reference/hooks", "label": "Hooks" } ] diff --git a/docs/guides/authorizing-the-slack-cli.md b/docs/guides/authorizing-the-slack-cli.md index 8f98ed7c..a49a9aeb 100644 --- a/docs/guides/authorizing-the-slack-cli.md +++ b/docs/guides/authorizing-the-slack-cli.md @@ -55,7 +55,7 @@ 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 [Bolt](/tools/slack-cli/guides/using-slack-cli-with-bolt-frameworks) and [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started) apps! +You're now ready to begin developing [Bolt](/quickstart) and [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started) apps! ### Version update notifications {#version-updates} diff --git a/docs/guides/installing-the-slack-cli-for-windows.md b/docs/guides/installing-the-slack-cli-for-windows.md index 254fbcf5..f01f4beb 100644 --- a/docs/guides/installing-the-slack-cli-for-windows.md +++ b/docs/guides/installing-the-slack-cli-for-windows.md @@ -7,9 +7,23 @@ slug: /tools/slack-cli/guides/installing-the-slack-cli-for-windows The Slack CLI is a useful tool for building Slack apps. This is your one-stop shop for installing this tool. -:::warning[PowerShell is required for installing the Slack CLI on Windows machines; an alternative shell will not work.] +
+Prerequisite: installing PowerShell + +PowerShell is required for installing the Slack CLI on Windows machines; an alternative shell will not work. + +Run the following command to install PowerShell 7 on your machine: + +```pwsh +iex "& { $(irm https://aka.ms/install-powershell.ps1) } -UseMSI" +``` + +The following articles may also be helpful should you run into any issues: + +- [Installing PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4) +- [How to install and update PowerShell 6](https://www.thomasmaurer.ch/2019/03/how-to-install-and-update-powershell-6/) -::: +
@@ -109,16 +123,3 @@ Using slack v4.0.1 - -## Installing PowerShell {#powershell} - -Run the following command to install PowerShell 7 on your machine: - -```pwsh -iex "& { $(irm https://aka.ms/install-powershell.ps1) } -UseMSI" -``` - -The following articles may also be helpful should you run into any issues: - -- [Installing PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4) -- [How to install and update PowerShell 6](https://www.thomasmaurer.ch/2019/03/how-to-install-and-update-powershell-6/) diff --git a/docs/guides/removing-an-app.md b/docs/guides/removing-an-app.md index d8d41bc8..9df8f1da 100644 --- a/docs/guides/removing-an-app.md +++ b/docs/guides/removing-an-app.md @@ -11,7 +11,7 @@ All good things must come to an end. You can `uninstall` your app if you need to ## Uninstall an app from your team {#uninstall-app} -Removing an app from a workspace doesn't have to be a permanent decision. Sometimes uninstalling the app to remove it's active presence in channels is sufficient! This option has the added benefit of reinstallation at a later time without recreating the entire app. +Removing an app from a workspace doesn't have to be a permanent decision. Sometimes uninstalling the app to remove its active presence in channels is sufficient! This option has the added benefit of reinstallation at a later time without recreating the entire app. To uninstall an app using the CLI, use the [`uninstall`](/tools/slack-cli/reference/commands/slack_app_uninstall/) command. Then, choose the workspace you want to remove the app from: diff --git a/docs/guides/troubleshooting-slack-cli-errors.md b/docs/guides/troubleshooting-slack-cli-errors.md deleted file mode 100644 index a8ae9307..00000000 --- a/docs/guides/troubleshooting-slack-cli-errors.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -sidebar_label: Troubleshooting errors -slug: /tools/slack-cli/guides/troubleshooting-slack-cli-errors ---- - -# Troubleshooting Slack CLI errors - -Troubleshooting errors can be tricky. There's a lot going on between your development environment, the Slack CLI, and your code! - -View the [full list of of errors in the reference](/tools/slack-cli/reference/errors). - -## VSCode and the Deno plugin {#vscode-deno} - -If you are using VSCode with the Deno plugin and you run into an error where Deno isn't being honored properly by VSCode, this is because VSCode treats the folder that's opened as the workspace root by default - -If you open a parent folder, the `.vscode/settings.json` file must be moved to the root of _that_ folder. VSCode requires that `deno.enable: true` is set in that `.vscode/settings.json` file, and VSCode only honors this setting if it's in the root of the project. - -Other common errors you may run into are static errors when opening a parent directory that contains one or many apps inside. These include: - -* _An import path cannot end with a '.ts' extension. Consider importing './workflows/greeting_workflow.js' instead_. - * This error is due to Deno not being set up correctly. -* _Relative import path "deno-slack-sdk/mod.ts" not prefixed with / or ./ or ../deno(import-prefix-missing)_. - * This error is due to an invalid import map. - -These errors occur because of that first one we covered — VSCode treats the folder that’s opened as the workspace root by default, and looks for the `.vscode/settings.json` and `deno.jsonc` files there. To resolve this, open the app folder directly, or set up your own workspace config in VSCode. - diff --git a/docs/guides/using-slack-cli-with-bolt-frameworks.md b/docs/guides/using-slack-cli-with-bolt-frameworks.md deleted file mode 100644 index 2d1ce1e8..00000000 --- a/docs/guides/using-slack-cli-with-bolt-frameworks.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_label: Using with Bolt frameworks ---- - -# Using the Slack CLI with Bolt frameworks - -You can use the Slack CLI to streamline development of apps using [Bolt for JavaScript](/tools/bolt-js) and [Bolt for Python](/tools/bolt-python). - -:::info[Feeling adventurous?] - -To create a Bolt app using features currently under development, refer to the [experiments](/tools/slack-cli/reference/experiments) page. - -::: - -## Getting started - -Creating a Bolt app via the Slack CLI is similar to creating other apps with the Slack CLI. Run the following command to begin: - -``` -slack create -``` - -Select an option from the following list. For this example, choose **Starter app**: - -```zsh -// highlight-next-line -> Starter app - Getting started Slack app -Automation app - Custom steps and workflows -AI app - Slack agents & assistants -View more samples -``` - -You will then be prompted to choose between **Bolt for JavaScript** or **Bolt for Python**. Choose your favorite flavor. - -Your app will be cloned from the respective [JavaScript](https://github.com/slack-samples/bolt-js-starter-template) or [Python](https://github.com/slack-samples/bolt-python-starter-template) project template on our Slack Platform Sample Code repository, and its project dependencies will be installed. Then, `cd` into your project folder. - -:::info[For Bolt for Python projects, automatic project dependency installation is currently unsupported, and will need to be done manually.] - -For more information, refer to [Getting started with Bolt for Python](/tools/bolt-python/getting-started). - -::: - -To run your new app, use the `slack run` command with the experiment flag as follows: - -``` -slack run -``` - -You'll be prompted to choose your team/workspace, and then your app should let you know that it's up and running. 🎉 - -## App manifest - -The Slack app manifest is the configuration of the app. The `manifest.json` file included with selected templates and samples reflects the features and permissions of your app. When you create an app with the CLI, the corresponding app and matching manifest can be found on [app settings](https://api.slack.com/apps). - -For Bolt apps created through the CLI, by default, the manifest source set in the `config.json` file is `remote`. This means that the manifest in your [app settings](https://api.slack.com/apps) is the source of truth. To modify the manifest (add new features, scopes, etc.), do so in the app settings. If you change the `config.json` to reflect a `local` manifest source and modify the local `manifest.json` file, the CLI will ask for confirmation before overriding the settings upstream on reinstall (run). This prompt appears if the app manifest on app settings differs from a known state saved in `.slack/cache`. There is not currently a dedicated manifest update command. - -In contrast, Deno apps created with the CLI have the manifest source configuration of `local` because those apps are not managed in the [app settings page](https://api.slack.com/apps). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 388f3fb2..c544b31e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,11 @@ # Slack CLI -The Slack command-line interface (CLI) allows you to create and manage Slack apps from the command line. Use it in combination with the Deno Slack SDK, or the Bolt frameworks for JavaScript and Python. +The Slack command-line interface (CLI) allows you to create and manage Slack apps from the command line. Use it in combination with the Bolt frameworks for JavaScript and Python, or the Deno Slack SDK. -Follow the installation guide for either [MacOS / Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) or [Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) to get set up. Then, follow the the [Authorization guide](/tools/slack-cli/guides/authorizing-the-slack-cli) to connect your workspace. +:::tip[Follow our [quickstart guide](/quickstart) to get set up with the Slack CLI and have a working app using the Bolt frameworks!] +::: + +For more detailed instructions, follow the installation guide for either [MacOS / Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) or [Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows). Then, follow the the [Authorization guide](/tools/slack-cli/guides/authorizing-the-slack-cli) to connect your workspace. ## Getting help diff --git a/docs/reference/hooks/index.md b/docs/reference/hooks.md similarity index 98% rename from docs/reference/hooks/index.md rename to docs/reference/hooks.md index 4d9d2d5d..520032f2 100644 --- a/docs/reference/hooks/index.md +++ b/docs/reference/hooks.md @@ -2,21 +2,16 @@ Communication between the CLI and the application SDK is managed by a project-level configuration file called `hooks.json`. This file is included in our app templates and defines script _hooks_. -Hooks are small scripts that are _executed_ by the CLI and _implemented_ by the SDK. These commands perform actions on the project. - -The `hooks.json` file allows the CLI and SDK a standard way to communicate while remaining decoupled and abstracted. This interface is a key design of the Slack CLI: many application and project level tasks are delegated from the CLI to the SDK. This delegation, decoupling and abstraction allows for language-agnostic SDK implementations. - -## Core concepts {#core-concepts} - -### Hooks: How the CLI and the SDK communicate {#communication} - -Hooks are scripts that execute when a specific event happens or a Slack CLI command is invoked. +Hooks are small scripts that are _executed_ by the CLI and _implemented_ by the SDK when a specific event happens or a Slack CLI command is invoked. These scripts perform actions on the project. A hook script may be triggered when: +- generating the app manifest. +- bundling function code before deployment to Slack infrastructure. +- handling an application event during local development runs. + +## Hooks: How the CLI and the SDK communicate {#communication} -- generating the app manifest -- bundling function code before deployment to Slack infrastructure -- handling an application event during local development runs +The `hooks.json` file allows the CLI and SDK a standard way to communicate while remaining decoupled and abstracted. This interface is a key design of the Slack CLI: many application and project level tasks are delegated from the CLI to the SDK. This delegation, decoupling and abstraction allows for language-agnostic SDK implementations. When an event occurs, the CLI will execute a hook script by spawning a separate process, possibly passing a JSON object through `STDIN` and/or other parameters via command line flags to the hook script process, and waiting for a JSON response via the spawned process’ `STDOUT`. This system is heavily inspired by git hooks. @@ -24,7 +19,7 @@ Since communication over hooks involves inter-process communication (one process Some hooks may return data as part of their functionality. The CLI will use the `STDOUT` and `STDERR` of the hook process to transmit its response. For details on how a hook process can shape its response, and delineate diagnostic data from response data, see the section on [protocol negotiation](#protocol). -### Discover hook scripts and default configuration with `get-hooks` {#discover} +## Discovering hook scripts and default configuration with `get-hooks` {#discover} In order for the CLI to reliably discover the hooks for the [Deno SDK](https://github.com/slackapi/deno-slack-sdk), [Bolt Frameworks](https://docs.slack.dev/tools/), and future community-driven SDKs, the CLI employs a service-discovery-like approach to querying the SDK for what functionality it supports. @@ -34,7 +29,7 @@ App developers do not need to edit or change their `hooks.json` file when upgrad Refer to the [CLI-SDK JSON interface](#interface-format) section for other examples. -### CLI-SDK protocol negotiation {#protocol} +## CLI-SDK protocol negotiation {#protocol} As the needs of app developers evolve, so will the interface and the rules of communication between the CLI and the SDK. These rules are negotiated via the initial `get-hooks` handshake and are specified via the `protocol-version` field returned by the SDK. @@ -45,7 +40,7 @@ At the time of writing, only two protocol versions are supported: If at any point protocol negotiation fails or does not adhere to the rules of communication, the CLI will fall back to using the default protocol. -#### Working implementations of protocol negotiation +### Working implementations of protocol negotiation - In the CLI: - [List of protocols supported by the CLI](https://github.com/slackapi/slack-cli/blob/d2349b6328820d2dcb01312abd4d8b3694f5137e/internal/hooks/protocol.go#L21-L22) @@ -57,13 +52,13 @@ If at any point protocol negotiation fails or does not adhere to the rules of co - [node-slack-sdk’s implementation](https://github.com/slackapi/node-slack-sdk/blob/main/packages/cli-hooks/src/protocols.js) - [python-slack-sdk’s implementation](https://github.com/slackapi/python-slack-hooks/blob/main/slack_cli_hooks/protocol/__init__.py) -### Ensuring backwards compatibility {#compatibility} +## Ensuring backwards compatibility {#compatibility} A hook’s name space (CLI) and its associated script implementation (SDK) will change over time. This can break backwards compatibility and require App Developers to juggle different CLI versions and SDK versions in order to maintain compatibility. It’s a frustrating situation that can ruin the developer experience. An additive approach to hook names or configuration settings allows us to keep hooks backwards-compatible for as long as possible and allows for a smoother upgrade experience. This approach also allows for tools to provide generous timeframes for supporting old hooks vs. new ones, allowing for deprecation windows and gradual rollouts. For configuration settings, an additive approach is accomplished by adding new configuration values that are not Golang defaults (e.g. bool defaults to false). -For example, the hook name `run-v2` may be the successor to the hook named `run`. The SDK can implement either hook and the CLI will trigger the latest version, possibly falling back to earlier versions of the hook where applicable. The CLI can also warn of impending removal of older hooks, providing hints to the developer when tooling behaviour changes. +For example, the hook name `run-v2` may be the successor to the hook named `run`. The SDK can implement either hook and the CLI will trigger the latest version, possibly falling back to earlier versions of the hook where applicable. The CLI can also warn of impending removal of older hooks, providing hints to the developer when tooling behavior changes. ## Hook specification {#specification}