Click: Composable Command Line Interface Toolkit

Click (Command Line Interface Creation Kit) is designed to create composable command line interfaces with minimal code. Key features include:

• Arbitrary nesting of commands: Easily create complex command hierarchies using groups.
• Automatic help page generation: Click automatically generates formatted help documentation based on your command and option definitions.
• Lazy loading: Supports loading subcommands at runtime to improve performance and startup time.
• Sensible defaults: Provides high configurability while working out of the box with minimal setup.

Click is a Python package designed for creating composable command line interfaces (CLIs) with minimal code. It provides sensible defaults and is highly configurable.

Key features include:

• Arbitrary nesting of commands: Easily create complex command hierarchies.
• Automatic help page generation: Automatically generates documentation for your CLI based on your code.
• Lazy loading of subcommands: Supports loading subcommands at runtime to improve performance and startup time.

In Click, a regular command's callback executes when the command runs. However, for a @click.group(), the callback fires whenever any subcommand is invoked. This means an outer group's logic (like setting up a debug mode) runs before the inner command's logic.

When using groups, ensure you use the group as the decorator for subcommands (e.g., @cli.command() instead of @click.command()) so they are correctly attached to the group's lifecycle.

@click.group()
@click.option('--debug/--no-debug', default=False)
def cli(debug):
    click.echo(f"Debug mode is {'on' if debug else 'off'}")

@cli.command()
def sync():
    click.echo('Syncing')

Click intentionally limits certain types of customizability (such as the formatting of help pages) to maintain a core promise: multiple Click instances will continue to function as intended when strung together.

By enforcing certain hardcoded behaviors and standard paradigms, Click ensures:

• Consistency: A predictable command-line experience across different tools.
• Reliability: Avoiding 'magical' behaviors like automatic parameter correction, which can break backwards compatibility if new parameters are added later.
• Predictability: Avoiding the syntactical ambiguities found in other libraries (like optparse) when handling variadic arguments.

Click supports POSIX-style short option stacking. For example, -abc is equivalent to -a -b -c if a, b, and c are single-character flags.

If you want to count how many times an option is provided (common for verbosity levels), set count=True. If the option is not provided, the value is 0.

@click.command()
@click.option('-v', '--verbose', count=True)
def log(verbose):
    click.echo(f"Verbosity: {verbose}")

# Usage:
# log() -> 0
# log('-vvv') -> 3

If you do not provide a second positional argument to @click.option(), Click attempts to infer the name of the decorated function's argument.

To ensure correct inference, name your CLI option by taking the function argument name, adding -- to the front, and replacing underscores with dashes. For example, a function argument foo_bar should have an option --foo-bar.

Inference logic:

1. If a positional argument is a valid Python identifier (no dashes), it is used.
2. If multiple arguments are prefixed with --, the first one declared is used.
3. Otherwise, the first argument prefixed with - is used.

The name is processed by converting to lowercase, removing leading - or --, and replacing remaining - with _.

@click.command()
@click.option('--string-to-echo')  # Inferred as 'string_to_echo'
def echo(string_to_echo):
    click.echo(string_to_echo)

Commands are isolated by default. To allow a parent command to pass data to a nested subcommand, use the Context object.

1. Accessing Context: Decorate a command with @click.pass_context to receive the ctx object as the first argument.
2. Storing Data: Use ctx.obj to store a shared object (typically a dict). Use ctx.ensure_object(dict) in the group callback to initialize it safely.
3. Accessing Data: Subcommands decorated with @click.pass_context can then read from ctx.obj.

@click.group()
@click.option('--debug/--no-debug', default=False)
@click.pass_context
def cli(ctx, debug):
    ctx.ensure_object(dict)
    ctx.obj['DEBUG'] = debug

@cli.command()
@click.pass_context
def sync(ctx):
    click.echo(f"Debug is {'on' if ctx.obj['DEBUG'] else 'off'}")

if __name__ == '__main__':
    cli(obj={})

The behavior of the default parameter depends on whether the flag is boolean or non-boolean:

Non-boolean flags (e.g., flag_value='upper')

There is a special shorthand: if you set default=True, Click interprets this as "activate this flag by default" and passes the actual flag_value to your function instead of the Python True object.

Recommendation: To avoid confusion, always use the explicit value instead of the shorthand.

• Avoid: @click.option('--upper', flag_value='upper', default=True)
• Prefer: @click.option('--upper', flag_value='upper', default='upper')

Boolean flags (e.g., flag_value=True or False)

There is no shorthand. default=True is passed to your function as the literal Python True object.

Click uses exceptions to signal error conditions, primarily incorrect usage. When using Command.main, Click follows a specific error handling lifecycle:

1. EOFError or KeyboardInterrupt: These are re-raised as Abort.
2. ClickException: Click calls ClickException.show() to display the error to the user and exits with the value of ClickException.exit_code.
3. Abort: Click prints Aborted! to stderr and exits with code 1.
4. Success: If no exceptions occur, the program exits with code 0.

Note that triggering a help page via --help returns exit code 0. However, if a help page is displayed automatically due to incorrect user input, the program returns exit code 2.