Shell Completion

Click turns a shell’s completion request into suggestions for commands, options, and parameter values. It supports Bash, Zsh, Fish, and PowerShell, with shell-specific scripts and response formats.

This exists so completion can run through the installed CLI itself: the shell invokes the executable with a special environment variable, and Click exits after returning either an activation script or completion data.

Sources: src/click/shell_completion.py:19-55

Core concepts

Completion instruction

A completion instruction is the environment-variable value that selects a shell and an operation, such as bash_source or bash_complete.

Sources: src/click/shell_completion.py:19-55

Completion item

A completion item is a suggestion plus metadata describing special handling and optional help text.

Sources: src/click/shell_completion.py:67-101

Shell adapter

A shell adapter translates that shell’s environment variables and Click’s completion items into the format expected by the shell.

Sources: src/click/shell_completion.py:278-386, src/click/shell_completion.py:389-445, src/click/shell_completion.py:448-481, src/click/shell_completion.py:484-518, src/click/shell_completion.py:521-552

Incomplete value

The incomplete value is the partial word currently being completed; it may be empty when the cursor is after the last complete argument.

Sources: src/click/shell_completion.py:278-386, src/click/shell_completion.py:389-445, src/click/shell_completion.py:448-481

How a shell request reaches Click

The shell first sources a generated function. That function is registered with the shell and later invokes the executable with the completion environment variable set to a shell-specific complete instruction.

This workflow shows the routing boundary between the shell script and the Click process.

The top-level shell_complete function splits the instruction at the first underscore, looks up the shell adapter, and returns failure if the shell is unknown. The adapter then emits the generated source script for source, or completion output for complete, writing encoded bytes so newline translation does not break the protocol.

The built-in registry maps bash, fish, powershell, and zsh to their adapter classes. A new adapter can be registered with add_completion_class, which stores the class under its explicit name or its name attribute.

Sources: src/click/shell_completion.py:105-135, src/click/shell_completion.py:143-185, src/click/shell_completion.py:187-207, src/click/shell_completion.py:214-269, src/click/shell_completion.py:19-55, src/click/shell_completion.py:593-600, src/click/shell_completion.py:555-560, src/click/shell_completion.py:565-582

How Click generates and formats suggestions

Each adapter inherits the common ShellComplete flow. It reads shell-specific state through get_completion_args, resolves the command context, asks the selected Click object for completions, formats every CompletionItem, and joins the results into the response.

This sequence follows one completion request through the shared adapter pipeline.

The context resolver enables resilient parsing, creates a context, and follows group and subcommand arguments without triggering prompts or callbacks. The incomplete-value resolver handles option syntax first: it separates = values, returns the command for option-name completion, then checks whether an option needs a value, then whether an argument can still accept one, and otherwise returns the command for command-name completion.

Command completion includes visible command names with short help text and then delegates to the base parameter completion behavior. Options are only considered when the partial value begins with an option prefix, and hidden commands and options are not shown.

The shell adapters share the same argument model but differ in transport details:

The generated Bash script maps plain, dir, and file item types to ordinary values, directory completion, and file completion. Zsh uses help-aware descriptions and path helpers, while Fish and PowerShell parse their own line-oriented formats and preserve shell-specific help behavior.

Bash completion checks the installed Bash version and reports that versions older than 4.4 are unsupported; it also reports when the version cannot be detected.

Sources: src/click/shell_completion.py:278-386, src/click/shell_completion.py:376-386, src/click/shell_completion.py:696-754, src/click/shell_completion.py:757-801, src/click/core.py:2142-2159, docs/shell-completion.md:11-12, src/click/shell_completion.py:662-668, src/click/shell_completion.py:389-445, src/click/shell_completion.py:448-481, src/click/shell_completion.py:484-518, src/click/shell_completion.py:521-552, src/click/shell_completion.py:105-135, src/click/shell_completion.py:143-185, src/click/shell_completion.py:187-207, src/click/shell_completion.py:214-269, src/click/shell_completion.py:396-426

How to add custom completions

For type-wide behavior, override shell_complete on a custom ParamType and return CompletionItem objects. The method receives the context, parameter, and incomplete value. The type field can request path handling with dir or file, while help supplies text for shells that support descriptions.

For one parameter, provide a shell_complete function instead of defining a custom type. Click calls that function first; if it returns strings, Click wraps them as CompletionItem objects, otherwise it returns the item objects directly.

A custom completion function can therefore filter suggestions using incomplete, return plain strings for simple values, or return CompletionItem instances when descriptions or special path behavior matter.

For a new shell, create a ShellComplete subclass, set its name and source_template, register it with add_completion_class, implement get_completion_args, and implement format_completion for the shell’s response protocol.

Sources: docs/shell-completion.md:139-164, src/click/shell_completion.py:67-101, src/click/types.py:1235-1251, src/click/core.py:2950-2960, docs/shell-completion.md:191-237, src/click/shell_completion.py:278-386, src/click/shell_completion.py:565-582

How it connects

Completion depends on the installed entry-point executable rather than invoking the program through the python command. The shell script is generated from the adapter’s source_template, with variables for the completion function, completion environment variable, and executable name.

The completion resolver hands command parsing to make_context and command groups’ resolve_command, so understanding completion benefits from Context and Execution and Commands and Groups. The selected command or parameter then supplies completions through shell_complete, connecting this page to The Parameter Model and Parameter Types.

The argument text is split with split_arg_string, which tolerates an unfinished quote or escape and preserves the partial token instead of failing. This makes shell-provided command lines usable while the user is still typing.

Sources: docs/shell-completion.md:21-25, src/click/shell_completion.py:278-386, src/click/shell_completion.py:272-275, src/click/shell_completion.py:696-754, src/click/types.py:224-239, src/click/shell_completion.py:603-636

Key takeaways

• Click selects a shell adapter from the completion instruction and returns either a generated script or formatted suggestions.
• ShellComplete.complete resolves arguments, finds the target command or parameter, and formats its completion items.
• Bash, Zsh, Fish, and PowerShell use different environment inputs and response formats, but share the same resolution pipeline.
• Custom completions can be attached to a parameter or supplied by a custom ParamType.
• New shells integrate through a registered ShellComplete subclass.

Sources: src/click/shell_completion.py:19-55, src/click/shell_completion.py:376-386, src/click/shell_completion.py:389-445, src/click/shell_completion.py:448-481, src/click/shell_completion.py:484-518, src/click/shell_completion.py:521-552, docs/shell-completion.md:191-237