Skip to content

Add shell completions command (zero completions <shell>) #499

Closed

Description

@ziishaned

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 / --help on the subcommand.

Help integration:

  • List completions under Commands: in zero --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 setup or 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

  1. Hand-maintained completion files in the repo — Rejected because they drift from the CLI as commands and flags change.
  2. Third-party completion packages — No widely maintained community package exists for Zero today.
  3. Documenting commands only in README — Helps discovery but does not enable tab completion in the shell.
  4. 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions