feat: install to $HOME/.local/bin if writes to /usr/local/bin fail (#188)

zimeg · lukegalbraithrussell · mwbrooks · web-flow · commit 4f4d77940bc2 · 2025-09-05T11:52:43.000-07:00
Co-authored-by: lukegalbraithrussell &lt;31357343+lukegalbraithrussell@users.noreply.github.com&gt;
Co-authored-by: Michael Brooks &lt;mbrooks@slack-corp.com&gt;
diff --git a/docs/guides/installing-the-slack-cli-for-mac-and-linux.md b/docs/guides/installing-the-slack-cli-for-mac-and-linux.md
@@ -25,7 +25,7 @@ Runtime installations are left to the developer and depend on the app being buil
 - [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started)
 
 <details>
-<summary>Optional: Use an alias for the Slack CLI binary</summary>
+<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 this `slack` binary to a different name to avoid errors during installation. The Slack CLI won't overwrite the existing one!
 
@@ -44,7 +44,7 @@ curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v
 </details>
 
 <details>
-<summary>Optional: Download a specific version</summary>
+<summary>Optional: download a specific version</summary>
 
 The latest Slack CLI version is installed by default, but a particular version can be pinned using the `-v` flag:
 
@@ -55,21 +55,39 @@ curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v
 </details>
 
 <details>
-<summary>Troubleshooting: Failed to create a symbolic link</summary>
+<summary>Troubleshooting: command not found</summary>
 
-The automated installer attempts to add the Slack CLI to a known directory in the path: `/usr/local/bin`.
+After running the Slack CLI installation script the `slack` command might not be available in the current shell. The download has often succeeded but a symbolic link to the command needs to be added to your path.
 
-Some machines protect this directory and elevated access might be needed for updated permissions. We do not recommend using `sudo` with the automated installer since unexpected side effects might place downloads in the wrong spot.
-
-If root access is available, create a symbolic link to the downloaded Slack CLI with the following command:
+Determine which shell you're using then update your shell profile with the following commands:
 
 ```sh
-sudo ln -s "$HOME/.slack/bin/slack" "/usr/local/bin/slack"
+basename "$SHELL"
 ```
 
-We recommend using an alias if another `slack` binary exists. To do this, change the alias used at the end of the symbolic link to something else that makes sense.
+- `bash`:
+
+  ```sh
+  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+  source ~/.bashrc
+  ```
+
+- `fish`:
+
+  ```sh
+  mkdir -p $HOME/.config/fish
+  echo 'fish_add_path $HOME/.local/bin' >> $HOME/.config/fish/config.fish
+  source $HOME/.config/fish/config.fish
+  ```
+
+- `zsh`:
+
+  ```sh
+  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+  source ~/.zshrc
+  ```
 
-For users without root permissions, please follow the **Manual Installation** steps.
+Once the profile is sourced, or a new shell is opened, the `slack` command should be available.
 
 </details>
 </TabItem>
@@ -97,7 +115,7 @@ In the following example we download the Slack CLI to the `.slack` directory and
 ln -s "$HOME/.slack/bin/slack" "$HOME/.local/bin/slack"
 ```
 
-We recommend using an alias if another `slack` binary exists. To do this, change the alias used at the end of the symbolic link to something else that makes sense.
+We recommend using an alias if another `slack` binary exists. To do this, change the alias used at the end of the symbolic link to something else that makes sense, or rename the moved download to something special.
 
 **4\. Verify that** `slack` **is installed and in your path.**
 
diff --git a/docs/guides/installing-the-slack-cli-for-windows.md b/docs/guides/installing-the-slack-cli-for-windows.md
@@ -29,7 +29,7 @@ Runtime installations are left to the developer and depend on the app being buil
 - [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started)
 
 <details>
-<summary>Optional: Use an alias for the Slack CLI binary</summary>
+<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 this `slack` binary to a different name to avoid errors during installation. The Slack CLI won't overwrite the existing one!
 
@@ -38,7 +38,7 @@ To do this, use the `-Alias` flag as described within the **Optional: Customize
 </details>
 
 <details>
-<summary>Optional: Customize installation using flags</summary>
+<summary>Optional: customize installation using flags</summary>
 
 There are several flags available to customize the installation. Since flags cannot be passed to remote scripts, you must first download the automated installer to a local file:
 
diff --git a/scripts/install-dev.sh b/scripts/install-dev.sh
@@ -43,6 +43,11 @@ if [ $(($# - $OPTIND)) -lt 1 ]; then
         fi
 fi
 
+# Emphasize text in a string
+bold() {
+        echo -en "\x1b[1m$1\x1b[0m"
+}
+
 # Print a message then pause for an amount of time
 delay() {
         local options="-e"
@@ -53,7 +58,7 @@ delay() {
         fi
 
         echo $options "$2"
-        sleep $1
+        sleep "$1"
 }
 
 # Replace /home/username/folder/file with ~/folder/file
@@ -72,12 +77,12 @@ version_lt() {
 install_slack_cli() {
         delay 0.6 "🥁 Hello and welcome! Now beginning to install the..."
 
-        delay 0.1 "\x1b[1m      ________ _     _    _____ _    __    _____ _    ________\x1b[0m"
-        delay 0.1 "\x1b[1m     /  ______/ |   / \ /  ____/ | /  /  /  ____/ | /___   __/\x1b[0m"
-        delay 0.1 "\x1b[1m    /______  |  |  / _ \  |   |      /   | |   |  |    |  |   \x1b[0m"
-        delay 0.1 "\x1b[1m     ____ /  |  |___ __ \ |____  |\  \   | |____  |__ _|  |___\x1b[0m"
-        delay 0.1 "\x1b[1m   /_______ /|______/  \_\ ____/_| \__\    _____/______/_____/\x1b[0m"
-        delay 0.2 "\x1b[0m"
+        delay 0.1 "$(bold "      ________ _     _    _____ _    __    _____ _    ________")"
+        delay 0.1 "$(bold "     /  ______/ |   / \ /  ____/ | /  /  /  ____/ | /___   __/")"
+        delay 0.1 "$(bold "    /______  |  |  / _ \  |   |      /   | |   |  |    |  |   ")"
+        delay 0.1 "$(bold "     ____ /  |  |___ __ \ |____  |\  \   | |____  |__ _|  |___")"
+        delay 0.1 "$(bold "   /_______ /|______/  \_\ ____/_| \__\    _____/______/_____/")"
+        delay 0.2 ""
 
         sleep 0.6
 
@@ -171,24 +176,14 @@ install_slack_cli() {
         delay 0.1 "📠 Removing packaged download files from $(home_path "$slack_cli_install_dir/slack-cli.tar.gz")"
         rm "$slack_cli_install_dir/slack-cli.tar.gz"
 
-        delay 0.1 "🔗 Adding a symbolic link from /usr/local/bin/$SLACK_CLI_NAME to $(home_path "$slack_cli_bin_path")"
-        if [ ! -d /usr/local/bin ]; then
-                echo -e "⚠️  The /usr/local/bin directory does not exist!"
-                echo -e "🔐 Please create /usr/local/bin directory first and try again..."
-                return 1
-        fi
-        if [ -w /usr/local/bin ]; then
-                ln -sf "$slack_cli_bin_path" "/usr/local/bin/$SLACK_CLI_NAME"
+        if [ -d "/usr/local/bin" ] && [ -w "/usr/local/bin" ]; then
+                local_bin_path="/usr/local/bin"
         else
-                echo -e "⚠️  Failed to create a symbolic link!"
-                delay 0.1 "🔖 The installer doesn't have write access to /usr/local/bin"
-                echo -e "🔐 Please check permission and try again..."
-                return 1
-        fi
-        if ! command -v "$SLACK_CLI_NAME" >/dev/null 2>&1; then
-                echo "📁 Manually add the Slack CLI command directory to your shell profile"
-                echo "   export PATH=\"$slack_cli_install_bin_dir:\$PATH\""
+                local_bin_path="$HOME/.local/bin"
+                mkdir -p "$local_bin_path"
         fi
+        delay 0.1 "🔗 Adding a symbolic link from $(home_path "$local_bin_path/$SLACK_CLI_NAME") to $(home_path "$slack_cli_bin_path")"
+        ln -sf "$slack_cli_bin_path" "$local_bin_path/$SLACK_CLI_NAME"
 }
 
 terms_of_service() {
@@ -215,8 +210,30 @@ next_step_message() {
         echo -e ""
         if command -v "$SLACK_CLI_NAME" >/dev/null 2>&1; then
                 echo -e "📺 Success! The Slack CLI (build: $SLACK_CLI_DEV_VERSION) is now installed!"
-                echo -e "🔐 Next, authorize your CLI in your workspace with \`$SLACK_CLI_NAME login\`"
+        else
+                echo -e "📚 Required manual setup"
+                echo -e "📝 Run the following commands to add the Slack CLI to your shell path:"
+                case "$(basename "$SHELL")" in
+                bash)
+                        echo -e "$(bold "   echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc")"
+                        echo -e "$(bold "   source ~/.bashrc")"
+                        ;;
+                fish)
+                        echo -e "$(bold "   mkdir -p \$HOME/.config/fish")"
+                        echo -e "$(bold "   echo 'fish_add_path \$HOME/.local/bin' >> \$HOME/.config/fish/config.fish")"
+                        echo -e "$(bold "   source \$HOME/.config/fish/config.fish")"
+                        ;;
+                zsh)
+                        echo -e "$(bold "   echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc")"
+                        echo -e "$(bold "   source ~/.zshrc")"
+                        ;;
+                *)
+                        echo -e "$(bold "   export PATH=\"$local_bin_path:\$PATH\"")"
+                        ;;
+                esac
         fi
+        echo -e "🔐 Next, authorize your CLI in your workspace with \`$(bold "$SLACK_CLI_NAME login")\`"
+        sleep 0.2
 }
 
 main() {
diff --git a/scripts/install.sh b/scripts/install.sh
@@ -40,6 +40,11 @@ if [ $(($# - $OPTIND)) -lt 1 ]; then
         fi
 fi
 
+# Emphasize text in a string
+bold() {
+        echo -en "\x1b[1m$1\x1b[0m"
+}
+
 # Print a message then pause for an amount of time
 delay() {
         local options="-e"
@@ -50,7 +55,7 @@ delay() {
         fi
 
         echo $options "$2"
-        sleep $1
+        sleep "$1"
 }
 
 # Replace /home/username/folder/file with ~/folder/file
@@ -69,12 +74,12 @@ version_lt() {
 install_slack_cli() {
         delay 0.6 "🥁 Hello and welcome! Now beginning to install the..."
 
-        delay 0.1 "\x1b[1m      ________ _     _    _____ _    __    _____ _    ________\x1b[0m"
-        delay 0.1 "\x1b[1m     /  ______/ |   / \ /  ____/ | /  /  /  ____/ | /___   __/\x1b[0m"
-        delay 0.1 "\x1b[1m    /______  |  |  / _ \  |   |      /   | |   |  |    |  |   \x1b[0m"
-        delay 0.1 "\x1b[1m     ____ /  |  |___ __ \ |____  |\  \   | |____  |__ _|  |___\x1b[0m"
-        delay 0.1 "\x1b[1m   /_______ /|______/  \_\ ____/_| \__\    _____/______/_____/\x1b[0m"
-        delay 0.2 "\x1b[0m"
+        delay 0.1 "$(bold "      ________ _     _    _____ _    __    _____ _    ________")"
+        delay 0.1 "$(bold "     /  ______/ |   / \ /  ____/ | /  /  /  ____/ | /___   __/")"
+        delay 0.1 "$(bold "    /______  |  |  / _ \  |   |      /   | |   |  |    |  |   ")"
+        delay 0.1 "$(bold "     ____ /  |  |___ __ \ |____  |\  \   | |____  |__ _|  |___")"
+        delay 0.1 "$(bold "   /_______ /|______/  \_\ ____/_| \__\    _____/______/_____/")"
+        delay 0.2 ""
 
         # Check if slack binary is already in user's system
         if [ -x "$(command -v "$SLACK_CLI_NAME")" ]; then
@@ -169,24 +174,14 @@ install_slack_cli() {
         delay 0.1 "📠 Removing packaged download files from $(home_path "$slack_cli_install_dir/slack-cli.tar.gz")"
         rm "$slack_cli_install_dir/slack-cli.tar.gz"
 
-        delay 0.1 "🔗 Adding a symbolic link from /usr/local/bin/$SLACK_CLI_NAME to $(home_path "$slack_cli_bin_path")"
-        if [ ! -d /usr/local/bin ]; then
-                echo -e "⚠️  The /usr/local/bin directory does not exist!"
-                echo -e "🔐 Please create /usr/local/bin directory first and try again..."
-                return 1
-        fi
-        if [ -w /usr/local/bin ]; then
-                ln -sf "$slack_cli_bin_path" "/usr/local/bin/$SLACK_CLI_NAME"
+        if [ -d "/usr/local/bin" ] && [ -w "/usr/local/bin" ]; then
+                local_bin_path="/usr/local/bin"
         else
-                echo -e "⚠️  Failed to create a symbolic link!"
-                delay 0.1 "🔖 The installer doesn't have write access to /usr/local/bin"
-                echo -e "🔐 Please check permission and try again..."
-                return 1
-        fi
-        if ! command -v "$SLACK_CLI_NAME" >/dev/null 2>&1; then
-                echo "📁 Manually add the Slack CLI command directory to your shell profile"
-                echo "   export PATH=\"$slack_cli_install_bin_dir:\$PATH\""
+                local_bin_path="$HOME/.local/bin"
+                mkdir -p "$local_bin_path"
         fi
+        delay 0.1 "🔗 Adding a symbolic link from $(home_path "$local_bin_path/$SLACK_CLI_NAME") to $(home_path "$slack_cli_bin_path")"
+        ln -sf "$slack_cli_bin_path" "$local_bin_path/$SLACK_CLI_NAME"
 }
 
 terms_of_service() {
@@ -213,8 +208,30 @@ next_step_message() {
         echo -e ""
         if command -v "$SLACK_CLI_NAME" >/dev/null 2>&1; then
                 echo -e "📺 Success! The Slack CLI is now installed!"
-                echo -e "🔐 Next, authorize your CLI in your workspace with \`$SLACK_CLI_NAME login\`"
+        else
+                echo -e "📚 Required manual setup"
+                echo -e "📝 Run the following commands to add the Slack CLI to your shell path:"
+                case "$(basename "$SHELL")" in
+                bash)
+                        echo -e "$(bold "   echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc")"
+                        echo -e "$(bold "   source ~/.bashrc")"
+                        ;;
+                fish)
+                        echo -e "$(bold "   mkdir -p \$HOME/.config/fish")"
+                        echo -e "$(bold "   echo 'fish_add_path \$HOME/.local/bin' >> \$HOME/.config/fish/config.fish")"
+                        echo -e "$(bold "   source \$HOME/.config/fish/config.fish")"
+                        ;;
+                zsh)
+                        echo -e "$(bold "   echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc")"
+                        echo -e "$(bold "   source ~/.zshrc")"
+                        ;;
+                *)
+                        echo -e "$(bold "   export PATH=\"$local_bin_path:\$PATH\"")"
+                        ;;
+                esac
         fi
+        echo -e "🔐 Next, authorize your CLI in your workspace with \`$(bold "$SLACK_CLI_NAME login")\`"
+        sleep 0.2
 }
 
 main() {
