docs: open source Slack CLI docs

docs/guides/authorizing-the-slack-cli.md

@@ -0,0 +1,122 @@
+---
+slug: /slack-cli/guides/authorizing-the-slack-cli
+---
+
+# Authorizing the Slack CLI {#authorize-cli}
+
+Once you have the Slack CLI installed for either [Windows](/slack-cli/guides/installing-the-slack-cli-for-windows) or [Mac/Linux](/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux), authorize the Slack CLI in your workspace with the following command:
+
+```zsh
+slack login
+```
+
+## Authorization ticket {#ticket}
+
+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:
+
+```zsh
+$ 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 **Confirm** in the modal to continue to the next step.
+
+A new modal with a challenge code will appear. Copy that challenge code, and paste it back into your terminal:
+
+```zsh
+? 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:
+
+```zsh
+$ 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 workflow apps!
+
+### Version update notifications {#version-updates}
+
+Once a day, the Slack CLI checks for updates after running any command. When an update is available, a notification will be displayed with a link where you can find and download the new version.
+
+Update notifications can be disabled using a command-line flag or an environment variable. When running any command, you can append the `--skip-update` or `-s` flag. Alternatively, you can set the `SLACK_SKIP_UPDATE` environment variable and assign it any value.
+
+## CI/CD authorization {#ci-cd}
+
+Setting up a CI/CD pipeline requires authorization using a service token. Service tokens are **long-lived, non-rotatable user tokens** — they won't expire, so they can be used to perform any Slack CLI action without the need to refresh tokens.
+
+To get a service token, you'll use the `slack auth token` command to get a `slackauthticket`, which you'll copy and paste into your workspace to exchange for the service token. The service token will not be saved to your `credentials.json` file; instead, it is presented in the terminal for you to copy and paste for use in your CI/CD pipeline. Once copied, you'll use the `slack login --auth <your-service-token>` command to authorize your Slack CLI. Detailed instructions are below.
+
+:::info 
+
+The service token will not conflict with your regular authentication token; you can continue using your regular authentication token within the Slack CLI while using the service token for your CI/CD pipeline.
+
+:::
+
+### Best practices for service tokens {#best-practices-tokens}
+
+Since a service token obtained via the Slack CLI is tied to the developer who requested it, it is recommended &mdash; especially for those who are part of large enterprises &mdash; to create a "Slack service account" within your workspace for the purpose of obtaining service tokens.
+
+This "Slack service account" will be identical to other user accounts, but service tokens can now be associated with this account rather than an individual organization member. This can reduce the security risk of an individual developer's token being compromised, as well as lessening the dependence on a single individual for service token access and management.
+
+### Obtaining a service token {#obtain-token}
+
+Run the following  command to get a `slackauthticket`:
+```
+slack auth token
+```
+
+Then, copy and paste the `/slackauthticket <your-auth-ticket>` slash command into the message composer anywhere within your Slack workspace.
+
+Copy the given challenge code, and paste it into the Slack CLI prompt.
+
+Securely store the given service token, as this authorization information will _not_ be saved to your local `credentials.json` file.
+
+### Using a service token {#use-token}
+
+Run the following command to authorize your Slack CLI with the service token:
+
+```
+slack --token <your-service-token>
+```
+
+The Slack CLI will attempt to verify the token and use it to log in.
+
+The `--token` global flag allows you to pass the service token with any Slack CLI command; for example:
+
+```
+slack deploy --token <your-service-token>
+```
+
+### Revoking a service token {#revoke-token}
+
+Run the following command to revoke a service token:
+
+```
+slack auth revoke --token <your-service-token>
+```

docs/guides/deploying-with-the-slack-cli-and-github-actions.md

@@ -0,0 +1,97 @@
+---
+sidebar_label: Deploying with GitHub Actions
+slug: /slack-cli/guides/deploying-the-slack-cli-with-github-actions
+---
+
+# Deploying with the Slack CLI & GitHub Actions
+
+This tutorial demonstrates how to use CI/CD to facilitate automatic deployments when code changes are pushed to GitHub.
+
+Before we begin, you'll need to do the following:
+
+* Create a new GitHub repository — any name will do.
+* [Install](/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) the Slack CLI on your machine.
+* [Authorize](/slack-cli/guides/authorizing-the-slack-cli) the Slack CLI to your workspace.
+
+Once those steps have been completed, we're ready to move on to building our automated deployment app.
+
+## Create a new app {#create}
+
+Run `slack create` to create a new Slack app project. Select a template to build from; in this case, hit **Enter** to choose the default `Issue submission` template.
+
+Refer to [Create or remove an app](/deno-slack-sdk/guides/creating-an-app) for more details.
+
+## Initial deploy {#initial-deploy}
+
+Run `slack deploy` to manually deploy the new app to your workspace for the first time. During the process, you'll be prompted to create a link trigger. Refer to [Link triggers](/deno-slack-sdk/guides/creating-link-triggers) for more details.
+
+Once created, copy the link and share it in a Slack channel. You'll see a button appear to start the workflow; click it to verify that the default workflow is functioning properly.
+
+## Obtain a service token {#obtain-service-token}
+
+To automate subsequent deployments, we'll need to obtain a [service token](/slack-cli/guides/authorizing-the-slack-cli#ci-cd) for the app. 
+
+Navigate to the root directory of your project and run the `slack auth token` command. You'll be prompted to run a slash command called `slackauthticket`, similar to the way you authorized your app earlier. Copy that command and run it in Slack, then copy the challenge code you receive and enter it into your terminal. You'll see a service token that starts with `xoxp-` — make sure you save this token. Note that this token is connected to a specific workspace and organization.
+
+## Add your service token to GitHub as a secret {#add-service-token}
+
+In your GitHub repository, navigate to **Settings** > **Secrets and variables** > **Actions** and click **New repository secret** to add a new secret as follows:
+
+* Name: SLACK_SERVICE_TOKEN
+* Secret: the `xoxp-` prefixed service token obtained above
+
+Be sure to save your changes!
+
+## Add a new deployment file with your GitHub actions workflow {#add-deployment-file}
+
+Create a folder called `.github/workflows/` and add a new file called `deployment.yml` with the following content:
+
+```yml
+name: Slack App Deployment
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install Deno runtime
+      uses: denoland/setup-deno@v1
+      with:
+        deno-version: v1.x
+
+    - name: Install Slack CLI
+      if: steps.cache-slack.outputs.cache-hit != 'true'
+      run: |
+        curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
+
+    - name: Deploy the app
+      env:
+        SLACK_SERVICE_TOKEN: ${{ secrets.SLACK_SERVICE_TOKEN }}
+      run: |
+        cd gh-actions-demo/
+        slack deploy -s --token $SLACK_SERVICE_TOKEN
+```
+
+This file instructs the Slack CLI to deploy the latest revision of your repository to the Slack platform when any changes are pushed to the main branch. 
+
+You can go with any other Linux option you prefer for the GitHub-hosted runner; refer to [About GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#viewing-available-runners-for-a-repository) for more details.
+
+## Test it out {#test}
+
+To test it out, make a PR and push some changes to the main branch. If the GitHub Actions job successfully completes, your app should now be available in your workspace.
+
+Your GitHub repository is now set up for team collaboration! Your team members can review code changes by submitting PRs, and once these are merged into the main branch, the changes will be deployed automatically. Should you need to reverse a deployment automatically, you can create a reverting PR and quickly merge that.
+
+## Further reading {#read}
+
+Check out these articles to expand your knowledge and skills of automated deployments and the Slack CLI: 
+
+➡️ [CI/CD overview and setup](https://tools.slack.dev/slack-cli/guides/setting-up-ci-cd-with-the-slack-cli)
+
+➡️ [CI/CD authorization](/slack-cli/guides/authorizing-the-slack-cli#ci-cd)

docs/guides/installing-the-slack-cli-for-mac-and-linux.md

@@ -0,0 +1,168 @@
+---
+sidebar_label: Installing for MacOS & Linux
+slug: /slack-cli/guides/installing-the-slack-cli-for-mac-and-linux
+---
+
+# Installing the Slack CLI for Mac & Linux
+
+
+The Slack CLI is a set of tools critical to building workflow apps. This is your one-stop shop for those tools.
+
+✨ **If you've not used the Slack CLI before, we recommend following our [Deno Slack SDK getting started guide](/deno-slack-sdk/guides/getting-started) instead**. We'll still get your wagon loaded up before you depart for the trail, but we'll also give you some additional guidance.
+
+⤵️ **If you need to authorize the Slack CLI, [go here](/slack-cli/guides/authorizing-the-slack-cli)**.
+
+:::info
+
+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.
+
+:::
+
+<Tabs groupId="installation">
+<TabItem value="Automated" label="Automated Installation">
+
+**Run the automated installer from your terminal window:**
+
+```zsh
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
+```
+
+This will install the Slack CLI and all required dependencies, including [Deno](/deno-slack-sdk/guides/installing-deno),
+the runtime environment for workflow apps. If you have VSCode installed,
+the [VSCode Deno
+extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno)
+will be installed.
+<details>
+<summary>Optional: Use an alias for the Slack CLI binary</summary>
+
+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:
+
+```zsh
+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`&mdash;you can use`echo $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&mdash;it will not overwrite your existing `slack` binary.
+
+</details>
+
+<details>
+<summary>Optional: customize installation using flags</summary>
+
+There are two optional flags available to customize the installation.
+
+1. Specify a version you'd like to install using the version flag, `-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
+```
+
+2. Skip the Deno installation by using the `-d` flag, like this:
+```
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -d
+```
+</details>
+
+<details>
+<summary>Troubleshooting</summary>
+
+#### Errors
+
+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` &mdash; 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 unusable for users without root permissions.
+* For users who do not have root permissions, run the sudo actions manually as follows: `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`).
+* For users who do have root permissions, you can run the installation script as `sudo curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash`. In this case, the script is executed as root.
+
+</details>
+</TabItem>
+<TabItem value="Manual" label="Manual Installation">
+
+**1\. Download and install [Deno](https://deno.land).** Refer to [Install Deno](/deno-slack-sdk/guides/installing-deno) for more details.
+
+**2\. Verify that Deno is installed and in your path.**
+
+The minimum version of Deno runtime required is currently version 1.37.0.
+
+```bash
+$ deno --version
+deno 1.46.2* (release, x86_64-apple-darwin)
+v8 10.*
+typescript 4.*
+```
+
+**3\. Download and install
+   [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), a
+   dependency of the** `slack` **CLI.**
+
+**4\. Download the** `slack` **CLI installer for your environment.**
+
+<ts-icon class="ts_icon_apple"></ts-icon> &nbsp; <a href="https://downloads.slack-edge.com/slack-cli/slack_cli_3.0.4_macOS_64-bit.tar.gz"><strong>Download for macOS (.tar.gz)</strong></a>
+
+<ts-icon class="ts_icon_plug"></ts-icon> &nbsp; <a href="https://downloads.slack-edge.com/slack-cli/slack_cli_3.0.4_linux_64-bit.tar.gz"><strong>Download for Linux (.tar.gz)</strong></a>
+
+**5\. Add the** `slack` **CLI to your path.**
+
+:::info
+  <p><strong>Existing</strong> <code>slack</code> <strong>binary in path?</strong></p>
+  <p>If you have another CLI tool in your path called <code>slack</code>, we recommend renaming our slack binary to a different name before adding it to your path. See the <strong>Automated installation</strong> tab for more details.</p>
+:::
+
+**6\. Verify that** `slack` **is installed and in your path.**
+
+```
+$ slack version
+Using slack v3.0.4
+```
+
+**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](/deno-slack-sdk/guides/installing-deno#vscode) (recommended).**
+
+</TabItem>
+</Tabs>