click

name	click
description	Best practices for building CLI applications with Click including commands, groups, options, and testing.

Skill: Click

Best practices for building CLI applications with Click including commands, groups, options, and testing.

When to Use

Apply this skill when building command-line interfaces with Click — commands, groups, options, arguments, and prompts.

Commands

• Use @click.command() for single commands, @click.group() for multi-command CLIs.
• Declare options with @click.option() and positional args with @click.argument().
• Use help= on every option and command for auto-generated help text.
• Use envvar= to allow environment variable fallback for sensitive options.

Groups

• Organize subcommands with @click.group() and group.add_command().
• Use @click.pass_context to share state between group and subcommands.

Type Safety

• Use Click's built-in types (click.Path(exists=True), click.Choice([...]), click.IntRange()).
• Use callbacks for custom validation.

Testing

• Use click.testing.CliRunner() for testing commands without subprocess overhead.
• Assert on result.exit_code and result.output.
• Use mix_stderr=False to test stderr separately.

Pitfalls

• Don't use sys.exit() — use click.exceptions.Exit or return from the command.
• Don't use print() — use click.echo() for proper encoding handling.
• Always handle KeyboardInterrupt / abort prompts gracefully.