Shell Completion

The ZERG CLI generates completion scripts for Bash, Zsh, and Fish. Completions cover all 54 commands, subcommands for grouped commands, global flags, and dynamic resource IDs.

Installation

Bash

zerg completion bash >> ~/.bashrc
source ~/.bashrc

Or install system-wide:

zerg completion bash | sudo tee /etc/bash_completion.d/zerg

Zsh

mkdir -p ~/.zfunc
zerg completion zsh > ~/.zfunc/_zerg

Ensure ~/.zfunc is in your fpath:

# In ~/.zshrc
fpath=(~/.zfunc $fpath)
autoload -U compinit && compinit

Fish

mkdir -p ~/.config/fish/completions
zerg completion fish > ~/.config/fish/completions/zerg.fish

Fish loads completions automatically. Start a new shell or run:

source ~/.config/fish/completions/zerg.fish

What Gets Completed

Commands

All 49 top-level commands are completed:

zerg <TAB>
status         discover       list           ps             metrics
show           start          stop           stop-all       prepare
run            chat           agents         spawn          kill
task           task-cancel    task-status    workflow       bg-workers
schedule       login          logout         completion     ...

Subcommands

Grouped commands complete their subcommands:

zerg workflow <TAB>
list     start    show     cancel   branch   tree     lineage

zerg schedule <TAB>
list     add      show     pause    unpause  run      delete

zerg bg-workers <TAB>
start    list     status   logs     kill

zerg update <TAB>
check    download apply    rollback

Global Flags

Flags are completed after --:

zerg status --<TAB>
--json         --token       --profile     --api-url
--format       --quiet       --version     --help
--model        --no-stream   --stream      --temp
--top-p        --max-tokens  --wait        --ttl

Dynamic Resources

The --model flag completes with model IDs fetched from the server (cached for 60 seconds):

zerg start --model <TAB>
glm-5.1    claude-sonnet-4-20250514    gpt-4o

The --profile flag completes with profile names from the config file:

zerg status --profile <TAB>
default    staging    production

Completion Architecture

The completion system is generated at runtime from cli/completion_data.lua. This module provides:

Function	Returns
get_commands()	All top-level command names
get_subcommands(group)	Subcommands for a grouped command
get_flags()	All global flags
get_profiles()	Profile names from ~/.zerg/config.json
fetch_models()	Model IDs from the server (cached)
bash_script()	Generated Bash completion script
zsh_script()	Generated Zsh completion script
fish_script()	Generated Fish completion script

Dynamic completions (models, agents) use a /tmp/.zerg-*-cache file with a 60-second TTL to avoid hitting the server on every tab press.

Troubleshooting

Completions not appearing

Bash: Ensure bash-completion is installed and sourced before the zerg script.

sudo apt install bash-completion

Zsh: Run rm ~/.zcompdump* && compinit to rebuild the completion cache.

Fish: Check that ~/.config/fish/completions/ exists and the file is readable.

Stale model completions

Model IDs are cached in /tmp/.zerg-models-cache for 60 seconds. To force a refresh:

rm /tmp/.zerg-models-cache

Completion script is empty

The zerg completion command outputs to stdout. Ensure you redirect to a file:

zerg completion bash >> ~/.bashrc

Not:

zerg completion bash

Profile completions show wrong names

Profile completions read from ~/.zerg/config.json. If you modified the config manually, verify the JSON is valid:

cat ~/.zerg/config.json | python3 -m json.tool

Zsh fpath issues

If Zsh completions do not load, verify the fpath order:

echo $fpath

~/.zfunc must appear before the default completion directories. Add it early in ~/.zshrc:

fpath=(~/.zfunc $fpath)
autoload -U compinit && compinit