How to Add Auto-Completion to Click CLI Apps

If you’ve ever typed a long CLI command and immediately regretted your life choices, this article is for you. Typing out full command names, remembering options, and scrolling through help menus is so last century.

Wouldn’t it be great if your CLI app could just complete commands for you? Like magic? Well, good news: Click supports auto-completion!

In this guide, we’ll:

Enable auto-completion in Click-powered CLI apps.
Set it up for Bash, Zsh, and Fish (sorry Windows users, life is hard).
Make our CLI apps feel 10x smarter.

🎯 Why Auto-Completion?

✅ Saves you from typing long commands (because who has time for that?)
✅ Reduces typos (no more --frce instead of --force)
✅ Makes your CLI look polished and professional

Click has built-in auto-completion support, but it needs a little setup. Let’s do it.

🛠 Step 1: Install Click Shell Completion

First, make sure you have Click 8.0+:

1
pip install --upgrade click

Now, let’s create a basic CLI app in cli.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import click

@click.group()
def cli():
    """A smart CLI app with auto-completion."""
    pass

@cli.command()
def hello():
    """Say hello!"""
    click.echo("Hello, world!")

@cli.command()
def goodbye():
    """Say goodbye!"""
    click.echo("Goodbye, world!")

if __name__ == "__main__":
    cli()

Run python cli.py --help, and you’ll see a basic CLI app with two commands.

Now, let’s add auto-completion.

🔧 Step 2: Enable Auto-Completion

Click supports shell completion, but we need to set it up manually.

Generate Completion Scripts

To enable completion, Click provides a built-in command:

1
python cli.py --show-completion

This will output a shell completion script. You need to save this script and source it in your shell.

For Bash Users 🐧

Save the script to your bash completion directory:

1
2
python cli.py --show-completion bash > ~/.bash_completion
source ~/.bash_completion

Or add it to .bashrc:

1
echo 'source ~/.bash_completion' >> ~/.bashrc

For Zsh Users 🦄

For Zsh, save the script to your completion functions:

1
2
3
4
5
mkdir -p ~/.zfunc
python cli.py --show-completion zsh > ~/.zfunc/_cli
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

For Fish Users 🐠

Fish shell users can do:

1
python cli.py --show-completion fish > ~/.config/fish/completions/cli.fish

Restart your shell, and auto-completion should work! 🎉

🎮 Step 3: Test It!

Try typing:

1
python cli.py <TAB>

You should see:

1
goodbye  hello

Now try:

1
python cli.py hello <TAB>

It should auto-complete the command! You’re now a CLI wizard. 🧙‍♂️

🏆 Step 4: Making It Even Smarter

Want better auto-completion? Click lets you suggest values dynamically.

Let’s create a command with auto-completing options:

1
2
3
4
5
6
7
@click.command()
@click.argument("color", type=click.Choice(["red", "green", "blue"], case_sensitive=False))
def choose_color(color):
    """Pick a color."""
    click.echo(f"You chose {color}!")

cli.add_command(choose_color)

Now, when you type:

1
python cli.py choose-color <TAB>

It will only suggest “red”, “green”, or “blue”! Smart, right?

🎉 Wrapping Up

Today, you learned how to supercharge your Click CLI apps with:
✅ Auto-completion for commands and options
✅ Bash, Zsh, and Fish integration
✅ Dynamic suggestions for even better UX

Your CLI is now faster, smarter, and less frustrating to use. Congrats! 🎊

How to Add Auto-Completion to Python Click CLI Apps

Where would we be without autocompletion?