diff --git a/.goreleaser/mac.yml b/.goreleaser/mac.yml
index 24b8d046..18e4dece 100644
--- a/.goreleaser/mac.yml
+++ b/.goreleaser/mac.yml
@@ -13,7 +13,7 @@ builds:
       - -s -w -X github.com/hookdeck/hookdeck-cli/pkg/version.Version={{.Version}}
     binary: hookdeck
     env:
-      - CGO_ENABLED=1
+      - CGO_ENABLED=0
     main: ./main.go
     goos:
       - darwin
@@ -23,6 +23,8 @@ builds:
     ldflags:
       - -s -w -X github.com/hookdeck/hookdeck-cli/pkg/version.Version={{.Version}}
     binary: hookdeck
+    env:
+      - CGO_ENABLED=0
     main: ./main.go
     goos:
       - darwin
diff --git a/README.md b/README.md
index c580f26b..8dc806fa 100644
--- a/README.md
+++ b/README.md
@@ -460,12 +460,20 @@ hookdeck version
 
 ### Completion
 
-Configure auto-completion for Hookdeck CLI. It is run on install when using Homebrew or Scoop. You can optionally run this command when using the binaries directly or without a package manager.
+Generate a shell completion script for the Hookdeck CLI. When installed via Homebrew or Scoop, completions are configured automatically.
+
+To enable completions for the current shell session:
 
 ```sh
-hookdeck completion
+# bash
+source <(hookdeck completion --shell bash)
+
+# zsh
+source <(hookdeck completion --shell zsh)
 ```
 
+To install completions permanently, redirect the output to your shell's completion directory. See `hookdeck completion --help` for examples.
+
 ### Running in CI
 
 If you want to use Hookdeck in CI for tests or any other purposes, you can use your HOOKDECK_API_KEY to authenticate and start forwarding events.
diff --git a/REFERENCE.md b/REFERENCE.md
index 4c268fe7..72b673cf 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -694,14 +694,24 @@ The connection will queue incoming events until unpaused.
 **Usage:**
 
 ```bash
-hookdeck gateway connection pause <connection-id>
+hookdeck gateway connection pause <connection-id-or-name>
 ```
 
 **Arguments:**
 
 | Argument | Type | Description |
 |----------|------|-------------|
-| `connection-id` | `string` | **Required.** Connection ID |
+| `connection-id-or-name` | `string` | **Required.** Connection ID or name |
+
+**Examples:**
+
+```bash
+# Pause by connection ID
+hookdeck gateway connection pause web_abc123
+
+# Pause by connection name
+hookdeck gateway connection pause my-connection
+```
 ### hookdeck gateway connection unpause
 
 Resume a paused connection.
@@ -711,14 +721,24 @@ The connection will start processing queued events.
 **Usage:**
 
 ```bash
-hookdeck gateway connection unpause <connection-id>
+hookdeck gateway connection unpause <connection-id-or-name>
 ```
 
 **Arguments:**
 
 | Argument | Type | Description |
 |----------|------|-------------|
-| `connection-id` | `string` | **Required.** Connection ID |
+| `connection-id-or-name` | `string` | **Required.** Connection ID or name |
+
+**Examples:**
+
+```bash
+# Unpause by connection ID
+hookdeck gateway connection unpause web_abc123
+
+# Unpause by connection name
+hookdeck gateway connection unpause my-connection
+```
 <!-- GENERATE_END -->
 ## Sources
 
@@ -1872,7 +1892,21 @@ Query Event Gateway metrics (events, requests, attempts, queue depth, pending ev
 
 ## Completion
 
-Generate bash and zsh completion scripts. This command runs on install when using Homebrew or Scoop. You can optionally run it when using binaries directly or without a package manager.
+Generate a shell completion script for hookdeck.
+
+The script is written to standard output. To enable completions in the
+current shell session, source the output:
+
+  $ source <(hookdeck completion `--shell` bash)
+  $ source <(hookdeck completion `--shell` zsh)
+
+To install completions permanently, redirect the output to your shell's
+completion directory:
+
+  bash:  hookdeck completion `--shell` bash > /usr/local/etc/bash_completion.d/hookdeck
+  zsh:   hookdeck completion `--shell` zsh > "${fpath[1]}/_hookdeck"
+
+When installed via Homebrew or Scoop, completions are installed automatically.
 
 **Usage:**
 
diff --git a/pkg/cmd/completion.go b/pkg/cmd/completion.go
index d17293dc..ddb80007 100644
--- a/pkg/cmd/completion.go
+++ b/pkg/cmd/completion.go
@@ -7,8 +7,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"runtime"
-
 	"github.com/hookdeck/hookdeck-cli/pkg/validators"
 )
 
@@ -24,12 +22,26 @@ func newCompletionCmd() *completionCmd {
 	cc.cmd = &cobra.Command{
 		Use:   "completion",
 		Short: "Generate bash and zsh completion scripts",
-		Long:  "Generate bash and zsh completion scripts. This command runs on install when using Homebrew or Scoop. You can optionally run it when using binaries directly or without a package manager.",
-		Args:  validators.NoArgs,
+		Long: `Generate a shell completion script for hookdeck.
+
+The script is written to standard output. To enable completions in the
+current shell session, source the output:
+
+  $ source <(hookdeck completion --shell bash)
+  $ source <(hookdeck completion --shell zsh)
+
+To install completions permanently, redirect the output to your shell's
+completion directory:
+
+  bash:  hookdeck completion --shell bash > /usr/local/etc/bash_completion.d/hookdeck
+  zsh:   hookdeck completion --shell zsh > "${fpath[1]}/_hookdeck"
+
+When installed via Homebrew or Scoop, completions are installed automatically.`,
+		Args: validators.NoArgs,
 		Example: `  $ hookdeck completion --shell zsh
   $ hookdeck completion --shell bash`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return selectShell(cc.shell)
+			return runCompletion(cmd, cc.shell)
 		},
 	}
 
