feat: add shell completions

refs #435

1 files changed, 35 insertions, 0 deletions

diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx
index d4708df6..4d2980fb 100644
--- a/docs/next/website/src/content/docs/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/cli-reference.mdx
@@ -19,6 +19,7 @@ herdr --no-session            # single-process escape hatch
 herdr --default-config        # print default config
 herdr update                  # download and install from the configured channel
 herdr update --handoff        # opt into live handoff for supported running servers
+herdr completion zsh          # generate a zsh completion script
 herdr channel show            # print stable or preview
 herdr channel set preview     # opt into preview builds
 herdr channel set stable      # return Linux/macOS direct installs to stable
@@ -45,6 +46,40 @@ herdr api schema --output herdr-api.schema.json
 with the installed binary. Use `--json` for the full JSON Schema document, or
 `--output PATH` to write that document to a file.
 
+## Shell completions
+
+```bash
+herdr completion zsh
+herdr completions zsh
+herdr completion bash
+herdr completion fish
+herdr completion powershell
+herdr completion elvish
+```
+
+`completion` prints the script to stdout. `completions` is an alias. For a
+temporary zsh session, load the script directly:
+
+```bash
+source <(herdr completion zsh)
+```
+
+For a persistent zsh setup, write the generated `_herdr` function somewhere on
+your `fpath` before `compinit` runs:
+
+```bash
+mkdir -p ~/.zfunc
+herdr completion zsh > ~/.zfunc/_herdr
+```
+
+Then make sure your `.zshrc` contains:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
 ## Server
 
 ```bash