Shell Completion
ArgMojo can generate shell completion scripts for Bash, Zsh, and Fish. These scripts enable tab-completion for your CLI’s options, flags, subcommands, and choice values — with zero runtime overhead.
The generated scripts are static: they are produced once from your command tree and sourced by the user’s shell. No runtime hook or callback mechanism is needed.
Built-in --completions Flag
Every Command automatically responds to --completions <shell> — just like
--help and --version. No extra code is required.
var app = Command("myapp", "My application", version="1.0.0")
app.add_argument(Argument("verbose", help="Verbose output").long["verbose"]().short["v"]().flag())
app.add_argument(Argument("output", help="Output file").long["output"]().short["o"]().value_name["FILE"]())
app.add_argument(Argument("format", help="Output format").long["format"]().choice["json"]().choice["csv"]().choice["table"]())
var sub = Command("serve", "Start a server")
sub.add_argument(Argument("port", help="Port number").long["port"]().short["p"]())
app.add_subcommand(sub^)
# parse() handles --completions automatically — no extra code needed
var result = app.parse()
Users run:
myapp --completions bash # prints Bash completion script and exits
myapp --completions zsh # prints Zsh completion script and exits
myapp --completions fish # prints Fish completion script and exits
The --completions option is shown in the help output alongside --help and
--version:
options:
--help Show this help message and exit
--version Show the version and exit
--completions {bash,zsh,fish}
Generate shell completion script
Disabling the Built-in Flag
If you want to use completions as a regular argument name — or handle
completion triggering entirely on your own — call
disable_default_completions():
var app = Command("myapp", "My CLI")
app.disable_default_completions() # --completions is now an unknown option
disable_default_completions() removes --completions from the parse loop,
help output, and all generated completion scripts. The generate_completion()
method remains available for programmatic use.
Customising the Trigger Name
By default the option is called --completions. Use completions_name() to
rename it:
var app = Command("myapp", "My CLI")
app.completions_name("autocomp") # → --autocomp bash/zsh/fish
Help output, parse loop, and generated scripts all reflect the new name.
Using a Subcommand Instead of an Option
To expose completion generation as a subcommand rather than a -- option, call
completions_as_subcommand():
var app = Command("myapp", "My CLI")
app.completions_as_subcommand() # → myapp completions bash
The trigger moves from Options: to Commands: in help output. This can be
combined with completions_name():
app.completions_name("comp")
app.completions_as_subcommand() # → myapp comp bash
Generating a Script Programmatically
You can also call generate_completion directly to get a completion script as a
String:
# Compile-time validated (bracket syntax) — invalid shell names fail to compile
var script = app.generate_completion["bash"]()
print(script)
A runtime overload is also available for when the shell name comes from user input:
# Runtime dispatch (case-insensitive) — raises on unknown shell
var script = app.generate_completion(shell_name) # "bash", "zsh", or "fish"
The runtime overload is case-insensitive ("Bash", "BASH", "bash" all
work). An error is raised for unrecognised shell names.
Installing Completions
After generating a script, users source it or place it in a shell-specific
directory.
Bash:
# One-shot (current session only)
eval "$(myapp --completions bash)"
# Persistent
myapp --completions bash > ~/.bash_completion.d/myapp
# Then add to ~/.bashrc: source ~/.bash_completion.d/myapp
Zsh:
# Place in your fpath (file must be named _myapp)
myapp --completions zsh > ~/.zsh/completions/_myapp
# Make sure ~/.zsh/completions is in fpath (add to ~/.zshrc):
# fpath=(~/.zsh/completions $fpath)
# autoload -Uz compinit && compinit
Fish:
# Fish auto-loads from this directory
myapp --completions fish > ~/.config/fish/completions/myapp.fish
What Gets Completed
The generated scripts cover the full command tree:
| Element | Completed? | Notes |
|---|---|---|
Long options (--verbose) | Yes | With description text from help |
Short options (-v) | Yes | Paired with long option when both exist |
| Boolean flags | Yes | Marked as no-argument (no file/value completion after the flag) |
Count flags (-vvv) | Yes | Treated like boolean flags (no value expected) |
Choices (--format json) | Yes | Tab-completes the allowed values (json, csv, table) |
| Subcommands | Yes | Listed with descriptions; scoped completions for each subcommand |
Built-in --help / --version | Yes | Automatically included |
Built-in --completions {bash,…} | Yes | Automatically included; disable with disable_default_completions() |
| Hidden arguments | No (intentional) | .hidden() arguments are excluded from completion |
| Positional arguments | No (by design) | Positionals use default shell completion (file paths, etc.) |
| Persistent (global) flags | Yes (root level) | Inherited flags appear in the root command’s completions |
Note: Negatable flags (
--color/--no-color) — the--no-Xform is not separately listed in completions. The base--colorflag is completed; users type--no-manually. This matches the behaviour of other CLI frameworks.