Quickstart

You can get the library directly from PyPI:

pip install click

Basic Concepts

Click is based on declaring commands through decorators. Internally there is a non-decorator interface for advanced use cases but it’s discouraged for high-level usage.

A function becomes a click command line tool by decorating it through click.command(). In the most simple version just decorating a function with this decorator will make it into a callable script:

import click

@click.command()
def hello():
    click.echo('Hello World!')

What’s happening is that the decorator converts the function into a Command which then can be invoked:

if __name__ == '__main__':
    hello()

And what it looks like:

$ hello
Hello World!

And the corresponding help page:

$ hello --help
Usage: hello [OPTIONS]

Options:
  --help  Show this message and exit.

Echoing

Why does this example use echo() instead of the regular print() function? The answer to this question is that click attempts to support both Python 2 and Python 3 the same way and to be very robust even when the environment is misconfigured. Click wants to be functional at least on a basic level even if everything is completely broken.

What this means is that the echo() function applies some error correction in case the terminal is misconfigured instead of dying with an UnicodeError.

If you don’t need this, you can also use the print() construct / function.

Nesting Commands

Commands can be attached to other commands of type Group. This allows arbitrary nesting of scripts. As an example here is a script that implements two commands for managing databases:

@click.group()
def cli():
    pass

@click.command()
def initdb():
    click.echo('Initialized the database')

@click.command()
def dropdb():
    click.echo('Dropped the database')

cli.add_command(initdb)
cli.add_command(dropdb)

As you can see the group() decorator works like the command() decorator but creates a Group object instead which can be given multiple subcommands that can be attached with Group.add_command().

For simple scripts it’s also possible to automatically attach and create a command by using the Group.command() decorator instead. The above script can be written like this then:

@click.group()
def cli():
    pass

@cli.command()
def initdb():
    click.echo('Initialized the database')

@cli.command()
def dropdb():
    click.echo('Dropped the database')

Adding Parameters

To add parameters the option() and argument() decorators:

@click.command()
@click.option('--count', default=1, help='number of greetings')
@click.argument('name')
def hello(count, name):
    for x in range(count):
        click.echo('Hello %s!' % name)

What it looks like:

$ hello --help
Usage: hello [OPTIONS] NAME

Options:
  --count INTEGER  number of greetings
  --help           Show this message and exit.