@@ -38,80 +50,19 @@ func newCompletionCmd() *completionCmd {
 	return cc
 }
 
-const (
-	instructionsHeader = `
-Suggested next steps:
----------------------`
-
-	zshCompletionInstructions = `
-1. Move ` + "`hookdeck-completion.zsh`" + ` to the correct location:
-    mkdir -p ~/.hookdeck
-    mv hookdeck-completion.zsh ~/.hookdeck
-
-2. Add the following lines to your ` + "`.zshrc`" + ` enabling shell completion for Hookdeck:
-    fpath=(~/.hookdeck $fpath)
-    autoload -Uz compinit && compinit -i
-
-3. Source your ` + "`.zshrc`" + ` or open a new terminal session:
-    source ~/.zshrc`
-
-	bashCompletionInstructionsMac = `
-Set up bash autocompletion on your system:
-1. Install the bash autocompletion package:
-     brew install bash-completion
-2. Follow the post-install instructions displayed by Homebrew; add a line like the following to your bash profile:
-     [[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
-
-Set up Hookdeck autocompletion:
-3. Move ` + "`hookdeck-completion.bash`" + ` to the correct location:
-    mkdir -p ~/.hookdeck
-    mv hookdeck-completion.bash ~/.hookdeck
-
-4. Add the following line to your bash profile, so that Hookdeck autocompletion will be enabled every time you start a new terminal session:
-    source ~/.hookdeck/hookdeck-completion.bash
-
-5. Either restart your terminal, or run the following command in your current session to enable immediately:
-    source ~/.hookdeck/hookdeck-completion.bash`
-
-	bashCompletionInstructionsLinux = `
-1. Ensure bash autocompletion is installed on your system. Often, this means verifying that ` + "`/etc/profile.d/bash_completion.sh`" + ` exists, and is sourced by your bash profile; the location of this file varies across distributions of Linux.
-
-2. Move ` + "`hookdeck-completion.bash`" + ` to the correct location:
-    mkdir -p ~/.hookdeck
-    mv hookdeck-completion.bash ~/.hookdeck
-
-3. Add the following line to your bash profile, so that Hookdeck autocompletion will be enabled every time you start a new terminal session:
-    source ~/.hookdeck/hookdeck-completion.bash
-
-4. Either restart your terminal, or run the following command in your current session to enable immediately:
-    source ~/.hookdeck/hookdeck-completion.bash`
-)
-
-func selectShell(shell string) error {
+func runCompletion(cmd *cobra.Command, shell string) error {
 	selected := shell
 	if selected == "" {
 		selected = detectShell()
 	}
 
-	switch {
-	case selected == "zsh":
-		fmt.Println("Detected `zsh`, generating zsh completion file: hookdeck-completion.zsh")
-		err := rootCmd.GenZshCompletionFile("hookdeck-completion.zsh")
-		if err == nil {
-			fmt.Printf("%s%s\n", instructionsHeader, zshCompletionInstructions)
-		}
-		return err
-	case selected == "bash":
-		fmt.Println("Detected `bash`, generating bash completion file: hookdeck-completion.bash")
-		err := rootCmd.GenBashCompletionFile("hookdeck-completion.bash")
-		if err == nil {
-			if runtime.GOOS == "darwin" {
-				fmt.Printf("%s%s\n", instructionsHeader, bashCompletionInstructionsMac)
-			} else if runtime.GOOS == "linux" {
-				fmt.Printf("%s%s\n", instructionsHeader, bashCompletionInstructionsLinux)
-			}
-		}
-		return err
+	out := cmd.OutOrStdout()
+
+	switch selected {
+	case "zsh":
+		return rootCmd.GenZshCompletion(out)
+	case "bash":
+		return rootCmd.GenBashCompletion(out)
 	default:
 		return fmt.Errorf("could not automatically detect your shell. Please run the command with the `--shell` flag for either bash or zsh")
 	}
diff --git a/scripts/completions.sh b/scripts/completions.sh
index e735cc52..d736fec0 100755
--- a/scripts/completions.sh
+++ b/scripts/completions.sh
@@ -8,18 +8,11 @@ set -e
 rm -rf completions
 mkdir completions
 
-# Use 'go run .' to compile and run the CLI to generate completions
-# This works on any platform that can build Go code
-# The completion command writes files to the current directory, so we cd into completions/
 echo "Generating bash completion..."
-(cd completions && go run .. completion --shell bash)
+go run . completion --shell bash > completions/hookdeck.bash
 
 echo "Generating zsh completion..."
-(cd completions && go run .. completion --shell zsh)
-
-# Rename the generated files to match GoReleaser expectations
-mv completions/hookdeck-completion.bash completions/hookdeck.bash
-mv completions/hookdeck-completion.zsh completions/_hookdeck
+go run . completion --shell zsh > completions/_hookdeck
 
 # Fish completion is not currently supported by the CLI
 # If it gets added in the future, uncomment this:
@@ -27,4 +20,4 @@ mv completions/hookdeck-completion.zsh completions/_hookdeck
 # go run . completion --shell fish > completions/hookdeck.fish
 
 echo "✅ Completions generated successfully in completions/"
-ls -lh completions/
\ No newline at end of file
+ls -lh completions/