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:
inout
: File input and outputnaval
: Port of docopt naval examplealiases
: Command alias examplecomplex
: Complex example with plugin loadingvalidation
: Custom parameter validation examplecolors
: Colorama ANSI color supporttermui
: Terminal UI functions demo
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.