Shell completion for Click CLI programs with auto-click-auto

Automatically enable tab autocompletion for shells in Click applications.

Edited image (original by Gabriel Heinzer on Unsplash)

Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It’s the “Command Line Interface Creation Kit”. It’s highly configurable but comes with sensible defaults out of the box.

Adding tab shell completion is a nice touch to any CLI program.

From version ≥ 8.0.0 Click supports shell completion, but to enable it the user still has to perform some manual steps (see docs).

auto-click-auto is a small Python library that is used to quickly and easily add tab shell completion support for Bash (version 4.4 and up), Zsh, and Fish, for Click CLI programs.

Usage

Install auto-click-auto with:

pip install auto-click-auto

There are two functions that auto-click-auto makes available: enable_click_shell_completion (general use)
and enable_click_shell_completion_option (to be used as a decorator).

Here are some typical ways to enable autocompletion with auto-click-auto:

1) Check on every run of the CLI program if autocompletion is configured and enable it in case it is not

This way you can seamlessly enable shell autocompletion without the user having to run any extra commands.

Example:

import click

from auto_click_auto import enable_click_shell_completion
from auto_click_auto.constants import ShellType


@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='The person to greet.')
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

    enable_click_shell_completion(
        program_name="example-1", shells={ShellType.BASH, ShellType.FISH},
    )

or

2) Make shell completion a Click command option

Example:

import click

from auto_click_auto import enable_click_shell_completion_option


@click.command()
@enable_click_shell_completion_option(program_name="example-2")
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='The person to greet.')
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

or

3) Make shell completion a command (or subcommand of a group)

This implementation option might be useful if you already have a “configuration” command in your CLI program.

Example:

import click

from auto_click_auto import enable_click_shell_completion
from auto_click_auto.constants import ShellType


@click.group()
def cli():
    """Simple CLI program."""
    pass


@cli.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='The person to greet.')
def hello(count, name):
    """Simple command that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")


@cli.group()
def config():
    """Program configuration."""
    pass


@config.command()
def shell_completion():
    """Activate shell completion for this program."""
    enable_click_shell_completion(
        program_name="example-3",
        shells={ShellType.BASH, ShellType.FISH, ShellType.ZSH},
        verbose=True,
    )

Examples

To run the examples, fork the project’s repository and follow the instructions at https://github.com/KAUTH/auto-click-auto/tree/main/examples.

Why auto-click-auto?

In the search for other tools that enable shell completion for Click, we come across a lot of example code and gists, or unmaintained repos and packages with extra dependencies. This introduces complexity to adapting the code and adding it to our use case quickly. For more information read here.

If you have any problems with auto-click-auto please open an issue here.

Hold down the 👏 to support and help others find this article. Thanks for reading!!

Follow me on Twitter @konpap1996