Click Completion

0.5.2 · active · verified Fri Apr 17

click-completion is a Click extension that provides shell completion for Fish, Bash, Zsh, and PowerShell. It helps users get tab-completion for their Click-based command-line interfaces. The current version is 0.5.2, and as a `click-contrib` library, it typically maintains an active but often lower-cadence release cycle, with updates often aligning with Click's own evolution.

Common errors

```
AttributeError: module 'click_completion.extra' has no attribute 'install'
```
cause Attempting to use `click_completion.extra.install()` or other functions from the `extra` module, which were removed in version 0.5.0.

fix Remove all calls to `click_completion.extra` functions. `click-completion` 0.5.0 and later requires manual generation and sourcing of completion scripts.
```
TypeError: startswith() missing 1 required positional argument: 'prefix'
```
cause The signature of `click_completion.core.startswith` changed in version 0.5.0, adding a required `prefix` argument. Code written for older versions might be calling it incorrectly.

fix Review calls to `click_completion.core.startswith`. Ensure you are passing the `prefix` argument as required by the current version's API.
```
Command 'my-cli-app' tab-completion is not working, or only completes basic commands, not options/arguments.
```
cause This is a common issue often caused by one of two things: `click_completion.init()` was not called in the Python application, or the generated shell completion script has not been correctly sourced in the user's shell.

fix 1. Verify `click_completion.init()` is called in your Click application. 2. Ensure the user has added the correct sourcing command to their shell configuration file (e.g., `echo 'source <(my-cli-app --show-completion bash)' >> ~/.bashrc && source ~/.bashrc`).

Warnings

breaking Starting with version 0.5.0, `click-completion` no longer attempts to automatically install completion scripts. Users must manually generate and source the completion script for their shell.
Fix: Remove any calls to `click_completion.extra.install()` or similar legacy installation methods. Update your shell's configuration (`.bashrc`, `.zshrc`, etc.) to explicitly source the completion script generated by `your_cli_app --show-completion <shell_type>`.
deprecated The `click_completion.extra` module and its functions, such as `install()` and `shell_paths()`, were removed in version 0.5.0.
Fix: These functions have no direct replacement. The intended way to use completion is to call `click_completion.init()` in your app and then have users manually generate and source the completion script using the `--show-completion` argument provided by `click-completion`.
gotcha For completion to work correctly, `click_completion.init()` must be called within your Click application, and the generated completion script must be sourced in the user's shell environment.
Fix: Ensure `click_completion.init()` is called early in your Click app's lifecycle. Instruct users to add `source <(your_cli_app --show-completion bash)` (or similar for their shell) to their shell configuration file (e.g., `~/.bashrc`).

Install

pip install click-completion Install latest version

Imports

init
wrong:
```
from click_completion.core import init
```
correct:
```
from click_completion import init
```
`init` is exported directly to the top-level `click_completion` module for convenience.

BashCompletion

from click_completion.core import BashCompletion

Quickstart

This quickstart demonstrates a minimal Click application integrated with `click-completion`. It defines a root group `cli` with two commands, `hello` and `goodbye`. Calling `click_completion.init()` at the start enables the completion functionality for the CLI. To activate completion, you would typically run `python your_app.py --show-completion <shell_type>` and source the output in your shell configuration.

import click
import click_completion

# Initialize click-completion. This must be called BEFORE defining your commands
# if you want options like --show-completion to be available.
click_completion.init()

@click.group()
def cli():
    """A simple CLI demonstrating completion."""
    pass

@cli.command()
@click.option('--name', default='World', help='The name to greet.')
def hello(name):
    """Greets the given name."""
    click.echo(f"Hello, {name}!")

@cli.command()
def goodbye():
    """Says goodbye."""
    click.echo("Goodbye!")

if __name__ == '__main__':
    cli()

view raw JSON →