Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

ElementCompleted?Notes
Long options (--verbose)YesWith description text from help
Short options (-v)YesPaired with long option when both exist
Boolean flagsYesMarked as no-argument (no file/value completion after the flag)
Count flags (-vvv)YesTreated like boolean flags (no value expected)
Choices (--format json)YesTab-completes the allowed values (json, csv, table)
SubcommandsYesListed with descriptions; scoped completions for each subcommand
Built-in --help / --versionYesAutomatically included
Built-in --completions {bash,…}YesAutomatically included; disable with disable_default_completions()
Hidden argumentsNo (intentional).hidden() arguments are excluded from completion
Positional argumentsNo (by design)Positionals use default shell completion (file paths, etc.)
Persistent (global) flagsYes (root level)Inherited flags appear in the root command’s completions

Note: Negatable flags (--color / --no-color) — the --no-X form is not separately listed in completions. The base --color flag is completed; users type --no- manually. This matches the behaviour of other CLI frameworks.