Quickstart

You can get the library directly from PyPI:

pip install click

Screencast and Examples

There is a screencast available which shows the basic API of click and how to build simple applications with it. It also explores how to build commands with subcommands.

Examples of click applications can be found in the documentation as well as in the GitHub repository together with readme files:

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(). At its simplest, 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.

As an added benefit, starting with click 2.0, the echo function also has good support for ANSI colors. It will automatically strip ANSI codes if the output stream is a file and if colorama is supported, ANSI colors will also work on Windows. See ANSI Colors for more information.

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 instead be written like this:

@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, use 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.