Navigation

I recommend click
module to build command line applications. Like any other project from Armin
Ronacher, it has great documentation. In this
post, I am going to write a beginners tutorial, you should the read the
documentation for any more details and examples.

Using virtualenv is highly recommended for developing “click” applications. I
am going to assume that we are in an empty directory and the continue from
there. To start, we will have a simple hello.py file with the following
content:

defcli():print("Hello World")

Now we will need a setup.py file. This will help us to use the python module we
are writing as a command line tool. It is also the recommended way to write
command line tools in python, then directly using shebang based scripts.

You can see that we mentioned the starting point of our tool in the
entry_points, hello:cli points to the right function to start with. We can
then install this on the virtualenv locally. I will also create the virtualenv
below so that becomes easier others. To learn more, read this
chapter later.

Now to convert the same script into a click based tool, we will make the
following modifications. Now when we execute the command again, we see nothing
changed visually, but it magically has a –help command line argument (which
is optional).

In a command line tool, we sometimes want to have a boolean option. If the
option is provided then do something, if not provided, then do something else.
In our example, we will call the flag as –verbose, it is provided, then we
will print some extra text.

importclick@click.command()@click.option('--verbose',is_flag=True,help="Will print verbose messages.")defcli(verbose):ifverbose:click.echo("We are in the verbose mode.")click.echo("Hello World")

We added another decorator to the cli function. In click.option() decorator,
first we passed the flag using –verbose, then marked this option as a
boolean flag, and then finally added the help text.

$ myhello --help
Usage: myhello [OPTIONS]
Options:
--verbose Will print verbose messages.
--help Show this message and exit.
$ myhello --verbose
We are in the verbose mode.
Hello World

By default, any boolean flag is treated as false.

### Standard options in the command line

We can now add more options to our tool. For example, we will have a –name
option which will take a string as input.

importclick@click.command()@click.option('--verbose',is_flag=True,help="Will print verbose messages.")@click.option('--name',default='',help='Who are you?')defcli(verbose,name):ifverbose:click.echo("We are in the verbose mode.")click.echo("Hello World")click.echo('Bye {0}'.format(name))

We may want to take the same option multiple times. Click has a very simple way to do so.

importclick@click.command()@click.option('--verbose',is_flag=True,help="Will print verbose messages.")@click.option('--name','-n',multiple=True,default='',help='Who are you?')defcli(verbose,name):ifverbose:click.echo("We are in the verbose mode.")click.echo("Hello World")forninname:click.echo('Bye {0}'.format(n))

In the above example, you can see that we specified the –name as a multiple
options. It also means the name parameter in the cli function is now a tuple.

### Help text for the script

We can add help text for the script using python docstrings. For example:

importclick@click.command()@click.option('--verbose',is_flag=True,help="Will print verbose messages.")@click.option('--name','-n',multiple=True,default='',help='Who are you?')defcli(verbose,name):"""This is an example script to learn Click."""ifverbose:click.echo("We are in the verbose mode.")click.echo("Hello World")forninname:click.echo('Bye {0}'.format(n))

$ myhello --help
Usage: myhello [OPTIONS]
This is an example script to learn Click.
Options:
--verbose Will print verbose messages.
-n, --name TEXT Who are you?
--help Show this message and exit.

Click provides a password_option() decorator, which can be used to accept a
password over hidden prompt and second confirmation prompt. Btw, I am printing
the password here as an example, never print the password to stdout in any
tool.

importclick@click.command()@click.option('--verbose',is_flag=True,help="Will print verbose messages.")@click.option('--name','-n',multiple=True,default='',help='Who are you?')@click.password_option()defcli(verbose,name,password):"""This is an example script to learn Click."""ifverbose:click.echo("We are in the verbose mode.")click.echo("Hello World")forninname:click.echo('Bye {0}'.format(n))click.echo('We received {0} as password.'.format(password))

The output looks like below:

$ myhello --help
Usage: myhello [OPTIONS]
This is an example script to learn Click.
Options:
--verbose Will print verbose messages.
-n, --name TEXT Who are you?
--password TEXT
--help Show this message and exit.
$ myhello
Password:
Repeat for confirmation:
Hello World
We received hello as password.

You can also add arguments to your tool. These are must haves, and if no
default value is provided, they are assumed to be strings. In the below
example, the script is expecting a county name to be specified.

importclick@click.command()@click.option('--verbose',is_flag=True,help="Will print verbose messages.")@click.option('--name','-n',multiple=True,default='',help='Who are you?')@click.argument('country')defcli(verbose,name,country):"""This is an example script to learn Click."""ifverbose:click.echo("We are in the verbose mode.")click.echo("Hello {0}".format(country))forninname:click.echo('Bye {0}'.format(n))