Repository navigation
Description
Problem
Zero has a large CLI surface (exec, daemon, mcp, sandbox, auth, and many more subcommands), but there is no built-in way to generate shell completion scripts. Users must type full command names and flags manually, which slows down everyday use and makes nested subcommands easy to mistype or forget.
Other terminal agents in this space already ship a completions command. For example, grok completions <shell> generates scripts for bash, zsh, fish, powershell, and elvish. Zero currently has no equivalent, so tab completion is unavailable out of the box.
Requested behavior
Add a completions subcommand to the Zero CLI:
zero completions <shell>
Shell argument (required): one of bash, zsh, fish, powershell, elvish.
Behavior:
- Print a shell completion script to stdout.
- Exit 0 on success; exit with usage error (exit code 2) for missing/unknown shell arguments.
- Support
-h/--helpon the subcommand.
Help integration:
-
List
completionsunderCommands:inzero --help. -
Document install examples in
zero completions --help, e.g.:zero completions bash >> ~/.bashrc zero completions zsh >> ~/.zshrc zero completions fish > ~/.config/fish/completions/zero.fish
Completion coverage (minimum):
- Top-level commands and documented aliases (
sessions/session,plugins/plugin,worktrees/worktree, etc.). - Nested subcommands (e.g.
zero daemon start,zero mcp oauth login,zero sandbox grants allow). - Root-level flags (
--add-dir,--theme,--skip-permissions-unsafe,-p/--prompt, etc.). - Common flags for heavily used commands such as
exec.
Non-goals for v1 (can be follow-ups):
- Dynamic completion of model names, session IDs, or MCP server names from live config.
- Auto-install during
zero setupor the install scripts.
Why it belongs in Zero
Zero is a terminal-first coding agent. Shell tab completion is standard UX for CLI tools with many subcommands, and it directly improves discoverability of Zero's command surface without reading docs.
A completions command keeps completion scripts in sync with the CLI as commands evolve, instead of maintaining hand-written completion files separately. This matches the pattern already used by comparable tools (e.g. grok completions) and fits Zero's existing custom CLI architecture without adding new dependencies or changing the core language.
Alternatives or workarounds considered
- Hand-maintained completion files in the repo — Rejected because they drift from the CLI as commands and flags change.
- Third-party completion packages — No widely maintained community package exists for Zero today.
- Documenting commands only in README — Helps discovery but does not enable tab completion in the shell.
- Migrating the CLI to Cobra/urfave for auto-generation — Too large a change for this feature alone; a lightweight generator inside the existing CLI is sufficient.
Examples, screenshots, or prior discussion
Comparable command in Grok:
$ grok --help
Commands:
completions Generate shell completion scripts (bash, zsh, fish, powershell, ...)
$ grok completions --help
Usage: grok completions [OPTIONS] <SHELL>
Arguments:
<SHELL> Target shell [possible values: bash, elvish, fish, powershell, zsh]
Proposed Zero UX (mirroring the above):
$ zero --help
Commands:
...
completions Generate shell completion scripts (bash, zsh, fish, powershell, ...)
...
$ zero completions --help
Generate shell completion scripts (bash, zsh, fish, powershell, ...)
Usage:
zero completions <shell>
Arguments:
<shell> Target shell (bash, elvish, fish, powershell, zsh)
Suggested verification after implementation:
zero completions --help
zero completions bash | grep 'complete -F _zero zero'
zero completions zsh | grep '#compdef zero'
zero completions fish | grep 'complete -c zero'
zero completions bash # should list daemon, mcp, exec subcommands
go test ./internal/cli -run Completions
Activity
Complete shell target suggestions
Fix Elvish completion syntax
Add shell completion generation (#764)