feat(cli): add dub completion <shell> and dub man

README.md

@@ -755,6 +755,30 @@ Undo the last `dub create`, `dub restack`, `dub rename`, `dub move`, `dub pop`,
 dub undo
 ```
 
+### `dub completion <shell>` and `dub man`
+
+Generate shell completions and a man page from the live commander definitions.
+
+```bash
+# bash, zsh, fish — pipe into the location your shell loads completions from
+dub completion bash > ~/.local/share/bash-completion/completions/dub
+dub completion zsh > "${fpath[1]}/_dub"
+dub completion fish > ~/.config/fish/completions/dub.fish
+
+# roff man page — drop into any MANPATH location
+mkdir -p ~/.local/share/man/man1
+dub man > ~/.local/share/man/man1/dub.1
+man dub
+```
+
+Completions cover top-level subcommands, nested subcommands and their flags
+(e.g. `dub config ai-provider <Tab>`), per-command flags, and local branch
+names for `co`/`checkout`, `delete`, `track`, and `untrack`. Branch-valued
+flags (`--parent`, `--branch`, `--before`, `--after`) also complete local
+branches. Regenerate after upgrading `dub` to pick up new commands and
+flags. Full docs:
+[`apps/docs/content/docs/guides/shell-integration.mdx`](apps/docs/content/docs/guides/shell-integration.mdx).
+
 ### `dub skills`
 
 Install or remove packaged agent skills.

apps/docs/content/docs/guides/shell-integration.mdx

@@ -115,6 +115,65 @@ Enable the plugin in `~/.zshrc`:
 plugins=(... dubstack)
 ```
 
+## Shell completions
+
+`dub completion <shell>` writes a completion script to stdout. Pipe it into
+the location your shell loads completions from:
+
+```bash
+# bash
+dub completion bash > ~/.local/share/bash-completion/completions/dub
+
+# zsh — write to a user-owned directory you put on $fpath before compinit
+mkdir -p ~/.zsh/completions
+dub completion zsh > ~/.zsh/completions/_dub
+# then ensure these two lines are in ~/.zshrc before any `compinit` call:
+#   fpath=(~/.zsh/completions $fpath)
+#   autoload -Uz compinit && compinit
+
+# fish
+dub completion fish > ~/.config/fish/completions/dub.fish
+```
+
+`${fpath[1]}` on most systems points at a root-owned directory like
+`/usr/local/share/zsh/site-functions`. Writing there works for system-wide
+installs (with `sudo`), but the user-owned path above is the recommended
+default.
+
+The generated script completes:
+
+- Top-level subcommands (`dub <Tab>`).
+- Nested subcommands and their flags (e.g. `dub config ai-provider <Tab>`,
+  `dub trunk add <Tab>`).
+- Local branch names for branch-arg commands: `dub co <Tab>` (alias
+  `checkout`), `dub delete <Tab>`, `dub track <Tab>`, `dub untrack <Tab>`.
+  (`dub up` and `dub down` take a numeric step count, not a branch.)
+- Branch names for branch-valued flags: `--parent`, `--branch`, `--before`,
+  `--after`.
+- File paths for `--by-file` and for commands that take positional file
+  arguments.
+- Per-command flags read directly from the `dub` binary's commander metadata,
+  so completions stay in sync with the CLI version installed in `$PATH`.
+
+Regenerate the script after upgrading `dub` so new flags and commands show up.
+
+## Man page
+
+`dub man` emits a roff-formatted man page to stdout. Redirect it into any
+directory on your `MANPATH`:
+
+```bash
+mkdir -p ~/.local/share/man/man1
+dub man > ~/.local/share/man/man1/dub.1
+man dub
+```
+
+The page is generated from the same commander.js definitions that power `dub
+--help`, so every subcommand and option is documented automatically.
+
+Distributors can bundle the man page alongside the binary — for example, the
+Homebrew formula installs `dub.1` into `share/man/man1/`.
+
 ## Refreshing the cache
 
 Most shell integrations should rely on the default (cache-first) behavior —

homebrew/dubstack.rb

@@ -12,9 +12,18 @@ class Dubstack < Formula
   def install
     system "npm", "install", *std_npm_args
     bin.install_symlink libexec.glob("bin/*")
+
+    # Generate the man page and shell completions from the installed binary
+    # so they always match the version users are running. `err: :merge` folds
+    # any stderr into the captured output so a failed `dub man` surfaces
+    # during `brew test` instead of silently writing a partial man page.
+    man1.mkpath
+    (man1/"dub.1").write Utils.safe_popen_read(bin/"dub", "man", err: :merge)
+    generate_completions_from_executable(bin/"dub", "completion")
   end
 
   test do
     assert_match version.to_s, shell_output("#{bin}/dub --version")
+    assert_match ".TH DUB 1", shell_output("#{bin}/dub man")
   end
 end