Zsh, Fish & PowerShell Completions

Cobra generates zsh, fish, and PowerShell completion scripts from the same command completion model, writing the generated script either to an io.Writer or to a file.

This exists so each shell can translate its command-line state into a request for Cobra completions while preserving shared directive behavior and shell-specific output rules.

Sources: zsh_completions.go:31-33, fish_completions.go:276-281, powershell_completions.go:337-339, zsh_completions.go:87-308, fish_completions.go:25-273, powershell_completions.go:28-311

Core concepts

Completion generator

A completion generator is a public Command method that renders a shell script for the command tree.

The public entry points are:

Sources: zsh_completions.go:25-27, fish_completions.go:276-281, powershell_completions.go:337-339, zsh_completions.go:31-33, zsh_completions.go:36-38, zsh_completions.go:42-44, fish_completions.go:284-292, powershell_completions.go:331-333, powershell_completions.go:342-344, powershell_completions.go:348-350

Shared completion request

A shared completion request is the shell script’s call back into Cobra to obtain candidates and a directive.

The generated scripts select ShellCompRequestCmd when descriptions are enabled and ShellCompNoDescRequestCmd otherwise.

Sources: zsh_completions.go:87-308, fish_completions.go:25-273, powershell_completions.go:28-311

Completion directive

A completion directive is a bit map that tells the shell what to do after Cobra returns completion candidates.

The shown zsh and PowerShell generators embed values for errors, spacing, file completion, extension filtering, directory filtering, and order preservation into their scripts.

Sources: completions.go:43-45, zsh_completions.go:87-308, powershell_completions.go:28-311

How generation is called

For zsh, call GenZshCompletion or GenZshCompletionFile for descriptions, and use GenZshCompletionNoDesc or GenZshCompletionFileNoDesc when descriptions should be omitted.

For fish, call GenFishCompletion with an io.Writer and an includeDesc boolean, or call GenFishCompletionFile with a filename and the same boolean.

For PowerShell, call GenPowerShellCompletion or GenPowerShellCompletionFile without descriptions, and use GenPowerShellCompletionWithDesc or GenPowerShellCompletionFileWithDesc when descriptions are wanted.

Each writer-based generator buffers output, calls its shell-specific internal generator with c.Name() and the description choice, then writes the buffer to the supplied writer.

Each file-based generator creates the target file, closes it after generation, and delegates to the writer-based path.

The built-in PowerShell completion command demonstrates the subcommand pattern: its RunE handler calls the root command’s description or no-description generator according to noDesc.

The generation call order is summarized here.

Sources: zsh_completions.go:25-27, zsh_completions.go:31-33, zsh_completions.go:36-38, zsh_completions.go:42-44, fish_completions.go:276-281, fish_completions.go:284-292, powershell_completions.go:331-333, powershell_completions.go:337-339, powershell_completions.go:342-344, powershell_completions.go:348-350, zsh_completions.go:80-85, powershell_completions.go:313-318, zsh_completions.go:70-78, completions.go:903-923, powershell_completions.go:28-311

How the shells use shared directive semantics

Zsh stores directive constants in local variables, requests completions, reads the final output line as a directive, and ignores completions when the error bit is set.

PowerShell follows the same broad model: it defines the directive values, prepares a request, disables Active Help, and captures the command output for completion processing.

Fish also returns a directive line after its completion candidates, but its generated function explicitly disables Active Help because Active Help is not supported for fish.

The shared engine therefore supplies candidates and directive information, while each shell adapter parses and applies that information according to shell syntax.

Sources: zsh_completions.go:105-112, zsh_completions.go:139-179, powershell_completions.go:75-87, powershell_completions.go:123-128, fish_completions.go:55-59, fish_completions.go:74-89, zsh_completions.go:87-308, fish_completions.go:25-273, powershell_completions.go:28-311

Shell-specific behavior

Zsh truncates the command line at the current completion position, adds an empty argument when the last parameter is complete, and prefixes completions for flags using the = form.

Fish prefixes completions with the flag text when completing a flag containing =, and removes trailing empty output lines before interpreting the candidates and directive.

PowerShell reconstructs the command from its AST, truncates it when the cursor moved backward, handles --flag=value, and adds an empty argument when the last parameter is complete.

Zsh and fish retain repeated flag-name completion behavior for array or slice flags and support the = form, while zsh’s older positional-argument helpers are now deprecated no-ops.

For zsh positional arguments, file completion is enabled by default; callers can disable it with ValidArgsFunction and ShellCompDirectiveNoFileComp, while file-extension filtering uses ShellCompDirectiveFilterFileExt.

Sources: zsh_completions.go:120-151, fish_completions.go:61-89, powershell_completions.go:57-121, site/content/completions/zsh.md:30-39, zsh_completions.go:55-57, zsh_completions.go:66-68, site/content/completions/zsh.md:21-28

Description output

Zsh includes descriptions by default through GenZshCompletion and GenZshCompletionFile; the corresponding methods pass false to the internal generator when descriptions are omitted.

Fish exposes description support directly through the includeDesc parameter, which selects either ShellCompRequestCmd or ShellCompNoDescRequestCmd.

PowerShell provides explicit description and no-description methods, and both paths pass the choice to genPowerShellComp.

Sources: zsh_completions.go:25-27, zsh_completions.go:31-33, zsh_completions.go:36-38, zsh_completions.go:42-44, fish_completions.go:25-273, fish_completions.go:276-281, powershell_completions.go:331-333, powershell_completions.go:337-339, powershell_completions.go:342-344, powershell_completions.go:348-350, powershell_completions.go:28-311

How it connects

The generated scripts depend on Cobra’s dynamic completion engine, including ValidArgsFunction, RegisterFlagCompletionFunc(), and ShellCompDirective; see Dynamic Completion Engine.

The shell scripts request completion data through Cobra’s completion command, so their runtime behavior belongs with the engine rather than with command execution; see Command Execution Flow and Dynamic Completion Engine.

The zsh changes described here are part of Cobra’s cross-shell standardization and should be read alongside the bash-specific implementation; see Bash Completion Scripts (V1 & V2).

Sources: completions.go:43-45, site/content/completions/zsh.md:41-44, zsh_completions.go:87-308, fish_completions.go:25-273, powershell_completions.go:28-311, site/content/completions/zsh.md:5-7

Key takeaways

• Use the shell-specific public generator methods to write completion scripts to writers or files.
• Zsh, fish, and PowerShell all request candidates plus directive information from the shared completion engine.
• Fish and PowerShell disable Active Help; fish also handles = flags by prefixing returned candidates.
• Zsh defaults to descriptions and file completion, while its older positional helpers are deprecated no-ops.
• Description support is selected by method names for zsh and PowerShell, but by includeDesc for fish.