How to enable shell completion
This guide adds completion to a cloudctl CLI with deploy and status subcommands, then to a flat minify CLI. The interactive listings use zsh; other shells render the same candidates in their native layout. To compute candidates in Go, see How to compute and shape completion candidates.
Enable completion on the builder
Section titled “Enable completion on the builder”Call EnableCompletion() on the application builder:
type CLI struct { Deploy conga.Command[DeployCmd] `summary:"Deploy a service"` Status conga.Command[StatusCmd] `summary:"Show service status"`}
type DeployCmd struct { Env conga.OptionalFlag[string] `default:"staging" enum:"staging,prod" help:"Target environment"` Service conga.RequiredArg[string] `help:"Service to deploy"`}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "deploying %s to %s\n", d.Service.Get(), d.Env.Get())
return nil}
type StatusCmd struct{}
func (s *StatusCmd) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintln(session.Stdout(), "all services healthy")
return nil}
func main() { app := conga.New[CLI](). Name("cloudctl"). EnableCompletion()
if err := app.Run(); err != nil { app.Exit(err) }}Because CLI declares subcommands, CONGA mounts a completion <shell> subcommand, listed last under Commands::
$ cloudctl --helpUsage: cloudctl <command>
Commands: deploy Deploy a service status Show service status completion Generate shell completion scripts
Flags: --help Show help --version Show versionA root command without subcommands gets a --completion <shell> flag instead; see Enable completion in a flat CLI.
Customize the completion subcommand
Section titled “Customize the completion subcommand”Declare a conga.CompletionCommand field on the root struct to customize the subcommand with name, aliases, section, summary, or hidden tags:
type CLI struct { Deploy conga.Command[DeployCmd] `summary:"Deploy a service"` Status conga.Command[StatusCmd] `summary:"Show service status"`
Completion conga.CompletionCommand `aliases:"comp" section:"Setup" summary:"Print the shell completion script"`}$ cloudctl --helpUsage: cloudctl <command>
Commands: deploy Deploy a service status Show service status
Setup: completion Print the shell completion script
Flags: --help Show help --version Show versioncloudctl comp zsh now resolves to the completion subcommand. Setting hidden:"true" keeps the command executable while omitting it from --help and completion candidates.
Enable completion in a flat CLI
Section titled “Enable completion in a flat CLI”A root command without conga.Command[T] fields gets a --completion <shell> flag in place of the subcommand. This minify program takes one positional argument:
type CLI struct { Level conga.OptionalFlag[int] `default:"1" help:"Minification level" range:"1..9" short:"l"` Output conga.OptionalFlag[string] `help:"Output file path" short:"o"` Input conga.RequiredArg[string] `help:"Input file to minify"`}
func (c *CLI) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "minifying %s at level %d\n", c.Input.Get(), c.Level.Get())
return nil}
func main() { app := conga.New[CLI](). Name("minify"). EnableCompletion()
if err := app.Run(); err != nil { app.Exit(err) }}$ minify --helpUsage: minify [flags] <input>
Arguments: <input> Input file to minify
Flags: -l, --level=1 Minification level [1..9] -o, --output=STRING Output file path --completion=SHELL Generate shell completion script --help Show help --version Show versionThe flag takes the same shell names and prints the same setup screens, in flag syntax. Users of a flat CLI type --completion <shell> wherever the install commands below use completion <shell>:
$ minify --completionGenerate shell completion scripts
Usage: minify --completion [shell]
Supported shells: bash Bourne Again SHell elvish Elvish shell fish Friendly interactive shell nushell Nushell shell powershell PowerShell / pwsh zsh Z shell
Enable completions for your current zsh shell now:
source <(minify --completion zsh)
For persistent setups, run 'minify --completion zsh --help'.
Flags: --help Show helpTo offer a completion subcommand instead, declare a conga.CompletionCommand field. CONGA drops the --completion flag, and the field takes the tags from the previous section:
type CLI struct { Level conga.OptionalFlag[int] `default:"1" help:"Minification level" range:"1..9" short:"l"` Output conga.OptionalFlag[string] `help:"Output file path" short:"o"` Input conga.RequiredArg[string] `help:"Input file to minify"`
Completion conga.CompletionCommand `summary:"Generate shell completion scripts"`}$ minify --helpUsage: minify [flags] <input>
Commands: completion Generate shell completion scripts
Arguments: <input> Input file to minify
Flags: -l, --level=1 Minification level [1..9] -o, --output=STRING Output file path --help Show help --version Show versionThe command name now shadows a positional value spelled completion: minify completion prints the setup screen, and minify -- completion or minify ./completion minifies a file of that name. The flat completion flag and flat completion subcommand examples show both forms.
Load or install the completion script
Section titled “Load or install the completion script”Without a shell name, cloudctl completion lists the shells and the setup command for the detected shell:
$ cloudctl completionGenerate shell completion scripts
Usage: cloudctl completion [<shell>]
Arguments: [<shell>] Target shell name
Supported shells: bash Bourne Again SHell elvish Elvish shell fish Friendly interactive shell nushell Nushell shell powershell PowerShell / pwsh zsh Z shell
Enable completions for your current zsh shell now:
source <(cloudctl completion zsh)
For persistent setups, run 'cloudctl completion zsh --help'.
Flags: --help Show helpcloudctl completion <shell> --help prints the setup steps for that shell, adjusted to the environment: with HOMEBREW_PREFIX set, the zsh steps write to $HOMEBREW_PREFIX/share/zsh/site-functions, and on macOS the bash steps warn when the running Bash is older than 4.4.
# Current sessionsource <(cloudctl completion bash)
# Every new sessionecho 'source <(cloudctl completion bash)' >> ~/.bashrc
# Or, with bash-completion installed, write a lazy-loaded completion filemkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions"cloudctl completion bash > "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/cloudctl"# Ensure compinit is enabledecho 'autoload -U compinit; compinit' >> ~/.zshrc
# Current sessionsource <(cloudctl completion zsh)
# Every new sessionecho 'source <(cloudctl completion zsh)' >> ~/.zshrc
# Or write a completion file into fpath (add fpath=(~/.zfunc $fpath) before compinit)mkdir -p ~/.zfunccloudctl completion zsh > ~/.zfunc/_cloudctl
# Or, with Homebrew, write to the site-functions directory already in fpathcloudctl completion zsh > "$HOMEBREW_PREFIX/share/zsh/site-functions/_cloudctl"# Current sessioncloudctl completion fish | source
# Every new sessionmkdir -p ~/.config/fish/completionscloudctl completion fish > ~/.config/fish/completions/cloudctl.fish# Current sessioncloudctl completion powershell | Out-String | Invoke-Expression
# Every new sessionif (!(Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }Add-Content -Path $PROFILE -Value 'cloudctl completion powershell | Out-String | Invoke-Expression'
# If script execution is disabledSet-ExecutionPolicy -Scope CurrentUser RemoteSigned# Current sessioneval (cloudctl completion elvish | slurp)
# Every new sessionmkdir -p ~/.config/elvishecho 'eval (cloudctl completion elvish | slurp)' >> ~/.config/elvish/rc.elv# Every new session (Nushell 0.102+ autoloads this directory)mkdir ($nu.default-config-dir | path join "autoload")cloudctl completion nushell | save -f ($nu.default-config-dir | path join "autoload/cloudctl.nu")
# Current session, after saving the filesource ($nu.default-config-dir | path join "autoload/cloudctl.nu")Verify completion output
Section titled “Verify completion output”With the script loaded, pressing
$ cloudctl <Tab>completion -- Generate shell completion scriptsdeploy -- Deploy a servicestatus -- Show service statusThe enum tag on --env supplies its values:
$ cloudctl deploy --env <Tab>Target environmentprod stagingAt a bare space, deploy offers its positional argument, and flags appear once the user types -:
$ cloudctl deploy <Tab><service>: Service to deploy$ cloudctl deploy --<Tab>--env -- Target environment--help -- Show helpFlags at a bare space lists when flags appear without the -.
Override the environment variable prefix
Section titled “Override the environment variable prefix”Generated shell scripts read <APP>_COMPLETION_DESCRIPTIONS, <APP>_COMPLETION_ALIASES, and <APP>_COMPLETION_BARE_SPACE_FLAGS, where <APP> defaults to the application name in UPPER_SNAKE_CASE (CLOUDCTL_COMPLETION_*). Pass conga.CompletionEnvPrefix to EnableCompletion to override the prefix:
app := conga.New[CLI](). Name("cloudctl"). EnableCompletion( conga.CompletionEnvPrefix("CCTL"), )The scripts read these variables from the shell’s environment at each CCTL_COMPLETION_DESCRIPTIONS=0 cloudctl <Tab>) is part of the line being completed and has no effect. With CCTL_COMPLETION_DESCRIPTIONS=0 exported (or zstyle ':completion:*' verbose no in zsh), candidates lose their descriptions:
$ export CCTL_COMPLETION_DESCRIPTIONS=0$ cloudctl <Tab>completion deploy statusSee User toggles for the full variable and zstyle reference.
Know what users see
Section titled “Know what users see”| Invocation | Result |
|---|---|
cloudctl completion myshell |
Usage error listing the supported shells (exit 2) |
--completion zsh on a CLI that has a completion subcommand |
Usage error, unknown flag: --completion (exit 2) |
./cloudctl <Tab> or /usr/local/bin/cloudctl <Tab> |
Dispatches to the cloudctl completer in bash, zsh, fish, PowerShell, and Nushell |
./cloudctl <Tab> in Elvish |
Falls back to file completion; Elvish keys completers on the literal command word |
cctl <Tab> using a script generated from cloudctl |
Falls back to file completion until the user regenerates the script from cctl |
Error:cloudctl: error: unknown shell "myshell", supported shells: bash, elvish, fish, nushell, powershell, zshErrorWhere to go next
Section titled “Where to go next”- How to compute and shape completion candidates: compute candidates from loaded data or an API, combine predictors, and complete values in parts.
- Completion: flag vs. subcommand rules, user toggles, binary names, and file candidates.
- Package predict: predictor constructors, combinators, and interfaces.