# Advanced Patterns

In addition to common functionality that is implemented in the library itself,
there are countless patterns that can be implemented by extending Click. This
page should give some insight into what can be accomplished.

## Command Aliases

Many tools support aliases for commands (see [Command alias
example](https://github.com/pallets/click/tree/main/examples/aliases)). For
instance, you can configure `git` to accept `git ci` as alias for `git
commit`. Other tools also support auto-discovery for aliases by automatically
shortening them.

Click does not support this out of the box, but it’s very easy to customize
the [`Group`](../api/index#click.Group "click.Group") or any other
[`MultiCommand`](../api/index#click.MultiCommand "click.MultiCommand") to
provide this functionality.

As explained in [Custom Multi Commands](../commands/index#custom-multi-
commands), a multi command can provide two methods:
[`list_commands()`](../api/index#click.MultiCommand.list_commands
"click.MultiCommand.list_commands") and
[`get_command()`](../api/index#click.MultiCommand.get_command
"click.MultiCommand.get_command"). In this particular case, you only need to
override the latter as you generally don’t want to enumerate the aliases on
the help page in order to avoid confusion.

This following example implements a subclass of
[`Group`](../api/index#click.Group "click.Group") that accepts a prefix for a
command. If there were a command called `push`, it would accept `pus` as an
alias (so long as it was unique):

    
    
    class AliasedGroup(click.Group):
        def get_command(self, ctx, cmd_name):
            rv = click.Group.get_command(self, ctx, cmd_name)
            if rv is not None:
                return rv
            matches = [x for x in self.list_commands(ctx)
                       if x.startswith(cmd_name)]
            if not matches:
                return None
            elif len(matches) == 1:
                return click.Group.get_command(self, ctx, matches[0])
            ctx.fail(f"Too many matches: {', '.join(sorted(matches))}")
    
        def resolve_command(self, ctx, args):
            # always return the full command name
            _, cmd, args = super().resolve_command(ctx, args)
            return cmd.name, cmd, args
    

And it can then be used like this:

    
    
    @click.command(cls=AliasedGroup)
    def cli():
        pass
    
    @cli.command()
    def push():
        pass
    
    @cli.command()
    def pop():
        pass
    

## Parameter Modifications

Parameters (options and arguments) are forwarded to the command callbacks as
you have seen. One common way to prevent a parameter from being passed to the
callback is the `expose_value` argument to a parameter which hides the
parameter entirely. The way this works is that the
[`Context`](../api/index#click.Context "click.Context") object has a
[`params`](../api/index#click.Context.params "click.Context.params") attribute
which is a dictionary of all parameters. Whatever is in that dictionary is
being passed to the callbacks.

This can be used to make up additional parameters. Generally this pattern is
not recommended but in some cases it can be useful. At the very least it’s
good to know that the system works this way.

    
    
    import urllib
    
    def open_url(ctx, param, value):
        if value is not None:
            ctx.params['fp'] = urllib.urlopen(value)
            return value
    
    @click.command()
    @click.option('--url', callback=open_url)
    def cli(url, fp=None):
        if fp is not None:
            click.echo(f"{url}: {fp.code}")
    

In this case the callback returns the URL unchanged but also passes a second
`fp` value to the callback. What’s more recommended is to pass the information
in a wrapper however:

    
    
    import urllib
    
    class URL(object):
    
        def __init__(self, url, fp):
            self.url = url
            self.fp = fp
    
    def open_url(ctx, param, value):
        if value is not None:
            return URL(value, urllib.urlopen(value))
    
    @click.command()
    @click.option('--url', callback=open_url)
    def cli(url):
        if url is not None:
            click.echo(f"{url.url}: {url.fp.code}")
    

## Token Normalization

Changelog

New in version 2.0.

Starting with Click 2.0, it’s possible to provide a function that is used for
normalizing tokens. Tokens are option names, choice values, or command values.
This can be used to implement case insensitive options, for instance.

In order to use this feature, the context needs to be passed a function that
performs the normalization of the token. For instance, you could have a
function that converts the token to lowercase:

    
    
    CONTEXT_SETTINGS = dict(token_normalize_func=lambda x: x.lower())
    
    @click.command(context_settings=CONTEXT_SETTINGS)
    @click.option('--name', default='Pete')
    def cli(name):
        click.echo(f"Name: {name}")
    

And how it works on the command line:

    
    
    $ cli --NAME=Pete
    Name: Pete
    

## Invoking Other Commands

Sometimes, it might be interesting to invoke one command from another command.
This is a pattern that is generally discouraged with Click, but possible
nonetheless. For this, you can use the
[`Context.invoke()`](../api/index#click.Context.invoke "click.Context.invoke")
or [`Context.forward()`](../api/index#click.Context.forward
"click.Context.forward") methods.

They work similarly, but the difference is that
[`Context.invoke()`](../api/index#click.Context.invoke "click.Context.invoke")
merely invokes another command with the arguments you provide as a caller,
whereas [`Context.forward()`](../api/index#click.Context.forward
"click.Context.forward") fills in the arguments from the current command. Both
accept the command as the first argument and everything else is passed onwards
as you would expect.

Example:

    
    
    cli = click.Group()
    
    @cli.command()
    @click.option('--count', default=1)
    def test(count):
        click.echo(f'Count: {count}')
    
    @cli.command()
    @click.option('--count', default=1)
    @click.pass_context
    def dist(ctx, count):
        ctx.forward(test)
        ctx.invoke(test, count=42)
    

And what it looks like:

    
    
    $ cli dist
    Count: 1
    Count: 42
    

## Callback Evaluation Order

Click works a bit differently than some other command line parsers in that it
attempts to reconcile the order of arguments as defined by the programmer with
the order of arguments as defined by the user before invoking any callbacks.

This is an important concept to understand when porting complex patterns to
Click from optparse or other systems. A parameter callback invocation in
optparse happens as part of the parsing step, whereas a callback invocation in
Click happens after the parsing.

The main difference is that in optparse, callbacks are invoked with the raw
value as it happens, whereas a callback in Click is invoked after the value
has been fully converted.

Generally, the order of invocation is driven by the order in which the user
provides the arguments to the script; if there is an option called `--foo` and
an option called `--bar` and the user calls it as `--bar --foo`, then the
callback for `bar` will fire before the one for `foo`.

There are three exceptions to this rule which are important to know:

Eagerness:

    

An option can be set to be “eager”. All eager parameters are evaluated before
all non-eager parameters, but again in the order as they were provided on the
command line by the user.

This is important for parameters that execute and exit like `--help` and
`--version`. Both are eager parameters, but whatever parameter comes first on
the command line will win and exit the program.

Repeated parameters:

    

If an option or argument is split up on the command line into multiple places
because it is repeated – for instance, `--exclude foo --include baz --exclude
bar` – the callback will fire based on the position of the first option. In
this case, the callback will fire for `exclude` and it will be passed both
options (`foo` and `bar`), then the callback for `include` will fire with
`baz` only.

Note that even if a parameter does not allow multiple versions, Click will
still accept the position of the first, but it will ignore every value except
the last. The reason for this is to allow composability through shell aliases
that set defaults.

Missing parameters:

    

If a parameter is not defined on the command line, the callback will still
fire. This is different from how it works in optparse where undefined values
do not fire the callback. Missing parameters fire their callbacks at the very
end which makes it possible for them to default to values from a parameter
that came before.

Most of the time you do not need to be concerned about any of this, but it is
important to know how it works for some advanced cases.

## Forwarding Unknown Options

In some situations it is interesting to be able to accept all unknown options
for further manual processing. Click can generally do that as of Click 4.0,
but it has some limitations that lie in the nature of the problem. The support
for this is provided through a parser flag called `ignore_unknown_options`
which will instruct the parser to collect all unknown options and to put them
to the leftover argument instead of triggering a parsing error.

This can generally be activated in two different ways:

  1. It can be enabled on custom [`Command`](../api/index#click.Command "click.Command") subclasses by changing the [`ignore_unknown_options`](../api/index#click.BaseCommand.ignore_unknown_options "click.BaseCommand.ignore_unknown_options") attribute.
  2. It can be enabled by changing the attribute of the same name on the context class ([`Context.ignore_unknown_options`](../api/index#click.Context.ignore_unknown_options "click.Context.ignore_unknown_options")). This is best changed through the `context_settings` dictionary on the command.

For most situations the easiest solution is the second. Once the behavior is
changed something needs to pick up those leftover options (which at this point
are considered arguments). For this again you have two options:

  1. You can use [`pass_context()`](../api/index#click.pass_context "click.pass_context") to get the context passed. This will only work if in addition to [`ignore_unknown_options`](../api/index#click.Context.ignore_unknown_options "click.Context.ignore_unknown_options") you also set [`allow_extra_args`](../api/index#click.Context.allow_extra_args "click.Context.allow_extra_args") as otherwise the command will abort with an error that there are leftover arguments. If you go with this solution, the extra arguments will be collected in [`Context.args`](../api/index#click.Context.args "click.Context.args").
  2. You can attach an [`argument()`](../api/index#click.argument "click.argument") with `nargs` set to `-1` which will eat up all leftover arguments. In this case it’s recommended to set the `type` to [`UNPROCESSED`](../api/index#click.UNPROCESSED "click.UNPROCESSED") to avoid any string processing on those arguments as otherwise they are forced into unicode strings automatically which is often not what you want.

In the end you end up with something like this:

    
    
    import sys
    from subprocess import call
    
    @click.command(context_settings=dict(
        ignore_unknown_options=True,
    ))
    @click.option('-v', '--verbose', is_flag=True, help='Enables verbose mode')
    @click.argument('timeit_args', nargs=-1, type=click.UNPROCESSED)
    def cli(verbose, timeit_args):
        """A fake wrapper around Python's timeit."""
        cmdline = ['echo', 'python', '-mtimeit'] + list(timeit_args)
        if verbose:
            click.echo(f"Invoking: {' '.join(cmdline)}")
        call(cmdline)
    

And what it looks like:

    
    
    $ cli --help
    Usage: cli [OPTIONS] [TIMEIT_ARGS]...
    
      A fake wrapper around Python's timeit.
    
    Options:
      -v, --verbose  Enables verbose mode
      --help         Show this message and exit.
    
    $ cli -n 100 'a = 1; b = 2; a * b'
    python -mtimeit -n 100 a = 1; b = 2; a * b
    
    $ cli -v 'a = 1; b = 2; a * b'
    Invoking: echo python -mtimeit a = 1; b = 2; a * b
    python -mtimeit a = 1; b = 2; a * b
    

As you can see the verbosity flag is handled by Click, everything else ends up
in the `timeit_args` variable for further processing which then for instance,
allows invoking a subprocess. There are a few things that are important to
know about how this ignoring of unhandled flag happens:

  * Unknown long options are generally ignored and not processed at all. So for instance if `--foo=bar` or `--foo bar` are passed they generally end up like that. Note that because the parser cannot know if an option will accept an argument or not, the `bar` part might be handled as an argument.
  * Unknown short options might be partially handled and reassembled if necessary. For instance in the above example there is an option called `-v` which enables verbose mode. If the command would be ignored with `-va` then the `-v` part would be handled by Click (as it is known) and `-a` would end up in the leftover parameters for further processing.
  * Depending on what you plan on doing you might have some success by disabling interspersed arguments ([`allow_interspersed_args`](../api/index#click.Context.allow_interspersed_args "click.Context.allow_interspersed_args")) which instructs the parser to not allow arguments and options to be mixed. Depending on your situation this might improve your results.

Generally though the combined handling of options and arguments from your own
commands and commands from another application are discouraged and if you can
avoid it, you should. It’s a much better idea to have everything below a
subcommand be forwarded to another application than to handle some arguments
yourself.

## Global Context Access

Changelog

New in version 5.0.

Starting with Click 5.0 it is possible to access the current context from
anywhere within the same thread through the use of the
[`get_current_context()`](../api/index#click.get_current_context
"click.get_current_context") function which returns it. This is primarily
useful for accessing the context bound object as well as some flags that are
stored on it to customize the runtime behavior. For instance the
[`echo()`](../api/index#click.echo "click.echo") function does this to infer
the default value of the `color` flag.

Example usage:

    
    
    def get_current_command_name():
        return click.get_current_context().info_name
    

It should be noted that this only works within the current thread. If you
spawn additional threads then those threads will not have the ability to refer
to the current context. If you want to give another thread the ability to
refer to this context you need to use the context within the thread as a
context manager:

    
    
    def spawn_thread(ctx, func):
        def wrapper():
            with ctx:
                func()
        t = threading.Thread(target=wrapper)
        t.start()
        return t
    

Now the thread function can access the context like the main thread would do.
However if you do use this for threading you need to be very careful as the
vast majority of the context is not thread safe! You are only allowed to read
from the context, but not to perform any modifications on it.

## Detecting the Source of a Parameter

In some situations it’s helpful to understand whether or not an option or
parameter came from the command line, the environment, the default value, or
`Context.default_map`. The
[`Context.get_parameter_source()`](../api/index#click.Context.get_parameter_source
"click.Context.get_parameter_source") method can be used to find this out. It
will return a member of the
[`ParameterSource`](../api/index#click.core.ParameterSource
"click.core.ParameterSource") enum.

    
    
    @click.command()
    @click.argument('port', nargs=1, default=8080, envvar="PORT")
    @click.pass_context
    def cli(ctx, port):
        source = ctx.get_parameter_source("port")
        click.echo(f"Port came from {source.name}")
    
    
    
    $ cli 8080
    Port came from COMMANDLINE
    
    $ export PORT=8080
    $ cli
    Port came from ENVIRONMENT
    
    $ cli
    Port came from DEFAULT
    

## Managing Resources

It can be useful to open a resource in a group, to be made available to
subcommands. Many types of resources need to be closed or otherwise cleaned up
after use. The standard way to do this in Python is by using a context manager
with the `with` statement.

For example, the `Repo` class from [Complex Applications](../complex/index)
might actually be defined as a context manager:

    
    
    class Repo:
        def __init__(self, home=None):
            self.home = os.path.abspath(home or ".")
            self.db = None
    
        def __enter__(self):
            path = os.path.join(self.home, "repo.db")
            self.db = open_database(path)
            return self
    
        def __exit__(self, exc_type, exc_value, tb):
            self.db.close()
    

Ordinarily, it would be used with the `with` statement:

    
    
    with Repo() as repo:
        repo.db.query(...)
    

However, a `with` block in a group would exit and close the database before it
could be used by a subcommand.

Instead, use the context’s
[`with_resource()`](../api/index#click.Context.with_resource
"click.Context.with_resource") method to enter the context manager and return
the resource. When the group and any subcommands finish, the context’s
resources are cleaned up.

    
    
    @click.group()
    @click.option("--repo-home", default=".repo")
    @click.pass_context
    def cli(ctx, repo_home):
        ctx.obj = ctx.with_resource(Repo(repo_home))
    
    @cli.command()
    @click.pass_obj
    def log(obj):
        # obj is the repo opened in the cli group
        for entry in obj.db.query(...):
            click.echo(entry)
    

If the resource isn’t a context manager, usually it can be wrapped in one
using something from
[`contextlib`](https://docs.python.org/3/library/contextlib.html#module-
contextlib "\(in Python v3.12\)"). If that’s not possible, use the context’s
[`call_on_close()`](../api/index#click.Context.call_on_close
"click.Context.call_on_close") method to register a cleanup function.

    
    
    @click.group()
    @click.option("--name", default="repo.db")
    @click.pass_context
    def cli(ctx, repo_home):
        ctx.obj = db = open_db(repo_home)
    
        @ctx.call_on_close
        def close_db():
            db.record_use()
            db.save()
            db.close()
    

# Arguments

Arguments work similarly to [options](../options/index#options) but are
positional. They also only support a subset of the features of options due to
their syntactical nature. Click will also not attempt to document arguments
for you and wants you to [document them
manually](../documentation/index#documenting-arguments) in order to avoid ugly
help pages.

## Basic Arguments

The most basic option is a simple string argument of one value. If no type is
provided, the type of the default value is used, and if no default value is
provided, the type is assumed to be [`STRING`](../api/index#click.STRING
"click.STRING").

Example:

    
    
    @click.command()
    @click.argument('filename')
    def touch(filename):
        """Print FILENAME."""
        click.echo(filename)
    

And what it looks like:

    
    
    $ touch foo.txt
    foo.txt
    

## Variadic Arguments

The second most common version is variadic arguments where a specific (or
unlimited) number of arguments is accepted. This can be controlled with the
`nargs` parameter. If it is set to `-1`, then an unlimited number of arguments
is accepted.

The value is then passed as a tuple. Note that only one argument can be set to
`nargs=-1`, as it will eat up all arguments.

Example:

    
    
    @click.command()
    @click.argument('src', nargs=-1)
    @click.argument('dst', nargs=1)
    def copy(src, dst):
        """Move file SRC to DST."""
        for fn in src:
            click.echo(f"move {fn} to folder {dst}")
    

And what it looks like:

    
    
    $ copy foo.txt bar.txt my_folder
    move foo.txt to folder my_folder
    move bar.txt to folder my_folder
    

Note that this is not how you would write this application. The reason for
this is that in this particular example the arguments are defined as strings.
Filenames, however, are not strings! They might be on certain operating
systems, but not necessarily on all. For better ways to write this, see the
next sections.

Note on Non-Empty Variadic Arguments

If you come from `argparse`, you might be missing support for setting `nargs`
to `+` to indicate that at least one argument is required.

This is supported by setting `required=True`. However, this should not be used
if you can avoid it as we believe scripts should gracefully degrade into
becoming noops if a variadic argument is empty. The reason for this is that
very often, scripts are invoked with wildcard inputs from the command line and
they should not error out if the wildcard is empty.

## File Arguments

Since all the examples have already worked with filenames, it makes sense to
explain how to deal with files properly. Command line tools are more fun if
they work with files the Unix way, which is to accept `-` as a special file
that refers to stdin/stdout.

Click supports this through the [`click.File`](../api/index#click.File
"click.File") type which intelligently handles files for you. It also deals
with Unicode and bytes correctly for all versions of Python so your script
stays very portable.

Example:

    
    
    @click.command()
    @click.argument('input', type=click.File('rb'))
    @click.argument('output', type=click.File('wb'))
    def inout(input, output):
        """Copy contents of INPUT to OUTPUT."""
        while True:
            chunk = input.read(1024)
            if not chunk:
                break
            output.write(chunk)
    

And what it does:

    
    
    $ inout - hello.txt
    hello
    ^D
    $ inout hello.txt -
    hello
    

## File Path Arguments

In the previous example, the files were opened immediately. But what if we
just want the filename? The naïve way is to use the default string argument
type. The [`Path`](../api/index#click.Path "click.Path") type has several
checks available which raise nice errors if they fail, such as existence.
Filenames in these error messages are formatted with
[`format_filename()`](../api/index#click.format_filename
"click.format_filename"), so any undecodable bytes will be printed nicely.

Example:

    
    
    @click.command()
    @click.argument('filename', type=click.Path(exists=True))
    def touch(filename):
        """Print FILENAME if the file exists."""
        click.echo(click.format_filename(filename))
    

And what it does:

    
    
    $ touch hello.txt
    hello.txt
    
    $ touch missing.txt
    Usage: touch [OPTIONS] FILENAME
    Try 'touch --help' for help.
    
    Error: Invalid value for 'FILENAME': Path 'missing.txt' does not exist.
    

## File Opening Safety

The `FileType` type has one problem it needs to deal with, and that is to
decide when to open a file. The default behavior is to be “intelligent” about
it. What this means is that it will open stdin/stdout and files opened for
reading immediately. This will give the user direct feedback when a file
cannot be opened, but it will only open files for writing the first time an IO
operation is performed by automatically wrapping the file in a special
wrapper.

This behavior can be forced by passing `lazy=True` or `lazy=False` to the
constructor. If the file is opened lazily, it will fail its first IO operation
by raising an [`FileError`](../api/index#click.FileError "click.FileError").

Since files opened for writing will typically immediately empty the file, the
lazy mode should only be disabled if the developer is absolutely sure that
this is intended behavior.

Forcing lazy mode is also very useful to avoid resource handling confusion. If
a file is opened in lazy mode, it will receive a `close_intelligently` method
that can help figure out if the file needs closing or not. This is not needed
for parameters, but is necessary for manually prompting with the
[`prompt()`](../api/index#click.prompt "click.prompt") function as you do not
know if a stream like stdout was opened (which was already open before) or a
real file that needs closing.

Starting with Click 2.0, it is also possible to open files in atomic mode by
passing `atomic=True`. In atomic mode, all writes go into a separate file in
the same folder, and upon completion, the file will be moved over to the
original location. This is useful if a file regularly read by other users is
modified.

## Environment Variables

Like options, arguments can also grab values from an environment variable.
Unlike options, however, this is only supported for explicitly named
environment variables.

Example usage:

    
    
    @click.command()
    @click.argument('src', envvar='SRC', type=click.File('r'))
    def echo(src):
        """Print value of SRC environment variable."""
        click.echo(src.read())
    

And from the command line:

    
    
    $ export SRC=hello.txt
    $ echo
    Hello World!
    

In that case, it can also be a list of different environment variables where
the first one is picked.

Generally, this feature is not recommended because it can cause the user a lot
of confusion.

## Option-Like Arguments

Sometimes, you want to process arguments that look like options. For instance,
imagine you have a file named `-foo.txt`. If you pass this as an argument in
this manner, Click will treat it as an option.

To solve this, Click does what any POSIX style command line script does, and
that is to accept the string `--` as a separator for options and arguments.
After the `--` marker, all further parameters are accepted as arguments.

Example usage:

    
    
    @click.command()
    @click.argument('files', nargs=-1, type=click.Path())
    def touch(files):
        """Print all FILES file names."""
        for filename in files:
            click.echo(filename)
    

And from the command line:

    
    
    $ touch -- -foo.txt bar.txt
    -foo.txt
    bar.txt
    

If you don’t like the `--` marker, you can set ignore_unknown_options to True
to avoid checking unknown options:

    
    
    @click.command(context_settings={"ignore_unknown_options": True})
    @click.argument('files', nargs=-1, type=click.Path())
    def touch(files):
        """Print all FILES file names."""
        for filename in files:
            click.echo(filename)
    

And from the command line:

    
    
    $ touch -foo.txt bar.txt
    -foo.txt
    bar.txt
    

# Commands and Groups

The most important feature of Click is the concept of arbitrarily nesting
command line utilities. This is implemented through the
[`Command`](../api/index#click.Command "click.Command") and
[`Group`](../api/index#click.Group "click.Group") (actually
[`MultiCommand`](../api/index#click.MultiCommand "click.MultiCommand")).

## Callback Invocation

For a regular command, the callback is executed whenever the command runs. If
the script is the only command, it will always fire (unless a parameter
callback prevents it. This for instance happens if someone passes `--help` to
the script).

For groups and multi commands, the situation looks different. In this case,
the callback fires whenever a subcommand fires (unless this behavior is
changed). What this means in practice is that an outer command runs when an
inner command runs:

    
    
    @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()  # @cli, not @click!
    def sync():
        click.echo('Syncing')
    

Here is what this looks like:

    
    
    $ tool.py
    Usage: tool.py [OPTIONS] COMMAND [ARGS]...
    
    Options:
      --debug / --no-debug
      --help                Show this message and exit.
    
    Commands:
      sync
    
    $ tool.py --debug sync
    Debug mode is on
    Syncing
    

## Passing Parameters

Click strictly separates parameters between commands and subcommands. What
this means is that options and arguments for a specific command have to be
specified _after_ the command name itself, but _before_ any other command
names.

This behavior is already observable with the predefined `--help` option.
Suppose we have a program called `tool.py`, containing a subcommand called
`sub`.

  * `tool.py --help` will return the help for the whole program (listing subcommands).
  * `tool.py sub --help` will return the help for the `sub` subcommand.
  * But `tool.py --help sub` will treat `--help` as an argument for the main program. Click then invokes the callback for `--help`, which prints the help and aborts the program before click can process the subcommand.

## Nested Handling and Contexts

As you can see from the earlier example, the basic command group accepts a
debug argument which is passed to its callback, but not to the sync command
itself. The sync command only accepts its own arguments.

This allows tools to act completely independent of each other, but how does
one command talk to a nested one? The answer to this is the
[`Context`](../api/index#click.Context "click.Context").

Each time a command is invoked, a new context is created and linked with the
parent context. Normally, you can’t see these contexts, but they are there.
Contexts are passed to parameter callbacks together with the value
automatically. Commands can also ask for the context to be passed by marking
themselves with the [`pass_context()`](../api/index#click.pass_context
"click.pass_context") decorator. In that case, the context is passed as first
argument.

The context can also carry a program specified object that can be used for the
program’s purposes. What this means is that you can build a script like this:

    
    
    @click.group()
    @click.option('--debug/--no-debug', default=False)
    @click.pass_context
    def cli(ctx, debug):
        # ensure that ctx.obj exists and is a dict (in case `cli()` is called
        # by means other than the `if` block below)
        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={})
    

If the object is provided, each context will pass the object onwards to its
children, but at any level a context’s object can be overridden. To reach to a
parent, `context.parent` can be used.

In addition to that, instead of passing an object down, nothing stops the
application from modifying global state. For instance, you could just flip a
global `DEBUG` variable and be done with it.

## Decorating Commands

As you have seen in the earlier example, a decorator can change how a command
is invoked. What actually happens behind the scenes is that callbacks are
always invoked through the
[`Context.invoke()`](../api/index#click.Context.invoke "click.Context.invoke")
method which automatically invokes a command correctly (by either passing the
context or not).

This is very useful when you want to write custom decorators. For instance, a
common pattern would be to configure an object representing state and then
storing it on the context and then to use a custom decorator to find the most
recent object of this sort and pass it as first argument.

For instance, the [`pass_obj()`](../api/index#click.pass_obj "click.pass_obj")
decorator can be implemented like this:

    
    
    from functools import update_wrapper
    
    def pass_obj(f):
        @click.pass_context
        def new_func(ctx, *args, **kwargs):
            return ctx.invoke(f, ctx.obj, *args, **kwargs)
        return update_wrapper(new_func, f)
    

The [`Context.invoke()`](../api/index#click.Context.invoke
"click.Context.invoke") command will automatically invoke the function in the
correct way, so the function will either be called with `f(ctx, obj)` or
`f(obj)` depending on whether or not it itself is decorated with
[`pass_context()`](../api/index#click.pass_context "click.pass_context").

This is a very powerful concept that can be used to build very complex nested
applications; see [Complex Applications](../complex/index#complex-guide) for
more information.

## Group Invocation Without Command

By default, a group or multi command is not invoked unless a subcommand is
passed. In fact, not providing a command automatically passes `--help` by
default. This behavior can be changed by passing `invoke_without_command=True`
to a group. In that case, the callback is always invoked instead of showing
the help page. The context object also includes information about whether or
not the invocation would go to a subcommand.

Example:

    
    
    @click.group(invoke_without_command=True)
    @click.pass_context
    def cli(ctx):
        if ctx.invoked_subcommand is None:
            click.echo('I was invoked without subcommand')
        else:
            click.echo(f"I am about to invoke {ctx.invoked_subcommand}")
    
    @cli.command()
    def sync():
        click.echo('The subcommand')
    

And how it works in practice:

    
    
    $ tool
    I was invoked without subcommand
    $ tool sync
    I am about to invoke sync
    The subcommand
    

## Custom Multi Commands

In addition to using [`click.group()`](../api/index#click.group
"click.group"), you can also build your own custom multi commands. This is
useful when you want to support commands being loaded lazily from plugins.

A custom multi command just needs to implement a list and load method:

    
    
    import click
    import os
    
    plugin_folder = os.path.join(os.path.dirname(__file__), 'commands')
    
    class MyCLI(click.MultiCommand):
    
        def list_commands(self, ctx):
            rv = []
            for filename in os.listdir(plugin_folder):
                if filename.endswith('.py') and filename != '__init__.py':
                    rv.append(filename[:-3])
            rv.sort()
            return rv
    
        def get_command(self, ctx, name):
            ns = {}
            fn = os.path.join(plugin_folder, name + '.py')
            with open(fn) as f:
                code = compile(f.read(), fn, 'exec')
                eval(code, ns, ns)
            return ns['cli']
    
    cli = MyCLI(help='This tool\'s subcommands are loaded from a '
                'plugin folder dynamically.')
    
    if __name__ == '__main__':
        cli()
    

These custom classes can also be used with decorators:

    
    
    @click.command(cls=MyCLI)
    def cli():
        pass
    

## Merging Multi Commands

In addition to implementing custom multi commands, it can also be interesting
to merge multiple together into one script. While this is generally not as
recommended as it nests one below the other, the merging approach can be
useful in some circumstances for a nicer shell experience.

The default implementation for such a merging system is the
[`CommandCollection`](../api/index#click.CommandCollection
"click.CommandCollection") class. It accepts a list of other multi commands
and makes the commands available on the same level.

Example usage:

    
    
    import click
    
    @click.group()
    def cli1():
        pass
    
    @cli1.command()
    def cmd1():
        """Command on cli1"""
    
    @click.group()
    def cli2():
        pass
    
    @cli2.command()
    def cmd2():
        """Command on cli2"""
    
    cli = click.CommandCollection(sources=[cli1, cli2])
    
    if __name__ == '__main__':
        cli()
    

And what it looks like:

    
    
    $ cli --help
    Usage: cli [OPTIONS] COMMAND [ARGS]...
    
    Options:
      --help  Show this message and exit.
    
    Commands:
      cmd1  Command on cli1
      cmd2  Command on cli2
    

In case a command exists in more than one source, the first source wins.

## Multi Command Chaining

Changelog

New in version 3.0.

Sometimes it is useful to be allowed to invoke more than one subcommand in one
go. For instance if you have installed a setuptools package before you might
be familiar with the `setup.py sdist bdist_wheel upload` command chain which
invokes `sdist` before `bdist_wheel` before `upload`. Starting with Click 3.0
this is very simple to implement. All you have to do is to pass `chain=True`
to your multicommand:

    
    
    @click.group(chain=True)
    def cli():
        pass
    
    
    @cli.command('sdist')
    def sdist():
        click.echo('sdist called')
    
    
    @cli.command('bdist_wheel')
    def bdist_wheel():
        click.echo('bdist_wheel called')
    

Now you can invoke it like this:

    
    
    $ setup.py sdist bdist_wheel
    sdist called
    bdist_wheel called
    

When using multi command chaining you can only have one command (the last) use
`nargs=-1` on an argument. It is also not possible to nest multi commands
below chained multicommands. Other than that there are no restrictions on how
they work. They can accept options and arguments as normal. The order between
options and arguments is limited for chained commands. Currently only
`--options argument` order is allowed.

Another note: the
[`Context.invoked_subcommand`](../api/index#click.Context.invoked_subcommand
"click.Context.invoked_subcommand") attribute is a bit useless for multi
commands as it will give `'*'` as value if more than one command is invoked.
This is necessary because the handling of subcommands happens one after
another so the exact subcommands that will be handled are not yet available
when the callback fires.

Note

It is currently not possible for chain commands to be nested. This will be
fixed in future versions of Click.

## Multi Command Pipelines

Changelog

New in version 3.0.

A very common usecase of multi command chaining is to have one command process
the result of the previous command. There are various ways in which this can
be facilitated. The most obvious way is to store a value on the context object
and process it from function to function. This works by decorating a function
with [`pass_context()`](../api/index#click.pass_context "click.pass_context")
after which the context object is provided and a subcommand can store its data
there.

Another way to accomplish this is to setup pipelines by returning processing
functions. Think of it like this: when a subcommand gets invoked it processes
all of its parameters and comes up with a plan of how to do its processing. At
that point it then returns a processing function and returns.

Where do the returned functions go? The chained multicommand can register a
callback with
[`MultiCommand.result_callback()`](../api/index#click.MultiCommand.result_callback
"click.MultiCommand.result_callback") that goes over all these functions and
then invoke them.

To make this a bit more concrete consider this example:

    
    
    @click.group(chain=True, invoke_without_command=True)
    @click.option('-i', '--input', type=click.File('r'))
    def cli(input):
        pass
    
    @cli.result_callback()
    def process_pipeline(processors, input):
        iterator = (x.rstrip('\r\n') for x in input)
        for processor in processors:
            iterator = processor(iterator)
        for item in iterator:
            click.echo(item)
    
    @cli.command('uppercase')
    def make_uppercase():
        def processor(iterator):
            for line in iterator:
                yield line.upper()
        return processor
    
    @cli.command('lowercase')
    def make_lowercase():
        def processor(iterator):
            for line in iterator:
                yield line.lower()
        return processor
    
    @cli.command('strip')
    def make_strip():
        def processor(iterator):
            for line in iterator:
                yield line.strip()
        return processor
    

That’s a lot in one go, so let’s go through it step by step.

  1. The first thing is to make a [`group()`](../api/index#click.group "click.group") that is chainable. In addition to that we also instruct Click to invoke even if no subcommand is defined. If this would not be done, then invoking an empty pipeline would produce the help page instead of running the result callbacks.
  2. The next thing we do is to register a result callback on our group. This callback will be invoked with an argument which is the list of all return values of all subcommands and then the same keyword parameters as our group itself. This means we can access the input file easily there without having to use the context object.
  3. In this result callback we create an iterator of all the lines in the input file and then pass this iterator through all the returned callbacks from all subcommands and finally we print all lines to stdout.

After that point we can register as many subcommands as we want and each
subcommand can return a processor function to modify the stream of lines.

One important thing of note is that Click shuts down the context after each
callback has been run. This means that for instance file types cannot be
accessed in the `processor` functions as the files will already be closed
there. This limitation is unlikely to change because it would make resource
handling much more complicated. For such it’s recommended to not use the file
type and manually open the file through
[`open_file()`](../api/index#click.open_file "click.open_file").

For a more complex example that also improves upon handling of the pipelines
have a look at the [imagepipe multi command chaining
demo](https://github.com/pallets/click/tree/main/examples/imagepipe) in the
Click repository. It implements a pipeline based image editing tool that has a
nice internal structure for the pipelines.

## Overriding Defaults

By default, the default value for a parameter is pulled from the `default`
flag that is provided when it’s defined, but that’s not the only place
defaults can be loaded from. The other place is the `Context.default_map` (a
dictionary) on the context. This allows defaults to be loaded from a
configuration file to override the regular defaults.

This is useful if you plug in some commands from another package but you’re
not satisfied with the defaults.

The default map can be nested arbitrarily for each subcommand:

    
    
    default_map = {
        "debug": True,  # default for a top level option
        "runserver": {"port": 5000}  # default for a subcommand
    }
    

The default map can be provided when the script is invoked, or overridden at
any point by commands. For instance, a top-level command could load the
defaults from a configuration file.

Example usage:

    
    
    import click
    
    @click.group()
    def cli():
        pass
    
    @cli.command()
    @click.option('--port', default=8000)
    def runserver(port):
        click.echo(f"Serving on http://127.0.0.1:{port}/")
    
    if __name__ == '__main__':
        cli(default_map={
            'runserver': {
                'port': 5000
            }
        })
    

And in action:

    
    
    $ cli runserver
    Serving on http://127.0.0.1:5000/
    

## Context Defaults

Changelog

New in version 2.0.

Starting with Click 2.0 you can override defaults for contexts not just when
calling your script, but also in the decorator that declares a command. For
instance given the previous example which defines a custom `default_map` this
can also be accomplished in the decorator now.

This example does the same as the previous example:

    
    
    import click
    
    CONTEXT_SETTINGS = dict(
        default_map={'runserver': {'port': 5000}}
    )
    
    @click.group(context_settings=CONTEXT_SETTINGS)
    def cli():
        pass
    
    @cli.command()
    @click.option('--port', default=8000)
    def runserver(port):
        click.echo(f"Serving on http://127.0.0.1:{port}/")
    
    if __name__ == '__main__':
        cli()
    

And again the example in action:

    
    
    $ cli runserver
    Serving on http://127.0.0.1:5000/
    

## Command Return Values

Changelog

New in version 3.0.

One of the new introductions in Click 3.0 is the full support for return
values from command callbacks. This enables a whole range of features that
were previously hard to implement.

In essence any command callback can now return a value. This return value is
bubbled to certain receivers. One usecase for this has already been show in
the example of Multi Command Chaining where it has been demonstrated that
chained multi commands can have callbacks that process all return values.

When working with command return values in Click, this is what you need to
know:

  * The return value of a command callback is generally returned from the [`BaseCommand.invoke()`](../api/index#click.BaseCommand.invoke "click.BaseCommand.invoke") method. The exception to this rule has to do with [`Group`](../api/index#click.Group "click.Group")s:

    * In a group the return value is generally the return value of the subcommand invoked. The only exception to this rule is that the return value is the return value of the group callback if it’s invoked without arguments and `invoke_without_command` is enabled.
    * If a group is set up for chaining then the return value is a list of all subcommands’ results.
    * Return values of groups can be processed through a [`MultiCommand.result_callback`](../api/index#click.MultiCommand.result_callback "click.MultiCommand.result_callback"). This is invoked with the list of all return values in chain mode, or the single return value in case of non chained commands.
  * The return value is bubbled through from the [`Context.invoke()`](../api/index#click.Context.invoke "click.Context.invoke") and [`Context.forward()`](../api/index#click.Context.forward "click.Context.forward") methods. This is useful in situations where you internally want to call into another command.
  * Click does not have any hard requirements for the return values and does not use them itself. This allows return values to be used for custom decorators or workflows (like in the multi command chaining example).
  * When a Click script is invoked as command line application (through [`BaseCommand.main()`](../api/index#click.BaseCommand.main "click.BaseCommand.main")) the return value is ignored unless the `standalone_mode` is disabled in which case it’s bubbled through.

# Complex Applications

Click is designed to assist with the creation of complex and simple CLI tools
alike. However, the power of its design is the ability to arbitrarily nest
systems together. For instance, if you have ever used Django, you will have
realized that it provides a command line utility, but so does Celery. When
using Celery with Django, there are two tools that need to interact with each
other and be cross-configured.

In a theoretical world of two separate Click command line utilities, they
could solve this problem by nesting one inside the other. For instance, the
web framework could also load the commands for the message queue framework.

## Basic Concepts

To understand how this works, you need to understand two concepts: contexts
and the calling convention.

### Contexts

Whenever a Click command is executed, a [`Context`](../api/index#click.Context
"click.Context") object is created which holds state for this particular
invocation. It remembers parsed parameters, what command created it, which
resources need to be cleaned up at the end of the function, and so forth. It
can also optionally hold an application-defined object.

Context objects build a linked list until they hit the top one. Each context
is linked to a parent context. This allows a command to work below another
command and store its own information there without having to be afraid of
altering up the state of the parent command.

Because the parent data is available, however, it is possible to navigate to
it if needed.

Most of the time, you do not see the context object, but when writing more
complex applications it comes in handy. This brings us to the next point.

### Calling Convention

When a Click command callback is executed, it’s passed all the non-hidden
parameters as keyword arguments. Notably absent is the context. However, a
callback can opt into being passed to the context object by marking itself
with [`pass_context()`](../api/index#click.pass_context "click.pass_context").

So how do you invoke a command callback if you don’t know if it should receive
the context or not? The answer is that the context itself provides a helper
function ([`Context.invoke()`](../api/index#click.Context.invoke
"click.Context.invoke")) which can do this for you. It accepts the callback as
first argument and then invokes the function correctly.

## Building a Git Clone

In this example, we want to build a command line tool that resembles a version
control system. Systems like Git usually provide one over-arching command that
already accepts some parameters and configuration, and then have extra
subcommands that do other things.

### The Root Command

At the top level, we need a group that can hold all our commands. In this
case, we use the basic [`click.group()`](../api/index#click.group
"click.group") which allows us to register other Click commands below it.

For this command, we also want to accept some parameters that configure the
state of our tool:

    
    
    import os
    import click
    
    
    class Repo(object):
        def __init__(self, home=None, debug=False):
            self.home = os.path.abspath(home or '.')
            self.debug = debug
    
    
    @click.group()
    @click.option('--repo-home', envvar='REPO_HOME', default='.repo')
    @click.option('--debug/--no-debug', default=False,
                  envvar='REPO_DEBUG')
    @click.pass_context
    def cli(ctx, repo_home, debug):
        ctx.obj = Repo(repo_home, debug)
    

Let’s understand what this does. We create a group command which can have
subcommands. When it is invoked, it will create an instance of a `Repo` class.
This holds the state for our command line tool. In this case, it just
remembers some parameters, but at this point it could also start loading
configuration files and so on.

This state object is then remembered by the context as
[`obj`](../api/index#click.Context.obj "click.Context.obj"). This is a special
attribute where commands are supposed to remember what they need to pass on to
their children.

In order for this to work, we need to mark our function with
[`pass_context()`](../api/index#click.pass_context "click.pass_context"),
because otherwise, the context object would be entirely hidden from us.

### The First Child Command

Let’s add our first child command to it, the clone command:

    
    
    @cli.command()
    @click.argument('src')
    @click.argument('dest', required=False)
    def clone(src, dest):
        pass
    

So now we have a clone command, but how do we get access to the repo? As you
can imagine, one way is to use the
[`pass_context()`](../api/index#click.pass_context "click.pass_context")
function which again will make our callback also get the context passed on
which we memorized the repo. However, there is a second version of this
decorator called [`pass_obj()`](../api/index#click.pass_obj "click.pass_obj")
which will just pass the stored object, (in our case the repo):

    
    
    @cli.command()
    @click.argument('src')
    @click.argument('dest', required=False)
    @click.pass_obj
    def clone(repo, src, dest):
        pass
    

### Interleaved Commands

While not relevant for the particular program we want to build, there is also
quite good support for interleaving systems. Imagine for instance that there
was a super cool plugin for our version control system that needed a lot of
configuration and wanted to store its own configuration as
[`obj`](../api/index#click.Context.obj "click.Context.obj"). If we would then
attach another command below that, we would all of a sudden get the plugin
configuration instead of our repo object.

One obvious way to remedy this is to store a reference to the repo in the
plugin, but then a command needs to be aware that it’s attached below such a
plugin.

There is a much better system that can be built by taking advantage of the
linked nature of contexts. We know that the plugin context is linked to the
context that created our repo. Because of that, we can start a search for the
last level where the object stored by the context was a repo.

Built-in support for this is provided by the
[`make_pass_decorator()`](../api/index#click.make_pass_decorator
"click.make_pass_decorator") factory, which will create decorators for us that
find objects (it internally calls into
[`Context.find_object()`](../api/index#click.Context.find_object
"click.Context.find_object")). In our case, we know that we want to find the
closest `Repo` object, so let’s make a decorator for this:

    
    
    pass_repo = click.make_pass_decorator(Repo)
    

If we now use `pass_repo` instead of `pass_obj`, we will always get a repo
instead of something else:

    
    
    @cli.command()
    @click.argument('src')
    @click.argument('dest', required=False)
    @pass_repo
    def clone(repo, src, dest):
        pass
    

### Ensuring Object Creation

The above example only works if there was an outer command that created a
`Repo` object and stored it in the context. For some more advanced use cases,
this might become a problem. The default behavior of
[`make_pass_decorator()`](../api/index#click.make_pass_decorator
"click.make_pass_decorator") is to call
[`Context.find_object()`](../api/index#click.Context.find_object
"click.Context.find_object") which will find the object. If it can’t find the
object, [`make_pass_decorator()`](../api/index#click.make_pass_decorator
"click.make_pass_decorator") will raise an error. The alternative behavior is
to use [`Context.ensure_object()`](../api/index#click.Context.ensure_object
"click.Context.ensure_object") which will find the object, and if it cannot
find it, will create one and store it in the innermost context. This behavior
can also be enabled for
[`make_pass_decorator()`](../api/index#click.make_pass_decorator
"click.make_pass_decorator") by passing `ensure=True`:

    
    
    pass_repo = click.make_pass_decorator(Repo, ensure=True)
    

In this case, the innermost context gets an object created if it is missing.
This might replace objects being placed there earlier. In this case, the
command stays executable, even if the outer command does not run. For this to
work, the object type needs to have a constructor that accepts no arguments.

As such it runs standalone:

    
    
    @click.command()
    @pass_repo
    def cp(repo):
        click.echo(isinstance(repo, Repo))
    

As you can see:

    
    
    $ cp
    True
    

## Lazily Loading Subcommands

Large CLIs and CLIs with slow imports may benefit from deferring the loading
of subcommands. The interfaces which support this mode of use are
[`MultiCommand.list_commands()`](../api/index#click.MultiCommand.list_commands
"click.MultiCommand.list_commands") and
[`MultiCommand.get_command()`](../api/index#click.MultiCommand.get_command
"click.MultiCommand.get_command"). A custom
[`MultiCommand`](../api/index#click.MultiCommand "click.MultiCommand")
subclass can implement a lazy loader by storing extra data such that
[`MultiCommand.get_command()`](../api/index#click.MultiCommand.get_command
"click.MultiCommand.get_command") is responsible for running imports.

Since the primary case for this is a [`Group`](../api/index#click.Group
"click.Group") which loads its subcommands lazily, the following example shows
a lazy-group implementation.

Warning

Lazy loading of python code can result in hard to track down bugs, circular
imports in order-dependent codebases, and other surprising behaviors. It is
recommended that this technique only be used in concert with testing which
will at least run the `--help` on each subcommand. That will guarantee that
each subcommand can be loaded successfully.

### Defining the Lazy Group

The following [`Group`](../api/index#click.Group "click.Group") subclass adds
an attribute, `lazy_subcommands`, which stores a mapping from subcommand names
to the information for importing them.

    
    
    # in lazy_group.py
    import importlib
    import click
    
    class LazyGroup(click.Group):
        def __init__(self, *args, lazy_subcommands=None, **kwargs):
            super().__init__(*args, **kwargs)
            # lazy_subcommands is a map of the form:
            #
            #   {command-name} -> {module-name}.{command-object-name}
            #
            self.lazy_subcommands = lazy_subcommands or {}
    
        def list_commands(self, ctx):
            base = super().list_commands(ctx)
            lazy = sorted(self.lazy_subcommands.keys())
            return base + lazy
    
        def get_command(self, ctx, cmd_name):
            if cmd_name in self.lazy_subcommands:
                return self._lazy_load(cmd_name)
            return super().get_command(ctx, cmd_name)
    
        def _lazy_load(self, cmd_name):
            # lazily loading a command, first get the module name and attribute name
            import_path = self.lazy_subcommands[cmd_name]
            modname, cmd_object_name = import_path.rsplit(".", 1)
            # do the import
            mod = importlib.import_module(modname)
            # get the Command object from that module
            cmd_object = getattr(mod, cmd_object_name)
            # check the result to make debugging easier
            if not isinstance(cmd_object, click.BaseCommand):
                raise ValueError(
                    f"Lazy loading of {import_path} failed by returning "
                    "a non-command object"
                )
            return cmd_object
    

### Using LazyGroup To Define a CLI

With `LazyGroup` defined, it’s now possible to write a group which lazily
loads its subcommands like so:

    
    
    # in main.py
    import click
    from lazy_group import LazyGroup
    
    @click.group(
        cls=LazyGroup,
        lazy_subcommands={"foo": "foo.cli", "bar": "bar.cli"},
        help="main CLI command for lazy example",
    )
    def cli():
        pass
    
    # in foo.py
    import click
    
    @click.group(help="foo command for lazy example")
    def cli():
        pass
    
    # in bar.py
    import click
    from lazy_group import LazyGroup
    
    @click.group(
        cls=LazyGroup,
        lazy_subcommands={"baz": "baz.cli"},
        help="bar command for lazy example",
    )
    def cli():
        pass
    
    # in baz.py
    import click
    
    @click.group(help="baz command for lazy example")
    def cli():
        pass
    

### What triggers Lazy Loading?

There are several events which may trigger lazy loading by running the
[`MultiCommand.get_command()`](../api/index#click.MultiCommand.get_command
"click.MultiCommand.get_command") function. Some are intuititve, and some are
less so.

All cases are described with respect to the above example, assuming the main
program name is `cli`.

  1. Command resolution. If a user runs `cli bar baz`, this must first resolve `bar`, and then resolve `baz`. Each subcommand resolution step does a lazy load.
  2. Helptext rendering. In order to get the short help description of subcommands, `cli --help` will load `foo` and `bar`. Note that it will still not load `baz`.
  3. Shell completion. In order to get the subcommands of a lazy command, `cli <TAB>` will need to resolve the subcommands of `cli`. This process will trigger the lazy loads.

### Further Deferring Imports

It is possible to make the process even lazier, but it is generally more
difficult the more you want to defer work.

For example, subcommands could be represented as a custom
[`BaseCommand`](../api/index#click.BaseCommand "click.BaseCommand") subclass
which defers importing the command until it is invoked, but which provides
`BaseCommand.get_short_help_str()` in order to support completions and
helptext. More simply, commands can be constructed whose callback functions
defer any actual work until after an import.

This command definition provides `foo`, but any of the work associated with
importing the “real” callback function is deferred until invocation time:

    
    
    @click.command()
    @click.option("-n", type=int)
    @click.option("-w", type=str)
    def foo(n, w):
        from mylibrary import foo_concrete
    
        foo_concrete(n, w)
    

Because `click` builds helptext and usage info from options, arguments, and
command attributes, it has no awareness that the underlying function is in any
way handling a deferred import. Therefore, all `click`-provided utilities and
functionality will work as normal on such a command.

# click-contrib

As the number of users of Click grows, more and more major feature requests
are made. To users it may seem reasonable to include those features with
Click; however, many of them are experimental or aren’t practical to support
generically. Maintainers have to choose what is reasonable to maintain in
Click core.

The [click-contrib](https://github.com/click-contrib/) GitHub organization
exists as a place to collect third-party packages that extend Click’s
features. It is also meant to ease the effort of searching for such
extensions.

Please note that the quality and stability of those packages may be different
than Click itself. While published under a common organization, they are still
separate from Click and the Pallets maintainers.

# Documenting Scripts

Click makes it very easy to document your command line tools. First of all, it
automatically generates help pages for you. While these are currently not
customizable in terms of their layout, all of the text can be changed.

## Help Texts

Commands and options accept help arguments. In the case of commands, the
docstring of the function is automatically used if provided.

Simple example:

    
    
    @click.command()
    @click.option('--count', default=1, help='number of greetings')
    @click.argument('name')
    def hello(count, name):
        """This script prints hello NAME COUNT times."""
        for x in range(count):
            click.echo(f"Hello {name}!")
    

And what it looks like:

    
    
    $ hello --help
    Usage: hello [OPTIONS] NAME
    
      This script prints hello NAME COUNT times.
    
    Options:
      --count INTEGER  number of greetings
      --help           Show this message and exit.
    

### Documenting Arguments

[`click.argument()`](../api/index#click.argument "click.argument") does not
take a `help` parameter. This is to follow the general convention of Unix
tools of using arguments for only the most necessary things, and to document
them in the command help text by referring to them by name.

You might prefer to reference the argument in the description:

    
    
    @click.command()
    @click.argument('filename')
    def touch(filename):
        """Print FILENAME."""
        click.echo(filename)
    

And what it looks like:

    
    
    $ touch --help
    Usage: touch [OPTIONS] FILENAME
    
      Print FILENAME.
    
    Options:
      --help  Show this message and exit.
    

Or you might prefer to explicitly provide a description of the argument:

    
    
    @click.command()
    @click.argument('filename')
    def touch(filename):
        """Print FILENAME.
    
        FILENAME is the name of the file to check.
        """
        click.echo(filename)
    

And what it looks like:

    
    
    $ touch --help
    Usage: touch [OPTIONS] FILENAME
    
      Print FILENAME.
    
      FILENAME is the name of the file to check.
    
    Options:
      --help  Show this message and exit.
    

For more examples, see the examples in [Arguments](../arguments/index).

## Preventing Rewrapping

The default behavior of Click is to rewrap text based on the width of the
terminal, to a maximum 80 characters. In some circumstances, this can become a
problem. The main issue is when showing code examples, where newlines are
significant.

Rewrapping can be disabled on a per-paragraph basis by adding a line with
solely the `\b` escape marker in it. This line will be removed from the help
text and rewrapping will be disabled.

Example:

    
    
    @click.command()
    def cli():
        """First paragraph.
    
        This is a very long second paragraph and as you
        can see wrapped very early in the source text
        but will be rewrapped to the terminal width in
        the final output.
    
        \b
        This is
        a paragraph
        without rewrapping.
    
        And this is a paragraph
        that will be rewrapped again.
        """
    

And what it looks like:

    
    
    $ cli --help
    Usage: cli [OPTIONS]
    
      First paragraph.
    
      This is a very long second paragraph and as you can see wrapped very early in
      the source text but will be rewrapped to the terminal width in the final
      output.
    
      This is
      a paragraph
      without rewrapping.
    
      And this is a paragraph that will be rewrapped again.
    
    Options:
      --help  Show this message and exit.
    

To change the maximum width, pass `max_content_width` when calling the
command.

    
    
    cli(max_content_width=120)
    

## Truncating Help Texts

Click gets command help text from function docstrings. However if you already
use docstrings to document function arguments you may not want to see :param:
and :return: lines in your help text.

You can use the `\f` escape marker to have Click truncate the help text after
the marker.

Example:

    
    
    @click.command()
    @click.pass_context
    def cli(ctx):
        """First paragraph.
    
        This is a very long second
        paragraph and not correctly
        wrapped but it will be rewrapped.
        \f
    
        :param click.core.Context ctx: Click context.
        """
    

And what it looks like:

    
    
    $ cli --help
    Usage: cli [OPTIONS]
    
      First paragraph.
    
      This is a very long second paragraph and not correctly wrapped but it will be
      rewrapped.
    
    Options:
      --help  Show this message and exit.
    

## Meta Variables

Options and parameters accept a `metavar` argument that can change the meta
variable in the help page. The default version is the parameter name in
uppercase with underscores, but can be annotated differently if desired. This
can be customized at all levels:

    
    
    @click.command(options_metavar='<options>')
    @click.option('--count', default=1, help='number of greetings',
                  metavar='<int>')
    @click.argument('name', metavar='<name>')
    def hello(count, name):
        """This script prints hello <name> <int> times."""
        for x in range(count):
            click.echo(f"Hello {name}!")
    

Example:

    
    
    $ hello --help
    Usage: hello <options> <name>
    
      This script prints hello <name> <int> times.
    
    Options:
      --count <int>  number of greetings
      --help         Show this message and exit.
    

## Command Short Help

For commands, a short help snippet is generated. By default, it’s the first
sentence of the help message of the command, unless it’s too long. This can
also be overridden:

    
    
    @click.group()
    def cli():
        """A simple command line tool."""
    
    @cli.command('init', short_help='init the repo')
    def init():
        """Initializes the repository."""
    
    @cli.command('delete', short_help='delete the repo')
    def delete():
        """Deletes the repository."""
    

And what it looks like:

    
    
    $ repo.py
    Usage: repo.py [OPTIONS] COMMAND [ARGS]...
    
      A simple command line tool.
    
    Options:
      --help  Show this message and exit.
    
    Commands:
      delete  delete the repo
      init    init the repo
    

## Command Epilog Help

The help epilog is like the help string but it’s printed at the end of the
help page after everything else. Useful for showing example command usages or
referencing additional help resources.

    
    
    @click.command(epilog='Check out our docs at https://click.palletsprojects.com/ for more details')
    def init():
        """Initializes the repository."""
    

And what it looks like:

    
    
    $ repo.py --help
    Usage: repo.py [OPTIONS]
    
      Initializes the repository.
    
    Options:
      --help  Show this message and exit.
    
      Check out our docs at https://click.palletsprojects.com/ for more details
    

## Help Parameter Customization

Changelog

New in version 2.0.

The help parameter is implemented in Click in a very special manner. Unlike
regular parameters it’s automatically added by Click for any command and it
performs automatic conflict resolution. By default it’s called `--help`, but
this can be changed. If a command itself implements a parameter with the same
name, the default help parameter stops accepting it. There is a context
setting that can be used to override the names of the help parameters called
[`help_option_names`](../api/index#click.Context.help_option_names
"click.Context.help_option_names").

This example changes the default parameters to `-h` and `--help` instead of
just `--help`:

    
    
    CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
    
    @click.command(context_settings=CONTEXT_SETTINGS)
    def cli():
        pass
    

And what it looks like:

    
    
    $ cli -h
    Usage: cli [OPTIONS]
    
    Options:
      -h, --help  Show this message and exit.
    

# Exception Handling

Click internally uses exceptions to signal various error conditions that the
user of the application might have caused. Primarily this is things like
incorrect usage.

## Where are Errors Handled?

Click’s main error handling is happening in
[`BaseCommand.main()`](../api/index#click.BaseCommand.main
"click.BaseCommand.main"). In there it handles all subclasses of
[`ClickException`](../api/index#click.ClickException "click.ClickException")
as well as the standard
[`EOFError`](https://docs.python.org/3/library/exceptions.html#EOFError "\(in
Python v3.12\)") and
[`KeyboardInterrupt`](https://docs.python.org/3/library/exceptions.html#KeyboardInterrupt
"\(in Python v3.12\)") exceptions. The latter are internally translated into
an [`Abort`](../api/index#click.Abort "click.Abort").

The logic applied is the following:

  1. If an [`EOFError`](https://docs.python.org/3/library/exceptions.html#EOFError "\(in Python v3.12\)") or [`KeyboardInterrupt`](https://docs.python.org/3/library/exceptions.html#KeyboardInterrupt "\(in Python v3.12\)") happens, reraise it as [`Abort`](../api/index#click.Abort "click.Abort").
  2. If a [`ClickException`](../api/index#click.ClickException "click.ClickException") is raised, invoke the `ClickException.show()` method on it to display it and then exit the program with `ClickException.exit_code`.
  3. If an [`Abort`](../api/index#click.Abort "click.Abort") exception is raised print the string `Aborted!` to standard error and exit the program with exit code `1`.
  4. If it goes through well, exit the program with exit code `0`.

## What if I don’t want that?

Generally you always have the option to invoke the `invoke()` method yourself.
For instance if you have a [`Command`](../api/index#click.Command
"click.Command") you can invoke it manually like this:

    
    
    ctx = command.make_context('command-name', ['args', 'go', 'here'])
    with ctx:
        result = command.invoke(ctx)
    

In this case exceptions will not be handled at all and bubbled up as you would
expect.

Starting with Click 3.0 you can also use the `Command.main()` method but
disable the standalone mode which will do two things: disable exception
handling and disable the implicit `sys.exit()` at the end.

So you can do something like this:

    
    
    command.main(['command-name', 'args', 'go', 'here'],
                 standalone_mode=False)
    

## Which Exceptions Exist?

Click has two exception bases:
[`ClickException`](../api/index#click.ClickException "click.ClickException")
which is raised for all exceptions that Click wants to signal to the user and
[`Abort`](../api/index#click.Abort "click.Abort") which is used to instruct
Click to abort the execution.

A [`ClickException`](../api/index#click.ClickException "click.ClickException")
has a `show()` method which can render an error message to stderr or the given
file object. If you want to use the exception yourself for doing something
check the API docs about what else they provide.

The following common subclasses exist:

  * [`UsageError`](../api/index#click.UsageError "click.UsageError") to inform the user that something went wrong.
  * [`BadParameter`](../api/index#click.BadParameter "click.BadParameter") to inform the user that something went wrong with a specific parameter. These are often handled internally in Click and augmented with extra information if possible. For instance if those are raised from a callback Click will automatically augment it with the parameter name if possible.
  * [`FileError`](../api/index#click.FileError "click.FileError") this is an error that is raised by the `FileType` if Click encounters issues opening the file.

# Welcome to Click

[](https://palletsprojects.com/p/click/)

Click is a Python package for creating beautiful command line interfaces in a
composable way with as little code as necessary. It’s the “Command Line
Interface Creation Kit”. It’s highly configurable but comes with sensible
defaults out of the box.

It aims to make the process of writing command line tools quick and fun while
also preventing any frustration caused by the inability to implement an
intended CLI API.

Click in three points:

  * arbitrary nesting of commands
  * automatic help page generation
  * supports lazy loading of subcommands at runtime

What does it look like? Here is an example of a simple Click program:

    
    
    import click
    
    @click.command()
    @click.option('--count', default=1, help='Number of greetings.')
    @click.option('--name', prompt='Your name',
                  help='The person to greet.')
    def hello(count, name):
        """Simple program that greets NAME for a total of COUNT times."""
        for x in range(count):
            click.echo(f"Hello {name}!")
    
    if __name__ == '__main__':
        hello()
    

And what it looks like when run:

    
    
    $ python hello.py --count=3
    Your name: John
    Hello John!
    Hello John!
    Hello John!
    

It automatically generates nicely formatted help pages:

    
    
    $ python hello.py --help
    Usage: hello.py [OPTIONS]
    
      Simple program that greets NAME for a total of COUNT times.
    
    Options:
      --count INTEGER  Number of greetings.
      --name TEXT      The person to greet.
      --help           Show this message and exit.
    

You can get the library directly from PyPI:

    
    
    pip install click
    

## Documentation

This part of the documentation guides you through all of the library’s usage
patterns.

  * [Why Click?](why/index)
    * [Why not Argparse?](why/index#why-not-argparse)
    * [Why not Docopt etc.?](why/index#why-not-docopt-etc)
    * [Why Hardcoded Behaviors?](why/index#why-hardcoded-behaviors)
    * [Why No Auto Correction?](why/index#why-no-auto-correction)
  * [Quickstart](quickstart/index)
    * [virtualenv](quickstart/index#virtualenv)
    * [Screencast and Examples](quickstart/index#screencast-and-examples)
    * [Basic Concepts - Creating a Command](quickstart/index#basic-concepts-creating-a-command)
    * [Echoing](quickstart/index#echoing)
    * [Nesting Commands](quickstart/index#nesting-commands)
    * [Registering Commands Later](quickstart/index#registering-commands-later)
    * [Adding Parameters](quickstart/index#adding-parameters)
    * [Switching to Setuptools](quickstart/index#switching-to-setuptools)
  * [Setuptools Integration](setuptools/index)
    * [Introduction](setuptools/index#introduction)
    * [Testing The Script](setuptools/index#testing-the-script)
    * [Scripts in Packages](setuptools/index#scripts-in-packages)
  * [Parameters](parameters/index)
    * [Differences](parameters/index#differences)
    * [Parameter Types](parameters/index#parameter-types)
    * [Parameter Names](parameters/index#parameter-names)
    * [Implementing Custom Types](parameters/index#implementing-custom-types)
  * [Options](options/index)
    * [Name Your Options](options/index#name-your-options)
    * [Basic Value Options](options/index#basic-value-options)
    * [Multi Value Options](options/index#multi-value-options)
    * [Tuples as Multi Value Options](options/index#tuples-as-multi-value-options)
    * [Multiple Options](options/index#multiple-options)
    * [Counting](options/index#counting)
    * [Boolean Flags](options/index#boolean-flags)
    * [Feature Switches](options/index#feature-switches)
    * [Choice Options](options/index#choice-options)
    * [Prompting](options/index#prompting)
    * [Password Prompts](options/index#password-prompts)
    * [Dynamic Defaults for Prompts](options/index#dynamic-defaults-for-prompts)
    * [Callbacks and Eager Options](options/index#callbacks-and-eager-options)
    * [Yes Parameters](options/index#yes-parameters)
    * [Values from Environment Variables](options/index#values-from-environment-variables)
    * [Multiple Values from Environment Values](options/index#multiple-values-from-environment-values)
    * [Other Prefix Characters](options/index#other-prefix-characters)
    * [Range Options](options/index#range-options)
    * [Callbacks for Validation](options/index#callbacks-for-validation)
    * [Optional Value](options/index#optional-value)
  * [Arguments](arguments/index)
    * [Basic Arguments](arguments/index#basic-arguments)
    * [Variadic Arguments](arguments/index#variadic-arguments)
    * [File Arguments](arguments/index#file-arguments)
    * [File Path Arguments](arguments/index#file-path-arguments)
    * [File Opening Safety](arguments/index#file-opening-safety)
    * [Environment Variables](arguments/index#environment-variables)
    * [Option-Like Arguments](arguments/index#option-like-arguments)
  * [Commands and Groups](commands/index)
    * [Callback Invocation](commands/index#callback-invocation)
    * [Passing Parameters](commands/index#passing-parameters)
    * [Nested Handling and Contexts](commands/index#nested-handling-and-contexts)
    * [Decorating Commands](commands/index#decorating-commands)
    * [Group Invocation Without Command](commands/index#group-invocation-without-command)
    * [Custom Multi Commands](commands/index#custom-multi-commands)
    * [Merging Multi Commands](commands/index#merging-multi-commands)
    * [Multi Command Chaining](commands/index#multi-command-chaining)
    * [Multi Command Pipelines](commands/index#multi-command-pipelines)
    * [Overriding Defaults](commands/index#overriding-defaults)
    * [Context Defaults](commands/index#context-defaults)
    * [Command Return Values](commands/index#command-return-values)
  * [User Input Prompts](prompts/index)
    * [Option Prompts](prompts/index#option-prompts)
    * [Input Prompts](prompts/index#input-prompts)
    * [Confirmation Prompts](prompts/index#confirmation-prompts)
  * [Documenting Scripts](documentation/index)
    * [Help Texts](documentation/index#help-texts)
    * [Preventing Rewrapping](documentation/index#preventing-rewrapping)
    * [Truncating Help Texts](documentation/index#truncating-help-texts)
    * [Meta Variables](documentation/index#meta-variables)
    * [Command Short Help](documentation/index#command-short-help)
    * [Command Epilog Help](documentation/index#command-epilog-help)
    * [Help Parameter Customization](documentation/index#help-parameter-customization)
  * [Complex Applications](complex/index)
    * [Basic Concepts](complex/index#basic-concepts)
    * [Building a Git Clone](complex/index#building-a-git-clone)
    * [Lazily Loading Subcommands](complex/index#lazily-loading-subcommands)
  * [Advanced Patterns](advanced/index)
    * [Command Aliases](advanced/index#command-aliases)
    * [Parameter Modifications](advanced/index#parameter-modifications)
    * [Token Normalization](advanced/index#token-normalization)
    * [Invoking Other Commands](advanced/index#invoking-other-commands)
    * [Callback Evaluation Order](advanced/index#callback-evaluation-order)
    * [Forwarding Unknown Options](advanced/index#forwarding-unknown-options)
    * [Global Context Access](advanced/index#global-context-access)
    * [Detecting the Source of a Parameter](advanced/index#detecting-the-source-of-a-parameter)
    * [Managing Resources](advanced/index#managing-resources)
  * [Testing Click Applications](testing/index)
    * [Basic Testing](testing/index#basic-testing)
    * [File System Isolation](testing/index#file-system-isolation)
    * [Input Streams](testing/index#input-streams)
  * [Utilities](utils/index)
    * [Printing to Stdout](utils/index#printing-to-stdout)
    * [ANSI Colors](utils/index#ansi-colors)
    * [Pager Support](utils/index#pager-support)
    * [Screen Clearing](utils/index#screen-clearing)
    * [Getting Characters from Terminal](utils/index#getting-characters-from-terminal)
    * [Waiting for Key Press](utils/index#waiting-for-key-press)
    * [Launching Editors](utils/index#launching-editors)
    * [Launching Applications](utils/index#launching-applications)
    * [Printing Filenames](utils/index#printing-filenames)
    * [Standard Streams](utils/index#standard-streams)
    * [Intelligent File Opening](utils/index#intelligent-file-opening)
    * [Finding Application Folders](utils/index#finding-application-folders)
    * [Showing Progress Bars](utils/index#showing-progress-bars)
  * [Shell Completion](shell-completion/index)
    * [Enabling Completion](shell-completion/index#enabling-completion)
    * [Custom Type Completion](shell-completion/index#custom-type-completion)
    * [Overriding Value Completion](shell-completion/index#overriding-value-completion)
    * [Adding Support for a Shell](shell-completion/index#adding-support-for-a-shell)
  * [Exception Handling](exceptions/index)
    * [Where are Errors Handled?](exceptions/index#where-are-errors-handled)
    * [What if I don’t want that?](exceptions/index#what-if-i-don-t-want-that)
    * [Which Exceptions Exist?](exceptions/index#which-exceptions-exist)
  * [Unicode Support](unicode-support/index)
    * [Surrogate Handling](unicode-support/index#surrogate-handling)
  * [Windows Console Notes](wincmd/index)
    * [Unicode Arguments](wincmd/index#unicode-arguments)
    * [Unicode Output and Input](wincmd/index#unicode-output-and-input)

## API Reference

If you are looking for information on a specific function, class, or method,
this part of the documentation is for you.

  * [API](api/index)
    * [Decorators](api/index#decorators)
    * [Utilities](api/index#utilities)
    * [Commands](api/index#commands)
    * [Parameters](api/index#parameters)
    * [Context](api/index#context)
    * [Types](api/index#types)
    * [Exceptions](api/index#exceptions)
    * [Formatting](api/index#formatting)
    * [Parsing](api/index#parsing)
    * [Shell Completion](api/index#shell-completion)
    * [Testing](api/index#testing)

## Miscellaneous Pages

  * [click-contrib](contrib/index)
  * [Upgrading To Newer Releases](upgrading/index)
    * [Upgrading to 7.0](upgrading/index#upgrading-to-7-0)
    * [Upgrading to 3.2](upgrading/index#upgrading-to-3-2)
    * [Upgrading to 2.0](upgrading/index#upgrading-to-2-0)
  * [BSD-3-Clause License](license/index)
  * [Changes](https://click.palletsprojects.com/en/8.1.x/changes/)
    * [Version 8.1.8](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-8)
    * [Version 8.1.7](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-7)
    * [Version 8.1.6](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-6)
    * [Version 8.1.5](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-5)
    * [Version 8.1.4](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-4)
    * [Version 8.1.3](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-3)
    * [Version 8.1.2](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-2)
    * [Version 8.1.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-1)
    * [Version 8.1.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-0)
    * [Version 8.0.4](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-0-4)
    * [Version 8.0.3](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-0-3)
    * [Version 8.0.2](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-0-2)
    * [Version 8.0.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-0-1)
    * [Version 8.0.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-8-0-0)
    * [Version 7.1.2](https://click.palletsprojects.com/en/8.1.x/changes/#version-7-1-2)
    * [Version 7.1.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-7-1-1)
    * [Version 7.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-7-1)
    * [Version 7.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-7-0)
    * [Version 6.7](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-7)
    * [Version 6.6](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-6)
    * [Version 6.4](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-4)
    * [Version 6.3](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-3)
    * [Version 6.2](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-2)
    * [Version 6.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-1)
    * [Version 6.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-6-0)
    * [Version 5.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-5-1)
    * [Version 5.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-5-0)
    * [Version 4.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-4-1)
    * [Version 4.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-4-0)
    * [Version 3.3](https://click.palletsprojects.com/en/8.1.x/changes/#version-3-3)
    * [Version 3.2](https://click.palletsprojects.com/en/8.1.x/changes/#version-3-2)
    * [Version 3.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-3-1)
    * [Version 3.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-3-0)
    * [Version 2.6](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-6)
    * [Version 2.5](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-5)
    * [Version 2.4](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-4)
    * [Version 2.3](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-3)
    * [Version 2.2](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-2)
    * [Version 2.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-1)
    * [Version 2.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-2-0)
    * [Version 1.1](https://click.palletsprojects.com/en/8.1.x/changes/#version-1-1)
    * [Version 1.0](https://click.palletsprojects.com/en/8.1.x/changes/#version-1-0)

# BSD-3-Clause License

    
    
    Copyright 2014 Pallets
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are
    met:
    
    1.  Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
    
    2.  Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
    
    3.  Neither the name of the copyright holder nor the names of its
        contributors may be used to endorse or promote products derived from
        this software without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    

# Options

Adding options to commands can be accomplished by the
[`option()`](../api/index#click.option "click.option") decorator. Since
options can come in various different versions, there are a ton of parameters
to configure their behavior. Options in click are distinct from [positional
arguments](../arguments/index#arguments).

## Name Your Options

Options have a name that will be used as the Python argument name when calling
the decorated function. This can be inferred from the option names or given
explicitly. Names are given as position arguments to the decorator.

A name is chosen in the following order

  1. If a name is not prefixed, it is used as the Python argument name and not treated as an option name on the command line.
  2. If there is at least one name prefixed with two dashes, the first one given is used as the name.
  3. The first name prefixed with one dash is used otherwise.

To get the Python argument name, the chosen name is converted to lower case,
up to two dashes are removed as the prefix, and other dashes are converted to
underscores.

    
    
    @click.command()
    @click.option('-s', '--string-to-echo')
    def echo(string_to_echo):
        click.echo(string_to_echo)
    
    
    
    @click.command()
    @click.option('-s', '--string-to-echo', 'string')
    def echo(string):
        click.echo(string)
    

  * `"-f", "--foo-bar"`, the name is `foo_bar`
  * `"-x"`, the name is `x`
  * `"-f", "--filename", "dest"`, the name is `dest`
  * `"--CamelCase"`, the name is `camelcase`
  * `"-f", "-fb"`, the name is `f`
  * `"--f", "--foo-bar"`, the name is `f`
  * `"---f"`, the name is `_f`

## Basic Value Options

The most basic option is a value option. These options accept one argument
which is a value. If no type is provided, the type of the default value is
used. If no default value is provided, the type is assumed to be
[`STRING`](../api/index#click.STRING "click.STRING"). Unless a name is
explicitly specified, the name of the parameter is the first long option
defined; otherwise the first short one is used. By default, options are not
required, however to make an option required, simply pass in `required=True`
as an argument to the decorator.

    
    
    @click.command()
    @click.option('--n', default=1)
    def dots(n):
        click.echo('.' * n)
    
    
    
    # How to make an option required
    @click.command()
    @click.option('--n', required=True, type=int)
    def dots(n):
        click.echo('.' * n)
    
    
    
    # How to use a Python reserved word such as `from` as a parameter
    @click.command()
    @click.option('--from', '-f', 'from_')
    @click.option('--to', '-t')
    def reserved_param_name(from_, to):
        click.echo(f"from {from_} to {to}")
    

And on the command line:

    
    
    $ dots --n=2
    ..
    

In this case the option is of type [`INT`](../api/index#click.INT "click.INT")
because the default value is an integer.

To show the default values when showing command help, use `show_default=True`

    
    
    @click.command()
    @click.option('--n', default=1, show_default=True)
    def dots(n):
        click.echo('.' * n)
    
    
    
    $ dots --help
    Usage: dots [OPTIONS]
    
    Options:
      --n INTEGER  [default: 1]
      --help       Show this message and exit.
    

For single option boolean flags, the default remains hidden if the default
value is False.

    
    
    @click.command()
    @click.option('--n', default=1, show_default=True)
    @click.option("--gr", is_flag=True, show_default=True, default=False, help="Greet the world.")
    @click.option("--br", is_flag=True, show_default=True, default=True, help="Add a thematic break")
    def dots(n, gr, br):
        if gr:
            click.echo('Hello world!')
        click.echo('.' * n)
        if br:
            click.echo('-' * n)
    
    
    
    $ dots --help
    Usage: dots [OPTIONS]
    
    Options:
      --n INTEGER  [default: 1]
      --gr         Greet the world.
      --br         Add a thematic break  [default: True]
      --help       Show this message and exit.
    

## Multi Value Options

Sometimes, you have options that take more than one argument. For options,
only a fixed number of arguments is supported. This can be configured by the
`nargs` parameter. The values are then stored as a tuple.

    
    
    @click.command()
    @click.option('--pos', nargs=2, type=float)
    def findme(pos):
        a, b = pos
        click.echo(f"{a} / {b}")
    

And on the command line:

    
    
    $ findme --pos 2.0 3.0
    2.0 / 3.0
    

## Tuples as Multi Value Options

Changelog

New in version 4.0.

As you can see that by using `nargs` set to a specific number each item in the
resulting tuple is of the same type. This might not be what you want. Commonly
you might want to use different types for different indexes in the tuple. For
this you can directly specify a tuple as type:

    
    
    @click.command()
    @click.option('--item', type=(str, int))
    def putitem(item):
        name, id = item
        click.echo(f"name={name} id={id}")
    

And on the command line:

    
    
    $ putitem --item peter 1338
    name=peter id=1338
    

By using a tuple literal as type, `nargs` gets automatically set to the length
of the tuple and the [`click.Tuple`](../api/index#click.Tuple "click.Tuple")
type is automatically used. The above example is thus equivalent to this:

    
    
    @click.command()
    @click.option('--item', nargs=2, type=click.Tuple([str, int]))
    def putitem(item):
        name, id = item
        click.echo(f"name={name} id={id}")
    

## Multiple Options

Similarly to `nargs`, there is also the case of wanting to support a parameter
being provided multiple times and have all the values recorded – not just the
last one. For instance, `git commit -m foo -m bar` would record two lines for
the commit message: `foo` and `bar`. This can be accomplished with the
`multiple` flag:

Example:

    
    
    @click.command()
    @click.option('--message', '-m', multiple=True)
    def commit(message):
        click.echo('\n'.join(message))
    

And on the command line:

    
    
    $ commit -m foo -m bar
    foo
    bar
    

When passing a `default` with `multiple=True`, the default value must be a
list or tuple, otherwise it will be interpreted as a list of single
characters.

    
    
    @click.option("--format", multiple=True, default=["json"])
    

## Counting

In some very rare circumstances, it is interesting to use the repetition of
options to count an integer up. This can be used for verbosity flags, for
instance:

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

And on the command line:

    
    
    $ log -vvv
    Verbosity: 3
    

## Boolean Flags

Boolean flags are options that can be enabled or disabled. This can be
accomplished by defining two flags in one go separated by a slash (`/`) for
enabling or disabling the option. (If a slash is in an option string, Click
automatically knows that it’s a boolean flag and will pass `is_flag=True`
implicitly.) Click always wants you to provide an enable and disable flag so
that you can change the default later.

Example:

    
    
    import sys
    
    @click.command()
    @click.option('--shout/--no-shout', default=False)
    def info(shout):
        rv = sys.platform
        if shout:
            rv = rv.upper() + '!!!!111'
        click.echo(rv)
    

And on the command line:

    
    
    $ info --shout
    LINUX!!!!111
    $ info --no-shout
    linux
    $ info
    linux
    

If you really don’t want an off-switch, you can just define one and manually
inform Click that something is a flag:

    
    
    import sys
    
    @click.command()
    @click.option('--shout', is_flag=True)
    def info(shout):
        rv = sys.platform
        if shout:
            rv = rv.upper() + '!!!!111'
        click.echo(rv)
    

And on the command line:

    
    
    $ info --shout
    LINUX!!!!111
    $ info
    linux
    

Note that if a slash is contained in your option already (for instance, if you
use Windows-style parameters where `/` is the prefix character), you can
alternatively split the parameters through `;` instead:

    
    
    @click.command()
    @click.option('/debug;/no-debug')
    def log(debug):
        click.echo(f"debug={debug}")
    
    if __name__ == '__main__':
        log()
    

Changelog

Changed in version 6.0.

If you want to define an alias for the second option only, then you will need
to use leading whitespace to disambiguate the format string:

Example:

    
    
    import sys
    
    @click.command()
    @click.option('--shout/--no-shout', ' /-S', default=False)
    def info(shout):
        rv = sys.platform
        if shout:
            rv = rv.upper() + '!!!!111'
        click.echo(rv)
    
    
    
    $ info --help
    Usage: info [OPTIONS]
    
    Options:
      --shout / -S, --no-shout
      --help                    Show this message and exit.
    

## Feature Switches

In addition to boolean flags, there are also feature switches. These are
implemented by setting multiple options to the same parameter name and
defining a flag value. Note that by providing the `flag_value` parameter,
Click will implicitly set `is_flag=True`.

To set a default flag, assign a value of `True` to the flag that should be the
default.

    
    
    import sys
    
    @click.command()
    @click.option('--upper', 'transformation', flag_value='upper',
                  default=True)
    @click.option('--lower', 'transformation', flag_value='lower')
    def info(transformation):
        click.echo(getattr(sys.platform, transformation)())
    

And on the command line:

    
    
    $ info --upper
    LINUX
    $ info --lower
    linux
    $ info
    LINUX
    

## Choice Options

Sometimes, you want to have a parameter be a choice of a list of values. In
that case you can use [`Choice`](../api/index#click.Choice "click.Choice")
type. It can be instantiated with a list of valid values. The originally
passed choice will be returned, not the str passed on the command line. Token
normalization functions and `case_sensitive=False` can cause the two to be
different but still match.

Example:

    
    
    @click.command()
    @click.option('--hash-type',
                  type=click.Choice(['MD5', 'SHA1'], case_sensitive=False))
    def digest(hash_type):
        click.echo(hash_type)
    

What it looks like:

    
    
    $ digest --hash-type=MD5
    MD5
    
    $ digest --hash-type=md5
    MD5
    
    $ digest --hash-type=foo
    Usage: digest [OPTIONS]
    Try 'digest --help' for help.
    
    Error: Invalid value for '--hash-type': 'foo' is not one of 'MD5', 'SHA1'.
    
    $ digest --help
    Usage: digest [OPTIONS]
    
    Options:
      --hash-type [MD5|SHA1]
      --help                  Show this message and exit.
    

Only pass the choices as list or tuple. Other iterables (like generators) may
lead to unexpected results.

Choices work with options that have `multiple=True`. If a `default` value is
given with `multiple=True`, it should be a list or tuple of valid choices.

Choices should be unique after considering the effects of `case_sensitive` and
any specified token normalization function.

Changelog

Changed in version 7.1: The resulting value from an option will always be one
of the originally passed choices regardless of `case_sensitive`.

## Prompting

In some cases, you want parameters that can be provided from the command line,
but if not provided, ask for user input instead. This can be implemented with
Click by defining a prompt string.

Example:

    
    
    @click.command()
    @click.option('--name', prompt=True)
    def hello(name):
        click.echo(f"Hello {name}!")
    

And what it looks like:

    
    
    $ hello --name=John
    Hello John!
    $ hello
    Name: John
    Hello John!
    

If you are not happy with the default prompt string, you can ask for a
different one:

    
    
    @click.command()
    @click.option('--name', prompt='Your name please')
    def hello(name):
        click.echo(f"Hello {name}!")
    

What it looks like:

    
    
    $ hello
    Your name please: John
    Hello John!
    

It is advised that prompt not be used in conjunction with the multiple flag
set to True. Instead, prompt in the function interactively.

By default, the user will be prompted for an input if one was not passed
through the command line. To turn this behavior off, see Optional Value.

## Password Prompts

Click also supports hidden prompts and asking for confirmation. This is useful
for password input:

    
    
    import codecs
    
    @click.command()
    @click.option(
        "--password", prompt=True, hide_input=True,
        confirmation_prompt=True
    )
    def encode(password):
        click.echo(f"encoded: {codecs.encode(password, 'rot13')}")
    
    
    
    $ encode
    Password: 
    Repeat for confirmation: 
    encoded: frperg
    

Because this combination of parameters is quite common, this can also be
replaced with the [`password_option()`](../api/index#click.password_option
"click.password_option") decorator:

    
    
    @click.command()
    @click.password_option()
    def encrypt(password):
        click.echo(f"encoded: to {codecs.encode(password, 'rot13')}")
    

## Dynamic Defaults for Prompts

The `auto_envvar_prefix` and `default_map` options for the context allow the
program to read option values from the environment or a configuration file.
However, this overrides the prompting mechanism, so that the user does not get
the option to change the value interactively.

If you want to let the user configure the default value, but still be prompted
if the option isn’t specified on the command line, you can do so by supplying
a callable as the default value. For example, to get a default from the
environment:

    
    
    import os
    
    @click.command()
    @click.option(
        "--username", prompt=True,
        default=lambda: os.environ.get("USER", "")
    )
    def hello(username):
        click.echo(f"Hello, {username}!")
    

To describe what the default value will be, set it in `show_default`.

    
    
    import os
    
    @click.command()
    @click.option(
        "--username", prompt=True,
        default=lambda: os.environ.get("USER", ""),
        show_default="current user"
    )
    def hello(username):
        click.echo(f"Hello, {username}!")
    
    
    
    $ hello --help
    Usage: hello [OPTIONS]
    
    Options:
      --username TEXT  [default: (current user)]
      --help           Show this message and exit.
    

## Callbacks and Eager Options

Sometimes, you want a parameter to completely change the execution flow. For
instance, this is the case when you want to have a `--version` parameter that
prints out the version and then exits the application.

Note: an actual implementation of a `--version` parameter that is reusable is
available in Click as
[`click.version_option()`](../api/index#click.version_option
"click.version_option"). The code here is merely an example of how to
implement such a flag.

In such cases, you need two concepts: eager parameters and a callback. An
eager parameter is a parameter that is handled before others, and a callback
is what executes after the parameter is handled. The eagerness is necessary so
that an earlier required parameter does not produce an error message. For
instance, if `--version` was not eager and a parameter `--foo` was required
and defined before, you would need to specify it for `--version` to work. For
more information, see [Callback Evaluation Order](../advanced/index#callback-
evaluation-order).

A callback is a function that is invoked with three parameters: the current
[`Context`](../api/index#click.Context "click.Context"), the current
[`Parameter`](../api/index#click.Parameter "click.Parameter"), and the value.
The context provides some useful features such as quitting the application and
gives access to other already processed parameters.

Here an example for a `--version` flag:

    
    
    def print_version(ctx, param, value):
        if not value or ctx.resilient_parsing:
            return
        click.echo('Version 1.0')
        ctx.exit()
    
    @click.command()
    @click.option('--version', is_flag=True, callback=print_version,
                  expose_value=False, is_eager=True)
    def hello():
        click.echo('Hello World!')
    

The `expose_value` parameter prevents the pretty pointless `version` parameter
from being passed to the callback. If that was not specified, a boolean would
be passed to the `hello` script. The `resilient_parsing` flag is applied to
the context if Click wants to parse the command line without any destructive
behavior that would change the execution flow. In this case, because we would
exit the program, we instead do nothing.

What it looks like:

    
    
    $ hello
    Hello World!
    $ hello --version
    Version 1.0
    

Callback Signature Changes

In Click 2.0 the signature for callbacks changed. For more information about
these changes see [Upgrading to 2.0](../upgrading/index#upgrade-to-2-0).

## Yes Parameters

For dangerous operations, it’s very useful to be able to ask a user for
confirmation. This can be done by adding a boolean `--yes` flag and asking for
confirmation if the user did not provide it and to fail in a callback:

    
    
    def abort_if_false(ctx, param, value):
        if not value:
            ctx.abort()
    
    @click.command()
    @click.option('--yes', is_flag=True, callback=abort_if_false,
                  expose_value=False,
                  prompt='Are you sure you want to drop the db?')
    def dropdb():
        click.echo('Dropped all tables!')
    

And what it looks like on the command line:

    
    
    $ dropdb
    Are you sure you want to drop the db? [y/N]: n
    Aborted!
    $ dropdb --yes
    Dropped all tables!
    

Because this combination of parameters is quite common, this can also be
replaced with the
[`confirmation_option()`](../api/index#click.confirmation_option
"click.confirmation_option") decorator:

    
    
    @click.command()
    @click.confirmation_option(prompt='Are you sure you want to drop the db?')
    def dropdb():
        click.echo('Dropped all tables!')
    

Callback Signature Changes

In Click 2.0 the signature for callbacks changed. For more information about
these changes see [Upgrading to 2.0](../upgrading/index#upgrade-to-2-0).

## Values from Environment Variables

A very useful feature of Click is the ability to accept parameters from
environment variables in addition to regular parameters. This allows tools to
be automated much easier. For instance, you might want to pass a configuration
file with a `--config` parameter but also support exporting a
`TOOL_CONFIG=hello.cfg` key-value pair for a nicer development experience.

This is supported by Click in two ways. One is to automatically build
environment variables which is supported for options only. To enable this
feature, the `auto_envvar_prefix` parameter needs to be passed to the script
that is invoked. Each command and parameter is then added as an uppercase
underscore-separated variable. If you have a subcommand called `run` taking an
option called `reload` and the prefix is `WEB`, then the variable is
`WEB_RUN_RELOAD`.

Example usage:

    
    
    @click.command()
    @click.option('--username')
    def greet(username):
        click.echo(f'Hello {username}!')
    
    if __name__ == '__main__':
        greet(auto_envvar_prefix='GREETER')
    

And from the command line:

    
    
    $ export GREETER_USERNAME=john
    $ greet
    Hello john!
    

When using `auto_envvar_prefix` with command groups, the command name needs to
be included in the environment variable, between the prefix and the parameter
name, _i.e._ `PREFIX_COMMAND_VARIABLE`. If you have a subcommand called `run-
server` taking an option called `host` and the prefix is `WEB`, then the
variable is `WEB_RUN_SERVER_HOST`.

Example:

    
    
    @click.group()
    @click.option('--debug/--no-debug')
    def cli(debug):
        click.echo(f"Debug mode is {'on' if debug else 'off'}")
    
    @cli.command()
    @click.option('--username')
    def greet(username):
        click.echo(f"Hello {username}!")
    
    if __name__ == '__main__':
        cli(auto_envvar_prefix='GREETER')
    
    
    
    $ export GREETER_DEBUG=false
    $ export GREETER_GREET_USERNAME=John
    $ cli greet
    Debug mode is off
    Hello John!
    

The second option is to manually pull values in from specific environment
variables by defining the name of the environment variable on the option.

Example usage:

    
    
    @click.command()
    @click.option('--username', envvar='USERNAME')
    def greet(username):
       click.echo(f"Hello {username}!")
    
    if __name__ == '__main__':
        greet()
    

And from the command line:

    
    
    $ export USERNAME=john
    $ greet
    Hello john!
    

In that case it can also be a list of different environment variables where
the first one is picked.

## Multiple Values from Environment Values

As options can accept multiple values, pulling in such values from environment
variables (which are strings) is a bit more complex. The way Click solves this
is by leaving it up to the type to customize this behavior. For both
`multiple` and `nargs` with values other than `1`, Click will invoke the
[`ParamType.split_envvar_value()`](../api/index#click.ParamType.split_envvar_value
"click.ParamType.split_envvar_value") method to perform the splitting.

The default implementation for all types is to split on whitespace. The
exceptions to this rule are the [`File`](../api/index#click.File "click.File")
and [`Path`](../api/index#click.Path "click.Path") types which both split
according to the operating system’s path splitting rules. On Unix systems like
Linux and OS X, the splitting happens for those on every colon (`:`), and for
Windows, on every semicolon (`;`).

Example usage:

    
    
    @click.command()
    @click.option('paths', '--path', envvar='PATHS', multiple=True,
                  type=click.Path())
    def perform(paths):
        for path in paths:
            click.echo(path)
    
    if __name__ == '__main__':
        perform()
    

And from the command line:

    
    
    $ export PATHS=./foo/bar:./test
    $ perform
    ./foo/bar
    ./test
    

## Other Prefix Characters

Click can deal with alternative prefix characters other than `-` for options.
This is for instance useful if you want to handle slashes as parameters `/` or
something similar. Note that this is strongly discouraged in general because
Click wants developers to stay close to POSIX semantics. However in certain
situations this can be useful:

    
    
    @click.command()
    @click.option('+w/-w')
    def chmod(w):
        click.echo(f"writable={w}")
    
    if __name__ == '__main__':
        chmod()
    

And from the command line:

    
    
    $ chmod +w
    writable=True
    $ chmod -w
    writable=False
    

Note that if you are using `/` as prefix character and you want to use a
boolean flag you need to separate it with `;` instead of `/`:

    
    
    @click.command()
    @click.option('/debug;/no-debug')
    def log(debug):
        click.echo(f"debug={debug}")
    
    if __name__ == '__main__':
        log()
    

## Range Options

The [`IntRange`](../api/index#click.IntRange "click.IntRange") type extends
the [`INT`](../api/index#click.INT "click.INT") type to ensure the value is
contained in the given range. The [`FloatRange`](../api/index#click.FloatRange
"click.FloatRange") type does the same for [`FLOAT`](../api/index#click.FLOAT
"click.FLOAT").

If `min` or `max` is omitted, that side is _unbounded_. Any value in that
direction is accepted. By default, both bounds are _closed_ , which means the
boundary value is included in the accepted range. `min_open` and `max_open`
can be used to exclude that boundary from the range.

If `clamp` mode is enabled, a value that is outside the range is set to the
boundary instead of failing. For example, the range `0, 5` would return `5`
for the value `10`, or `0` for the value `-1`. When using
[`FloatRange`](../api/index#click.FloatRange "click.FloatRange"), `clamp` can
only be enabled if both bounds are _closed_ (the default).

    
    
    @click.command()
    @click.option("--count", type=click.IntRange(0, 20, clamp=True))
    @click.option("--digit", type=click.IntRange(0, 9))
    def repeat(count, digit):
        click.echo(str(digit) * count)
    
    
    
    $ repeat --count=100 --digit=5
    55555555555555555555
    $ repeat --count=6 --digit=12
    Usage: repeat [OPTIONS]
    Try 'repeat --help' for help.
    
    Error: Invalid value for '--digit': 12 is not in the range 0<=x<=9.
    

## Callbacks for Validation

Changelog

Changed in version 2.0.

If you want to apply custom validation logic, you can do this in the parameter
callbacks. These callbacks can both modify values as well as raise errors if
the validation does not work. The callback runs after type conversion. It is
called for all sources, including prompts.

In Click 1.0, you can only raise the
[`UsageError`](../api/index#click.UsageError "click.UsageError") but starting
with Click 2.0, you can also raise the
[`BadParameter`](../api/index#click.BadParameter "click.BadParameter") error,
which has the added advantage that it will automatically format the error
message to also contain the parameter name.

    
    
    def validate_rolls(ctx, param, value):
        if isinstance(value, tuple):
            return value
    
        try:
            rolls, _, dice = value.partition("d")
            return int(dice), int(rolls)
        except ValueError:
            raise click.BadParameter("format must be 'NdM'")
    
    @click.command()
    @click.option(
        "--rolls", type=click.UNPROCESSED, callback=validate_rolls,
        default="1d6", prompt=True,
    )
    def roll(rolls):
        sides, times = rolls
        click.echo(f"Rolling a {sides}-sided dice {times} time(s)")
    
    
    
    $ roll --rolls=42
    Usage: roll [OPTIONS]
    Try 'roll --help' for help.
    
    Error: Invalid value for '--rolls': format must be 'NdM'
    
    $ roll --rolls=2d12
    Rolling a 12-sided dice 2 time(s)
    
    $ roll
    Rolls [1d6]: 42
    Error: format must be 'NdM'
    Rolls [1d6]: 2d12
    Rolling a 12-sided dice 2 time(s)
    

## Optional Value

Providing the value to an option can be made optional, in which case providing
only the option’s flag without a value will either show a prompt or use its
`flag_value`.

Setting `is_flag=False, flag_value=value` tells Click that the option can
still be passed a value, but if only the flag is given the `flag_value` is
used.

    
    
    @click.command()
    @click.option("--name", is_flag=False, flag_value="Flag", default="Default")
    def hello(name):
        click.echo(f"Hello, {name}!")
    
    
    
    $ hello
    Hello, Default!
    $ hello --name Value
    Hello, Value!
    $ hello --name
    Hello, Flag!
    

If the option has `prompt` enabled, then setting `prompt_required=False` tells
Click to only show the prompt if the option’s flag is given, instead of if the
option is not provided at all.

    
    
    @click.command()
    @click.option('--name', prompt=True, prompt_required=False, default="Default")
    def hello(name):
        click.echo(f"Hello {name}!")
    
    
    
    $ hello
    Hello Default!
    $ hello --name Value
    Hello Value!
    $ hello --name
    Name [Default]: 
    

If `required=True`, then the option will still prompt if it is not given, but
it will also prompt if only the flag is given.

# Parameters

Click supports two types of parameters for scripts: options and arguments.
There is generally some confusion among authors of command line scripts of
when to use which, so here is a quick overview of the differences. As its name
indicates, an option is optional. While arguments can be optional within
reason, they are much more restricted in how optional they can be.

To help you decide between options and arguments, the recommendation is to use
arguments exclusively for things like going to subcommands or input filenames
/ URLs, and have everything else be an option instead.

## Differences

Arguments can do less than options. The following features are only available
for options:

  * automatic prompting for missing input
  * act as flags (boolean or otherwise)
  * option values can be pulled from environment variables, arguments can not
  * options are fully documented in the help page, arguments are not ([this is intentional](../documentation/index#documenting-arguments) as arguments might be too specific to be automatically documented)

On the other hand arguments, unlike options, can accept an arbitrary number of
arguments. Options can strictly ever only accept a fixed number of arguments
(defaults to 1), or they may be specified multiple times using [Multiple
Options](../options/index#multiple-options).

## Parameter Types

Parameters can be of different types. Types can be implemented with different
behavior and some are supported out of the box:

`str / click.STRING:`

    

The default parameter type which indicates unicode strings.

`int / click.INT:`

    

A parameter that only accepts integers.

`float / click.FLOAT:`

    

A parameter that only accepts floating point values.

`bool / click.BOOL:`

    

A parameter that accepts boolean values. This is automatically used for
boolean flags. The string values “1”, “true”, “t”, “yes”, “y”, and “on”
convert to `True`. “0”, “false”, “f”, “no”, “n”, and “off” convert to `False`.

`click.UUID:`

    

A parameter that accepts UUID values. This is not automatically guessed but
represented as
[`uuid.UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID "\(in
Python v3.12\)").

_class_ click.File(_mode ='r'_, _encoding =None_, _errors ='strict'_, _lazy
=None_, _atomic =False_)

    

Declares a parameter to be a file for reading or writing. The file is
automatically closed once the context tears down (after the command finished
working).

Files can be opened for reading or writing. The special value `-` indicates
stdin or stdout depending on the mode.

By default, the file is opened for reading text data, but it can also be
opened in binary mode or for writing. The encoding parameter can be used to
force a specific encoding.

The `lazy` flag controls if the file should be opened immediately or upon
first IO. The default is to be non-lazy for standard input and output streams
as well as files opened for reading, `lazy` otherwise. When opening a file
lazily for reading, it is still opened temporarily for validation, but will
not be held open until first IO. lazy is mainly useful when opening for
writing to avoid creating the file until it is needed.

Starting with Click 2.0, files can also be opened atomically in which case all
writes go into a separate file in the same folder and upon completion the file
will be moved over to the original location. This is useful if a file
regularly read by other users is modified.

See [File Arguments](../arguments/index#file-args) for more information.

Parameters:

    

  * **mode** ([str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.12\)")) – 
  * **encoding** ([str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.12\)") _|__None_) – 
  * **errors** ([str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.12\)") _|__None_) – 
  * **lazy** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)") _|__None_) – 
  * **atomic** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 

_class_ click.Path(_exists =False_, _file_okay =True_, _dir_okay =True_,
_writable =False_, _readable =True_, _resolve_path =False_, _allow_dash
=False_, _path_type =None_, _executable =False_)

    

The `Path` type is similar to the [`File`](../api/index#click.File
"click.File") type, but returns the filename instead of an open file. Various
checks can be enabled to validate the type of file and permissions.

Parameters:

    

  * **exists** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – The file or directory needs to exist for the value to be valid. If this is not set to `True`, and the file does not exist, then all further checks are silently skipped.
  * **file_okay** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – Allow a file as a value.
  * **dir_okay** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – Allow a directory as a value.
  * **readable** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – if true, a readable check is performed.
  * **writable** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – if true, a writable check is performed.
  * **executable** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – if true, an executable check is performed.
  * **resolve_path** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – Make the value absolute and resolve any symlinks. A `~` is not expanded, as this is supposed to be done by the shell only.
  * **allow_dash** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – Allow a single dash as a value, which indicates a standard stream (but does not open it). Use [`open_file()`](../api/index#click.open_file "click.open_file") to handle opening this value.
  * **path_type** ([Type](https://docs.python.org/3/library/typing.html#typing.Type "\(in Python v3.12\)") _[_[Any](https://docs.python.org/3/library/typing.html#typing.Any "\(in Python v3.12\)") _]__|__None_) – Convert the incoming path value to this type. If `None`, keep Python’s default, which is `str`. Useful to convert to [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "\(in Python v3.12\)").

Changed in version 8.1: Added the `executable` parameter.

Changelog

Changed in version 8.0: Allow passing `path_type=pathlib.Path`.

Changed in version 6.0: Added the `allow_dash` parameter.

_class_ click.Choice(_choices_ , _case_sensitive =True_)

    

The choice type allows a value to be checked against a fixed set of supported
values. All of these values have to be strings.

You should only pass a list or tuple of choices. Other iterables (like
generators) may lead to surprising results.

The resulting value will always be one of the originally passed choices
regardless of `case_sensitive` or any `ctx.token_normalize_func` being
specified.

See [Choice Options](../options/index#choice-opts) for an example.

Parameters:

    

  * **case_sensitive** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – Set to false to make choices case insensitive. Defaults to true.
  * **choices** ([Sequence](https://docs.python.org/3/library/typing.html#typing.Sequence "\(in Python v3.12\)") _[_[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.12\)") _]_) – 

_class_ click.IntRange(_min =None_, _max =None_, _min_open =False_, _max_open
=False_, _clamp =False_)

    

Restrict an [`click.INT`](../api/index#click.INT "click.INT") value to a range
of accepted values. See [Range Options](../options/index#ranges).

If `min` or `max` are not passed, any value is accepted in that direction. If
`min_open` or `max_open` are enabled, the corresponding boundary is not
included in the range.

If `clamp` is enabled, a value outside the range is clamped to the boundary
instead of failing.

Changelog

Changed in version 8.0: Added the `min_open` and `max_open` parameters.

Parameters:

    

  * **min** ([float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.12\)") _|__None_) – 
  * **max** ([float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.12\)") _|__None_) – 
  * **min_open** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 
  * **max_open** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 
  * **clamp** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 

_class_ click.FloatRange(_min =None_, _max =None_, _min_open =False_,
_max_open =False_, _clamp =False_)

    

Restrict a [`click.FLOAT`](../api/index#click.FLOAT "click.FLOAT") value to a
range of accepted values. See [Range Options](../options/index#ranges).

If `min` or `max` are not passed, any value is accepted in that direction. If
`min_open` or `max_open` are enabled, the corresponding boundary is not
included in the range.

If `clamp` is enabled, a value outside the range is clamped to the boundary
instead of failing. This is not supported if either boundary is marked `open`.

Changelog

Changed in version 8.0: Added the `min_open` and `max_open` parameters.

Parameters:

    

  * **min** ([float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.12\)") _|__None_) – 
  * **max** ([float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.12\)") _|__None_) – 
  * **min_open** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 
  * **max_open** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 
  * **clamp** ([bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)")) – 

_class_ click.DateTime(_formats =None_)

    

The DateTime type converts date strings into `datetime` objects.

The format strings which are checked are configurable, but default to some
common (non-timezone aware) ISO 8601 formats.

When specifying _DateTime_ formats, you should only pass a list or a tuple.
Other iterables, like generators, may lead to surprising results.

The format strings are processed using `datetime.strptime`, and this
consequently defines the format strings which are allowed.

Parsing is tried using each format, in order, and the first format which
parses successfully is used.

Parameters:

    

**formats**
([Sequence](https://docs.python.org/3/library/typing.html#typing.Sequence
"\(in Python v3.12\)")
_[_[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.12\)") _]__|__None_) – A list or tuple of date format strings, in the order
in which they should be tried. Defaults to `'%Y-%m-%d'`,
`'%Y-%m-%dT%H:%M:%S'`, `'%Y-%m-%d %H:%M:%S'`.

Custom parameter types can be implemented by subclassing
[`click.ParamType`](../api/index#click.ParamType "click.ParamType"). For
simple cases, passing a Python function that fails with a `ValueError` is also
supported, though discouraged.

## Parameter Names

Parameters (both options and arguments) have a name that will be used as the
Python argument name when calling the decorated function with values.

Arguments take only one positional name. To provide a different name for use
in help text, see [Truncating Help Texts](../documentation/index#doc-meta-
variables).

Options can have many names that may be prefixed with one or two dashes. Names
with one dash are parsed as short options, names with two are parsed as long
options. If a name is not prefixed, it is used as the Python argument name and
not parsed as an option name. Otherwise, the first name with a two dash prefix
is used, or the first with a one dash prefix if there are none with two. The
prefix is removed and dashes are converted to underscores to get the Python
argument name.

## Implementing Custom Types

To implement a custom type, you need to subclass the
[`ParamType`](../api/index#click.ParamType "click.ParamType") class. Override
the [`convert()`](../api/index#click.ParamType.convert
"click.ParamType.convert") method to convert the value from a string to the
correct type.

The following code implements an integer type that accepts hex and octal
numbers in addition to normal integers, and converts them into regular
integers.

    
    
    import click
    
    class BasedIntParamType(click.ParamType):
        name = "integer"
    
        def convert(self, value, param, ctx):
            if isinstance(value, int):
                return value
    
            try:
                if value[:2].lower() == "0x":
                    return int(value[2:], 16)
                elif value[:1] == "0":
                    return int(value, 8)
                return int(value, 10)
            except ValueError:
                self.fail(f"{value!r} is not a valid integer", param, ctx)
    
    BASED_INT = BasedIntParamType()
    

The [`name`](../api/index#click.ParamType.name "click.ParamType.name")
attribute is optional and is used for documentation. Call
[`fail()`](../api/index#click.ParamType.fail "click.ParamType.fail") if
conversion fails. The `param` and `ctx` arguments may be `None` in some cases
such as prompts.

Values from user input or the command line will be strings, but default values
and Python arguments may already be the correct type. The custom type should
check at the top if the value is already valid and pass it through to support
those cases.

# User Input Prompts

Click supports prompts in two different places. The first is automated prompts
when the parameter handling happens, and the second is to ask for prompts at a
later point independently.

This can be accomplished with the [`prompt()`](../api/index#click.prompt
"click.prompt") function, which asks for valid input according to a type, or
the [`confirm()`](../api/index#click.confirm "click.confirm") function, which
asks for confirmation (yes/no).

## Option Prompts

Option prompts are integrated into the option interface. See
[Prompting](../options/index#option-prompting) for more information.
Internally, it automatically calls either
[`prompt()`](../api/index#click.prompt "click.prompt") or
[`confirm()`](../api/index#click.confirm "click.confirm") as necessary.

## Input Prompts

To manually ask for user input, you can use the
[`prompt()`](../api/index#click.prompt "click.prompt") function. By default,
it accepts any Unicode string, but you can ask for any other type. For
instance, you can ask for a valid integer:

    
    
    value = click.prompt('Please enter a valid integer', type=int)
    

Additionally, the type will be determined automatically if a default value is
provided. For instance, the following will only accept floats:

    
    
    value = click.prompt('Please enter a number', default=42.0)
    

## Confirmation Prompts

To ask if a user wants to continue with an action, the
[`confirm()`](../api/index#click.confirm "click.confirm") function comes in
handy. By default, it returns the result of the prompt as a boolean value:

    
    
    if click.confirm('Do you want to continue?'):
        click.echo('Well done!')
    

There is also the option to make the function automatically abort the
execution of the program if it does not return `True`:

    
    
    click.confirm('Do you want to continue?', abort=True)
    

# Quickstart

You can get the library directly from PyPI:

    
    
    pip install click
    

The installation into a virtualenv is heavily recommended.

## virtualenv

Virtualenv is probably what you want to use for developing Click applications.

What problem does virtualenv solve? Chances are that you want to use it for
other projects besides your Click script. But the more projects you have, the
more likely it is that you will be working with different versions of Python
itself, or at least different versions of Python libraries. Let’s face it:
quite often libraries break backwards compatibility, and it’s unlikely that
any serious application will have zero dependencies. So what do you do if two
or more of your projects have conflicting dependencies?

Virtualenv to the rescue! Virtualenv enables multiple side-by-side
installations of Python, one for each project. It doesn’t actually install
separate copies of Python, but it does provide a clever way to keep different
project environments isolated.

Create your project folder, then a virtualenv within it:

    
    
    $ mkdir myproject
    $ cd myproject
    $ python3 -m venv .venv
    

Now, whenever you want to work on a project, you only have to activate the
corresponding environment. On OS X and Linux, do the following:

    
    
    $ . .venv/bin/activate
    (venv) $
    

If you are a Windows user, the following command is for you:

    
    
    > .venv\scripts\activate
    (venv) >
    

Either way, you should now be using your virtualenv (notice how the prompt of
your shell has changed to show the active environment).

And if you want to stop using the virtualenv, use the following command:

    
    
    $ deactivate
    

After doing this, the prompt of your shell should be as familiar as before.

Now, let’s move on. Enter the following command to get Click activated in your
virtualenv:

    
    
    $ pip install click
    

A few seconds later and you are good to go.

## 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.

  * [Building Command Line Applications with Click](https://www.youtube.com/watch?v=kNke39OZ2k0)

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 output](https://github.com/pallets/click/tree/main/examples/inout)
  * `naval`: [Port of docopt naval example](https://github.com/pallets/click/tree/main/examples/naval)
  * `aliases`: [Command alias example](https://github.com/pallets/click/tree/main/examples/aliases)
  * `repo`: [Git-/Mercurial-like command line interface](https://github.com/pallets/click/tree/main/examples/repo)
  * `complex`: [Complex example with plugin loading](https://github.com/pallets/click/tree/main/examples/complex)
  * `validation`: [Custom parameter validation example](https://github.com/pallets/click/tree/main/examples/validation)
  * `colors`: [Color support demo](https://github.com/pallets/click/tree/main/examples/colors)
  * `termui`: [Terminal UI functions demo](https://github.com/pallets/click/tree/main/examples/termui)
  * `imagepipe`: [Multi command chaining demo](https://github.com/pallets/click/tree/main/examples/imagepipe)

## Basic Concepts - Creating a Command

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()`](../api/index#click.command "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`](../api/index#click.Command "click.Command") which then can be
invoked:

    
    
    if __name__ == '__main__':
        hello()
    

And what it looks like:

    
    
    $ python hello.py
    Hello World!
    

And the corresponding help page:

    
    
    $ python hello.py --help
    Usage: hello.py [OPTIONS]
    
    Options:
      --help  Show this message and exit.
    

## Echoing

Why does this example use [`echo()`](../api/index#click.echo "click.echo")
instead of the regular
[`print()`](https://docs.python.org/3/library/functions.html#print "\(in
Python v3.12\)") function? The answer to this question is that Click attempts
to support different environments consistently 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()`](../api/index#click.echo "click.echo")
function applies some error correction in case the terminal is misconfigured
instead of dying with a
[`UnicodeError`](https://docs.python.org/3/library/exceptions.html#UnicodeError
"\(in Python v3.12\)").

The echo function also supports color and other styles in output. It will
automatically remove styles if the output stream is a file. On Windows,
colorama is automatically installed and used. See [ANSI
Colors](../utils/index#ansi-colors).

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`](../api/index#click.Group "click.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()`](../api/index#click.group "click.group")
decorator works like the [`command()`](../api/index#click.command
"click.command") decorator, but creates a [`Group`](../api/index#click.Group
"click.Group") object instead which can be given multiple subcommands that can
be attached with [`Group.add_command()`](../api/index#click.Group.add_command
"click.Group.add_command").

For simple scripts, it’s also possible to automatically attach and create a
command by using the [`Group.command()`](../api/index#click.Group.command
"click.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')
    

You would then invoke the [`Group`](../api/index#click.Group "click.Group") in
your setuptools entry points or other invocations:

    
    
    if __name__ == '__main__':
        cli()
    

## Registering Commands Later

Instead of using the `@group.command()` decorator, commands can be decorated
with the plain `@click.command()` decorator and registered with a group later
with `group.add_command()`. This could be used to split commands into multiple
Python modules.

    
    
    @click.command()
    def greet():
        click.echo("Hello, World!")
    
    
    
    @click.group()
    def group():
        pass
    
    group.add_command(greet)
    

## Adding Parameters

To add parameters, use the [`option()`](../api/index#click.option
"click.option") and [`argument()`](../api/index#click.argument
"click.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(f"Hello {name}!")
    

What it looks like:

    
    
    $ python hello.py --help
    Usage: hello.py [OPTIONS] NAME
    
    Options:
      --count INTEGER  number of greetings
      --help           Show this message and exit.
    

## Switching to Setuptools

In the code you wrote so far there is a block at the end of the file which
looks like this: `if __name__ == '__main__':`. This is traditionally how a
standalone Python file looks like. With Click you can continue doing that, but
there are better ways through setuptools.

There are two main (and many more) reasons for this:

The first one is that setuptools automatically generates executable wrappers
for Windows so your command line utilities work on Windows too.

The second reason is that setuptools scripts work with virtualenv on Unix
without the virtualenv having to be activated. This is a very useful concept
which allows you to bundle your scripts with all requirements into a
virtualenv.

Click is perfectly equipped to work with that and in fact the rest of the
documentation will assume that you are writing applications through
setuptools.

I strongly recommend to have a look at the [Setuptools
Integration](../setuptools/index#setuptools-integration) chapter before
reading the rest as the examples assume that you will be using setuptools.

# Setuptools Integration

When writing command line utilities, it’s recommended to write them as modules
that are distributed with setuptools instead of using Unix shebangs.

Why would you want to do that? There are a bunch of reasons:

  1. One of the problems with the traditional approach is that the first module the Python interpreter loads has an incorrect name. This might sound like a small issue but it has quite significant implications.

The first module is not called by its actual name, but the interpreter renames
it to `__main__`. While that is a perfectly valid name it means that if
another piece of code wants to import from that module it will trigger the
import a second time under its real name and all of a sudden your code is
imported twice.

  2. Not on all platforms are things that easy to execute. On Linux and OS X you can add a comment to the beginning of the file (`#!/usr/bin/env python`) and your script works like an executable (assuming it has the executable bit set). This however does not work on Windows. While on Windows you can associate interpreters with file extensions (like having everything ending in `.py` execute through the Python interpreter) you will then run into issues if you want to use the script in a virtualenv.

In fact running a script in a virtualenv is an issue with OS X and Linux as
well. With the traditional approach you need to have the whole virtualenv
activated so that the correct Python interpreter is used. Not very user
friendly.

  3. The main trick only works if the script is a Python module. If your application grows too large and you want to start using a package you will run into issues.

## Introduction

To bundle your script with setuptools, all you need is the script in a Python
package and a `setup.py` file.

Imagine this directory structure:

    
    
    yourscript.py
    setup.py
    

Contents of `yourscript.py`:

    
    
    import click
    
    @click.command()
    def cli():
        """Example script."""
        click.echo('Hello World!')
    

Contents of `setup.py`:

    
    
    from setuptools import setup
    
    setup(
        name='yourscript',
        version='0.1.0',
        py_modules=['yourscript'],
        install_requires=[
            'Click',
        ],
        entry_points={
            'console_scripts': [
                'yourscript = yourscript:cli',
            ],
        },
    )
    

The magic is in the `entry_points` parameter. Read the full
[entry_points](https://packaging.python.org/en/latest/specifications/entry-
points/) specification for more details. Below `console_scripts`, each line
identifies one console script. The first part before the equals sign (`=`) is
the name of the script that should be generated, the second part is the import
path followed by a colon (`:`) with the Click command.

That’s it.

## Testing The Script

To test the script, you can make a new virtualenv and then install your
package:

    
    
    $ python3 -m venv .venv
    $ . .venv/bin/activate
    $ pip install --editable .
    

Afterwards, your command should be available:

    
    
    $ yourscript
    Hello World!
    

## Scripts in Packages

If your script is growing and you want to switch over to your script being
contained in a Python package the changes necessary are minimal. Let’s assume
your directory structure changed to this:

    
    
    project/
        yourpackage/
            __init__.py
            main.py
            utils.py
            scripts/
                __init__.py
                yourscript.py
        setup.py
    

In this case instead of using `py_modules` in your `setup.py` file you can use
`packages` and the automatic package finding support of setuptools. In
addition to that it’s also recommended to include other package data.

These would be the modified contents of `setup.py`:

    
    
    from setuptools import setup, find_packages
    
    setup(
        name='yourpackage',
        version='0.1.0',
        packages=find_packages(),
        include_package_data=True,
        install_requires=[
            'Click',
        ],
        entry_points={
            'console_scripts': [
                'yourscript = yourpackage.scripts.yourscript:cli',
            ],
        },
    )
    

# Shell Completion

Click provides tab completion support for Bash (version 4.4 and up), Zsh, and
Fish. It is possible to add support for other shells too, and suggestions can
be customized at multiple levels.

Shell completion suggests command names, option names, and values for choice,
file, and path parameter types. Options are only listed if at least a dash has
been entered. Hidden commands and options are not shown.

    
    
    $ repo <TAB><TAB>
    clone  commit  copy  delete  setuser
    $ repo clone -<TAB><TAB>
    --deep  --help  --rev  --shallow  -r
    

## Enabling Completion

Completion is only available if a script is installed and invoked through an
entry point, not through the `python` command. See [Setuptools
Integration](../setuptools/index). Once the executable is installed, calling
it with a special environment variable will put Click in completion mode.

To enable shell completion, the user needs to register a special function with
their shell. The exact script varies depending on the shell you are using.
Click will output it when called with `_{FOO_BAR}_COMPLETE` set to
`{shell}_source`. `{FOO_BAR}` is the executable name in uppercase with dashes
replaced by underscores. It is conventional but not strictly required for
environment variable names to be in upper case. This convention helps
distinguish environment variables from regular shell variables and commands,
making scripts and configuration files more readable and easier to maintain.
The built-in shells are `bash`, `zsh`, and `fish`.

Provide your users with the following instructions customized to your program
name. This uses `foo-bar` as an example.

BashZshFish

Add this to `~/.bashrc`:

    
    
    eval "$(_FOO_BAR_COMPLETE=bash_source foo-bar)"
    

Add this to `~/.zshrc`:

    
    
    eval "$(_FOO_BAR_COMPLETE=zsh_source foo-bar)"
    

Add this to `~/.config/fish/completions/foo-bar.fish`:

    
    
    _FOO_BAR_COMPLETE=fish_source foo-bar | source
    

This is the same file used for the activation script method below. For Fish
it’s probably always easier to use that method.

Using `eval` means that the command is invoked and evaluated every time a
shell is started, which can delay shell responsiveness. To speed it up, write
the generated script to a file, then source that. You can generate the files
ahead of time and distribute them with your program to save your users a step.

BashZshFish

Save the script somewhere.

    
    
    _FOO_BAR_COMPLETE=bash_source foo-bar > ~/.foo-bar-complete.bash
    

Source the file in `~/.bashrc`.

    
    
    . ~/.foo-bar-complete.bash
    

Save the script somewhere.

    
    
    _FOO_BAR_COMPLETE=zsh_source foo-bar > ~/.foo-bar-complete.zsh
    

Source the file in `~/.zshrc`.

    
    
    . ~/.foo-bar-complete.zsh
    

Save the script to `~/.config/fish/completions/foo-bar.fish`:

    
    
    _FOO_BAR_COMPLETE=fish_source foo-bar > ~/.config/fish/completions/foo-bar.fish
    

After modifying the shell config, you need to start a new shell in order for
the changes to be loaded.

## Custom Type Completion

When creating a custom [`ParamType`](../api/index#click.ParamType
"click.ParamType"), override its
[`shell_complete()`](../api/index#click.ParamType.shell_complete
"click.ParamType.shell_complete") method to provide shell completion for
parameters with the type. The method must return a list of
[`CompletionItem`](../api/index#click.shell_completion.CompletionItem
"click.shell_completion.CompletionItem") objects. Besides the value, these
objects hold metadata that shell support might use. The built-in
implementations use `type` to indicate special handling for paths, and `help`
for shells that support showing a help string next to a suggestion.

In this example, the type will suggest environment variables that start with
the incomplete value.

    
    
    class EnvVarType(ParamType):
        name = "envvar"
    
        def shell_complete(self, ctx, param, incomplete):
            return [
                CompletionItem(name)
                for name in os.environ if name.startswith(incomplete)
            ]
    
    @click.command()
    @click.option("--ev", type=EnvVarType())
    def cli(ev):
        click.echo(os.environ[ev])
    

## Overriding Value Completion

Value completions for a parameter can be customized without a custom type by
providing a `shell_complete` function. The function is used instead of any
completion provided by the type. It is passed 3 keyword arguments:

  * `ctx` \- The current command context.
  * `param` \- The current parameter requesting completion.
  * `incomplete` \- The partial word that is being completed. May be an empty string if no characters have been entered yet.

It must return a list of
[`CompletionItem`](../api/index#click.shell_completion.CompletionItem
"click.shell_completion.CompletionItem") objects, or as a shortcut it can
return a list of strings.

In this example, the command will suggest environment variables that start
with the incomplete value.

    
    
    def complete_env_vars(ctx, param, incomplete):
        return [k for k in os.environ if k.startswith(incomplete)]
    
    @click.command()
    @click.argument("name", shell_complete=complete_env_vars)
    def cli(name):
        click.echo(f"Name: {name}")
        click.echo(f"Value: {os.environ[name]}")
    

## Adding Support for a Shell

Support can be added for shells that do not come built in. Be sure to check
PyPI to see if there’s already a package that adds support for your shell.
This topic is very technical, you’ll want to look at Click’s source to study
the built-in implementations.

Shell support is provided by subclasses of
[`ShellComplete`](../api/index#click.shell_completion.ShellComplete
"click.shell_completion.ShellComplete") registered with
[`add_completion_class()`](../api/index#click.shell_completion.add_completion_class
"click.shell_completion.add_completion_class"). When Click is invoked in
completion mode, it calls
[`source()`](../api/index#click.shell_completion.ShellComplete.source
"click.shell_completion.ShellComplete.source") to output the completion
script, or
[`complete()`](../api/index#click.shell_completion.ShellComplete.complete
"click.shell_completion.ShellComplete.complete") to output completions. The
base class provides default implementations that require implementing some
smaller parts.

First, you’ll need to figure out how your shell’s completion system works and
write a script to integrate it with Click. It must invoke your program with
the environment variable `_{FOO_BAR}_COMPLETE` set to `{shell}_complete` and
pass the complete args and incomplete value. How it passes those values, and
the format of the completion response from Click is up to you.

In your subclass, set
[`source_template`](../api/index#click.shell_completion.ShellComplete.source_template
"click.shell_completion.ShellComplete.source_template") to the completion
script. The default implementation will perform `%` formatting with the
following variables:

  * `complete_func` \- A safe name for the completion function defined in the script.
  * `complete_var` \- The environment variable name for passing the `{shell}_complete` instruction.
  * `foo_bar` \- The name of the executable being completed.

The example code is for a made up shell “My Shell” or “mysh” for short.

    
    
    from click.shell_completion import add_completion_class
    from click.shell_completion import ShellComplete
    
    _mysh_source = """\
    %(complete_func)s {
        response=$(%(complete_var)s=mysh_complete %(foo_bar)s)
        # parse response and set completions somehow
    }
    call-on-complete %(foo_bar)s %(complete_func)s
    """
    
    @add_completion_class
    class MyshComplete(ShellComplete):
        name = "mysh"
        source_template = _mysh_source
    

Next, implement
[`get_completion_args()`](../api/index#click.shell_completion.ShellComplete.get_completion_args
"click.shell_completion.ShellComplete.get_completion_args"). This must get,
parse, and return the complete args and incomplete value from the completion
script. For example, for the Bash implementation the `COMP_WORDS` env var
contains the command line args as a string, and the `COMP_CWORD` env var
contains the index of the incomplete arg. The method must return a `(args,
incomplete)` tuple.

    
    
    import os
    from click.parser import split_arg_string
    
    class MyshComplete(ShellComplete):
        ...
    
        def get_completion_args(self):
            args = split_arg_string(os.environ["COMP_WORDS"])
    
            if os.environ["COMP_PARTIAL"] == "1":
                incomplete = args.pop()
                return args, incomplete
    
            return args, ""
    

Finally, implement
[`format_completion()`](../api/index#click.shell_completion.ShellComplete.format_completion
"click.shell_completion.ShellComplete.format_completion"). This is called to
format each
[`CompletionItem`](../api/index#click.shell_completion.CompletionItem
"click.shell_completion.CompletionItem") into a string. For example, the Bash
implementation returns `f"{item.type},{item.value}` (it doesn’t support help
strings), and the Zsh implementation returns each part separated by a newline,
replacing empty help with a `_` placeholder. This format is entirely up to
what you parse with your completion script.

The `type` value is usually `plain`, but it can be another value that the
completion script can switch on. For example, `file` or `dir` can tell the
shell to handle path completion, since the shell is better at that than Click.

    
    
    class MyshComplete(ShellComplete):
        ...
    
        def format_completion(self, item):
            return f"{item.type}\t{item.value}"
    

With those three things implemented, the new shell support is ready. In case
those weren’t sufficient, there are more parts that can be overridden, but
that probably isn’t necessary.

The activation instructions will again depend on how your shell works. Use the
following to generate the completion script, then load it into the shell
somehow.

    
    
    _FOO_BAR_COMPLETE=mysh_source foo-bar
    

# Testing Click Applications

For basic testing, Click provides the `click.testing` module which provides
test functionality that helps you invoke command line applications and check
their behavior.

These tools should really only be used for testing as they change the entire
interpreter state for simplicity and are not in any way thread-safe!

## Basic Testing

The basic functionality for testing Click applications is the
[`CliRunner`](../api/index#click.testing.CliRunner "click.testing.CliRunner")
which can invoke commands as command line scripts. The
[`CliRunner.invoke()`](../api/index#click.testing.CliRunner.invoke
"click.testing.CliRunner.invoke") method runs the command line script in
isolation and captures the output as both bytes and binary data.

The return value is a [`Result`](../api/index#click.testing.Result
"click.testing.Result") object, which has the captured output data, exit code,
and optional exception attached:

hello.py

    
    
    import click
    
    @click.command()
    @click.argument('name')
    def hello(name):
       click.echo(f'Hello {name}!')
    

test_hello.py

    
    
    from click.testing import CliRunner
    from hello import hello
    
    def test_hello_world():
      runner = CliRunner()
      result = runner.invoke(hello, ['Peter'])
      assert result.exit_code == 0
      assert result.output == 'Hello Peter!\n'
    

For subcommand testing, a subcommand name must be specified in the `args`
parameter of
[`CliRunner.invoke()`](../api/index#click.testing.CliRunner.invoke
"click.testing.CliRunner.invoke") method:

sync.py

    
    
    import click
    
    @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')
    

test_sync.py

    
    
    from click.testing import CliRunner
    from sync import cli
    
    def test_sync():
      runner = CliRunner()
      result = runner.invoke(cli, ['--debug', 'sync'])
      assert result.exit_code == 0
      assert 'Debug mode is on' in result.output
      assert 'Syncing' in result.output
    

Additional keyword arguments passed to `.invoke()` will be used to construct
the initial Context object. For example, if you want to run your tests against
a fixed terminal width you can use the following:

    
    
    runner = CliRunner()
    result = runner.invoke(cli, ['--debug', 'sync'], terminal_width=60)
    

## File System Isolation

For basic command line tools with file system operations, the
[`CliRunner.isolated_filesystem()`](../api/index#click.testing.CliRunner.isolated_filesystem
"click.testing.CliRunner.isolated_filesystem") method is useful for setting
the current working directory to a new, empty folder.

cat.py

    
    
    import click
    
    @click.command()
    @click.argument('f', type=click.File())
    def cat(f):
       click.echo(f.read())
    

test_cat.py

    
    
    from click.testing import CliRunner
    from cat import cat
    
    def test_cat():
       runner = CliRunner()
       with runner.isolated_filesystem():
          with open('hello.txt', 'w') as f:
              f.write('Hello World!')
    
          result = runner.invoke(cat, ['hello.txt'])
          assert result.exit_code == 0
          assert result.output == 'Hello World!\n'
    

Pass `temp_dir` to control where the temporary directory is created. The
directory will not be removed by Click in this case. This is useful to
integrate with a framework like Pytest that manages temporary files.

    
    
    def test_keep_dir(tmp_path):
        runner = CliRunner()
    
        with runner.isolated_filesystem(temp_dir=tmp_path) as td:
            ...
    

## Input Streams

The test wrapper can also be used to provide input data for the input stream
(stdin). This is very useful for testing prompts, for instance:

prompt.py

    
    
    import click
    
    @click.command()
    @click.option('--foo', prompt=True)
    def prompt(foo):
       click.echo(f"foo={foo}")
    

test_prompt.py

    
    
    from click.testing import CliRunner
    from prompt import prompt
    
    def test_prompts():
       runner = CliRunner()
       result = runner.invoke(prompt, input='wau wau\n')
       assert not result.exception
       assert result.output == 'Foo: wau wau\nfoo=wau wau\n'
    

Note that prompts will be emulated so that they write the input data to the
output stream as well. If hidden input is expected then this obviously does
not happen.

# Unicode Support

Click has to take extra care to support Unicode text in different
environments.

  * The command line in Unix is traditionally bytes, not Unicode. While there are encoding hints, there are some situations where this can break. The most common one is SSH connections to machines with different locales.

Misconfigured environments can cause a wide range of Unicode problems due to
the lack of support for roundtripping surrogate escapes. This will not be
fixed in Click itself!

  * Standard input and output is opened in text mode by default. Click has to reopen the stream in binary mode in certain situations. Because there is no standard way to do this, it might not always work. Primarily this can become a problem when testing command-line applications.

This is not supported:

        
        sys.stdin = io.StringIO('Input here')
        sys.stdout = io.StringIO()
        

Instead you need to do this:

        
        input = 'Input here'
        in_stream = io.BytesIO(input.encode('utf-8'))
        sys.stdin = io.TextIOWrapper(in_stream, encoding='utf-8')
        out_stream = io.BytesIO()
        sys.stdout = io.TextIOWrapper(out_stream, encoding='utf-8')
        

Remember in that case, you need to use `out_stream.getvalue()` and not
`sys.stdout.getvalue()` if you want to access the buffer contents as the
wrapper will not forward that method.

  * `sys.stdin`, `sys.stdout` and `sys.stderr` are by default text-based. When Click needs a binary stream, it attempts to discover the underlying binary stream.
  * `sys.argv` is always text. This means that the native type for input values to the types in Click is Unicode, not bytes.

This causes problems if the terminal is incorrectly set and Python does not
figure out the encoding. In that case, the Unicode string will contain error
bytes encoded as surrogate escapes.

  * When dealing with files, Click will always use the Unicode file system API by using the operating system’s reported or guessed filesystem encoding. Surrogates are supported for filenames, so it should be possible to open files through the [`File`](../api/index#click.File "click.File") type even if the environment is misconfigured.

## Surrogate Handling

Click does all the Unicode handling in the standard library and is subject to
its behavior. Unicode requires extra care. The reason for this is that the
encoding detection is done in the interpreter, and on Linux and certain other
operating systems, its encoding handling is problematic.

The biggest source of frustration is that Click scripts invoked by init
systems, deployment tools, or cron jobs will refuse to work unless a Unicode
locale is exported.

If Click encounters such an environment it will prevent further execution to
force you to set a locale. This is done because Click cannot know about the
state of the system once it’s invoked and restore the values before Python’s
Unicode handling kicked in.

If you see something like this error:

    
    
    Traceback (most recent call last):
      ...
    RuntimeError: Click will abort further execution because Python was
      configured to use ASCII as encoding for the environment. Consult
      https://click.palletsprojects.com/unicode-support/ for mitigation
      steps.
    

You are dealing with an environment where Python thinks you are restricted to
ASCII data. The solution to these problems is different depending on which
locale your computer is running in.

For instance, if you have a German Linux machine, you can fix the problem by
exporting the locale to `de_DE.utf-8`:

    
    
    export LC_ALL=de_DE.utf-8
    export LANG=de_DE.utf-8
    

If you are on a US machine, `en_US.utf-8` is the encoding of choice. On some
newer Linux systems, you could also try `C.UTF-8` as the locale:

    
    
    export LC_ALL=C.UTF-8
    export LANG=C.UTF-8
    

On some systems it was reported that `UTF-8` has to be written as `UTF8` and
vice versa. To see which locales are supported you can invoke `locale -a`.

You need to export the values before you invoke your Python script.

In Python 3.7 and later you will no longer get a `RuntimeError` in many cases
thanks to [**PEP 538**](https://peps.python.org/pep-0538/) and [**PEP
540**](https://peps.python.org/pep-0540/), which changed the default
assumption in unconfigured environments. This doesn’t change the general issue
that your locale may be misconfigured.

# Upgrading To Newer Releases

Click attempts the highest level of backwards compatibility but sometimes this
is not entirely possible. In case we need to break backwards compatibility
this document gives you information about how to upgrade or handle backwards
compatibility properly.

## Upgrading to 7.0

Commands that take their name from the decorated function now replace
underscores with dashes. For example, the Python function `run_server` will
get the command name `run-server` now. There are a few options to address
this:

  * To continue with the new behavior, pin your dependency to `Click>=7` and update any documentation to use dashes.
  * To keep existing behavior, add an explicit command name with underscores, like `@click.command("run_server")`.
  * To try a name with dashes if the name with underscores was not found, pass a `token_normalize_func` to the context:
        
        def normalize(name):
            return name.replace("_", "-")
        
        @click.group(context_settings={"token_normalize_func": normalize})
        def group():
            ...
        
        @group.command()
        def run_server():
            ...
        

## Upgrading to 3.2

Click 3.2 had to perform two changes to multi commands which were triggered by
a change between Click 2 and Click 3 that had bigger consequences than
anticipated.

### Context Invokes

Click 3.2 contains a fix for the `Context.invoke()` function when used with
other commands. The original intention of this function was to invoke the
other command as as if it came from the command line when it was passed a
context object instead of a function. This use was only documented in a single
place in the documentation before and there was no proper explanation for the
method in the API documentation.

The core issue is that before 3.2 this call worked against intentions:

    
    
    ctx.invoke(other_command, 'arg1', 'arg2')
    

This was never intended to work as it does not allow Click to operate on the
parameters. Given that this pattern was never documented and ill intended the
decision was made to change this behavior in a bugfix release before it
spreads by accident and developers depend on it.

The correct invocation for the above command is the following:

    
    
    ctx.invoke(other_command, name_of_arg1='arg1', name_of_arg2='arg2')
    

This also allowed us to fix the issue that defaults were not handled properly
by this function.

### Multicommand Chaining API

Click 3 introduced multicommand chaining. This required a change in how Click
internally dispatches. Unfortunately this change was not correctly implemented
and it appeared that it was possible to provide an API that can inform the
super command about all the subcommands that will be invoked.

This assumption however does not work with one of the API guarantees that have
been given in the past. As such this functionality has been removed in 3.2 as
it was already broken. Instead the accidentally broken functionality of the
`Context.invoked_subcommand` attribute was restored.

If you do require the know which exact commands will be invoked there are
different ways to cope with this. The first one is to let the subcommands all
return functions and then to invoke the functions in a
`Context.result_callback()`.

## Upgrading to 2.0

Click 2.0 has one breaking change which is the signature for parameter
callbacks. Before 2.0, the callback was invoked with `(ctx, value)` whereas
now it’s `(ctx, param, value)`. This change was necessary as it otherwise made
reusing callbacks too complicated.

To ease the transition Click will still accept old callbacks. Starting with
Click 3.0 it will start to issue a warning to stderr to encourage you to
upgrade.

In case you want to support both Click 1.0 and Click 2.0, you can make a
simple decorator that adjusts the signatures:

    
    
    import click
    from functools import update_wrapper
    
    def compatcallback(f):
        # Click 1.0 does not have a version string stored, so we need to
        # use getattr here to be safe.
        if getattr(click, '__version__', '0.0') >= '2.0':
            return f
        return update_wrapper(lambda ctx, value: f(ctx, None, value), f)
    

With that helper you can then write something like this:

    
    
    @compatcallback
    def callback(ctx, param, value):
        return value.upper()
    

Note that because Click 1.0 did not pass a parameter, the `param` argument
here would be `None`, so a compatibility callback could not use that argument.

# Utilities

Besides the functionality that Click provides to interface with argument
parsing and handling, it also provides a bunch of addon functionality that is
useful for writing command line utilities.

## Printing to Stdout

The most obvious helper is the [`echo()`](../api/index#click.echo
"click.echo") function, which in many ways works like the Python `print`
statement or function. The main difference is that it works the same in many
different terminal environments.

Example:

    
    
    import click
    
    click.echo('Hello World!')
    

It can output both text and binary data. It will emit a trailing newline by
default, which needs to be suppressed by passing `nl=False`:

    
    
    click.echo(b'\xe2\x98\x83', nl=False)
    

Last but not least [`echo()`](../api/index#click.echo "click.echo") uses
click’s intelligent internal output streams to stdout and stderr which support
unicode output on the Windows console. This means for as long as you are using
`click.echo` you can output unicode characters (there are some limitations on
the default font with regards to which characters can be displayed).

Changelog

New in version 6.0.

Click emulates output streams on Windows to support unicode to the Windows
console through separate APIs. For more information see [Windows Console
Notes](../wincmd/index).

Changelog

New in version 3.0.

You can also easily print to standard error by passing `err=True`:

    
    
    click.echo('Hello World!', err=True)
    

## ANSI Colors

Changelog

New in version 2.0.

The [`echo()`](../api/index#click.echo "click.echo") function supports ANSI
colors and styles. On Windows this uses
[colorama](https://pypi.org/project/colorama/).

Primarily this means that:

  * Click’s [`echo()`](../api/index#click.echo "click.echo") function will automatically strip ANSI color codes if the stream is not connected to a terminal.
  * the [`echo()`](../api/index#click.echo "click.echo") function will transparently connect to the terminal on Windows and translate ANSI codes to terminal API calls. This means that colors will work on Windows the same way they do on other operating systems.

On Windows, Click uses colorama without calling `colorama.init()`. You can
still call that in your code, but it’s not required for Click.

For styling a string, the [`style()`](../api/index#click.style "click.style")
function can be used:

    
    
    import click
    
    click.echo(click.style('Hello World!', fg='green'))
    click.echo(click.style('Some more text', bg='blue', fg='white'))
    click.echo(click.style('ATTENTION', blink=True, bold=True))
    

The combination of [`echo()`](../api/index#click.echo "click.echo") and
[`style()`](../api/index#click.style "click.style") is also available in a
single function called [`secho()`](../api/index#click.secho "click.secho"):

    
    
    click.secho('Hello World!', fg='green')
    click.secho('Some more text', bg='blue', fg='white')
    click.secho('ATTENTION', blink=True, bold=True)
    

## Pager Support

In some situations, you might want to show long texts on the terminal and let
a user scroll through it. This can be achieved by using the
[`echo_via_pager()`](../api/index#click.echo_via_pager "click.echo_via_pager")
function which works similarly to the [`echo()`](../api/index#click.echo
"click.echo") function, but always writes to stdout and, if possible, through
a pager.

Example:

    
    
    @click.command()
    def less():
        click.echo_via_pager("\n".join(f"Line {idx}" for idx in range(200)))
    

If you want to use the pager for a lot of text, especially if generating
everything in advance would take a lot of time, you can pass a generator (or
generator function) instead of a string:

    
    
    def _generate_output():
        for idx in range(50000):
            yield f"Line {idx}\n"
    
    @click.command()
    def less():
        click.echo_via_pager(_generate_output())
    

## Screen Clearing

Changelog

New in version 2.0.

To clear the terminal screen, you can use the
[`clear()`](../api/index#click.clear "click.clear") function that is provided
starting with Click 2.0. It does what the name suggests: it clears the entire
visible screen in a platform-agnostic way:

    
    
    import click
    click.clear()
    

## Getting Characters from Terminal

Changelog

New in version 2.0.

Normally, when reading input from the terminal, you would read from standard
input. However, this is buffered input and will not show up until the line has
been terminated. In certain circumstances, you might not want to do that and
instead read individual characters as they are being written.

For this, Click provides the [`getchar()`](../api/index#click.getchar
"click.getchar") function which reads a single character from the terminal
buffer and returns it as a Unicode character.

Note that this function will always read from the terminal, even if stdin is
instead a pipe.

Example:

    
    
    import click
    
    click.echo('Continue? [yn] ', nl=False)
    c = click.getchar()
    click.echo()
    if c == 'y':
        click.echo('We will go on')
    elif c == 'n':
        click.echo('Abort!')
    else:
        click.echo('Invalid input :(')
    

Note that this reads raw input, which means that things like arrow keys will
show up in the platform’s native escape format. The only characters translated
are `^C` and `^D` which are converted into keyboard interrupts and end of file
exceptions respectively. This is done because otherwise, it’s too easy to
forget about that and to create scripts that cannot be properly exited.

## Waiting for Key Press

Changelog

New in version 2.0.

Sometimes, it’s useful to pause until the user presses any key on the
keyboard. This is especially useful on Windows where `cmd.exe` will close the
window at the end of the command execution by default, instead of waiting.

In click, this can be accomplished with the
[`pause()`](../api/index#click.pause "click.pause") function. This function
will print a quick message to the terminal (which can be customized) and wait
for the user to press a key. In addition to that, it will also become a NOP
(no operation instruction) if the script is not run interactively.

Example:

    
    
    import click
    click.pause()
    

## Launching Editors

Changelog

New in version 2.0.

Click supports launching editors automatically through
[`edit()`](../api/index#click.edit "click.edit"). This is very useful for
asking users for multi-line input. It will automatically open the user’s
defined editor or fall back to a sensible default. If the user closes the
editor without saving, the return value will be `None`, otherwise the entered
text.

Example usage:

    
    
    import click
    
    def get_commit_message():
        MARKER = '# Everything below is ignored\n'
        message = click.edit('\n\n' + MARKER)
        if message is not None:
            return message.split(MARKER, 1)[0].rstrip('\n')
    

Alternatively, the function can also be used to launch editors for files by a
specific filename. In this case, the return value is always `None`.

Example usage:

    
    
    import click
    click.edit(filename='/etc/passwd')
    

## Launching Applications

Changelog

New in version 2.0.

Click supports launching applications through
[`launch()`](../api/index#click.launch "click.launch"). This can be used to
open the default application associated with a URL or filetype. This can be
used to launch web browsers or picture viewers, for instance. In addition to
this, it can also launch the file manager and automatically select the
provided file.

Example usage:

    
    
    click.launch("https://click.palletsprojects.com/")
    click.launch("/my/downloaded/file.txt", locate=True)
    

## Printing Filenames

Because filenames might not be Unicode, formatting them can be a bit tricky.

The way this works with click is through the
[`format_filename()`](../api/index#click.format_filename
"click.format_filename") function. It does a best-effort conversion of the
filename to Unicode and will never fail. This makes it possible to use these
filenames in the context of a full Unicode string.

Example:

    
    
    click.echo(f"Path: {click.format_filename(b'foo.txt')}")
    

## Standard Streams

For command line utilities, it’s very important to get access to input and
output streams reliably. Python generally provides access to these streams
through `sys.stdout` and friends, but unfortunately, there are API differences
between 2.x and 3.x, especially with regards to how these streams respond to
Unicode and binary data.

Because of this, click provides the
[`get_binary_stream()`](../api/index#click.get_binary_stream
"click.get_binary_stream") and
[`get_text_stream()`](../api/index#click.get_text_stream
"click.get_text_stream") functions, which produce consistent results with
different Python versions and for a wide variety of terminal configurations.

The end result is that these functions will always return a functional stream
object (except in very odd cases; see [Unicode Support](../unicode-
support/index)).

Example:

    
    
    import click
    
    stdin_text = click.get_text_stream('stdin')
    stdout_binary = click.get_binary_stream('stdout')
    

Changelog

New in version 6.0.

Click now emulates output streams on Windows to support unicode to the Windows
console through separate APIs. For more information see [Windows Console
Notes](../wincmd/index).

## Intelligent File Opening

Changelog

New in version 3.0.

Starting with Click 3.0 the logic for opening files from the
[`File`](../api/index#click.File "click.File") type is exposed through the
[`open_file()`](../api/index#click.open_file "click.open_file") function. It
can intelligently open stdin/stdout as well as any other file.

Example:

    
    
    import click
    
    stdout = click.open_file('-', 'w')
    test_file = click.open_file('test.txt', 'w')
    

If stdin or stdout are returned, the return value is wrapped in a special file
where the context manager will prevent the closing of the file. This makes the
handling of standard streams transparent and you can always use it like this:

    
    
    with click.open_file(filename, 'w') as f:
        f.write('Hello World!\n')
    

## Finding Application Folders

Changelog

New in version 2.0.

Very often, you want to open a configuration file that belongs to your
application. However, different operating systems store these configuration
files in different locations depending on their standards. Click provides a
[`get_app_dir()`](../api/index#click.get_app_dir "click.get_app_dir") function
which returns the most appropriate location for per-user config files for your
application depending on the OS.

Example usage:

    
    
    import os
    import click
    import ConfigParser
    
    APP_NAME = 'My Application'
    
    def read_config():
        cfg = os.path.join(click.get_app_dir(APP_NAME), 'config.ini')
        parser = ConfigParser.RawConfigParser()
        parser.read([cfg])
        rv = {}
        for section in parser.sections():
            for key, value in parser.items(section):
                rv[f"{section}.{key}"] = value
        return rv
    

## Showing Progress Bars

Sometimes, you have command line scripts that need to process a lot of data,
but you want to quickly show the user some progress about how long that will
take. Click supports simple progress bar rendering for that through the
[`progressbar()`](../api/index#click.progressbar "click.progressbar")
function.

Note

If you find that you have requirements beyond what Click’s progress bar
supports, try using [tqdm](https://tqdm.github.io/).

The basic usage is very simple: the idea is that you have an iterable that you
want to operate on. For each item in the iterable it might take some time to
do processing. So say you have a loop like this:

    
    
    for user in all_the_users_to_process:
        modify_the_user(user)
    

To hook this up with an automatically updating progress bar, all you need to
do is to change the code to this:

    
    
    import click
    
    with click.progressbar(all_the_users_to_process) as bar:
        for user in bar:
            modify_the_user(user)
    

Click will then automatically print a progress bar to the terminal and
calculate the remaining time for you. The calculation of remaining time
requires that the iterable has a length. If it does not have a length but you
know the length, you can explicitly provide it:

    
    
    with click.progressbar(all_the_users_to_process,
                           length=number_of_users) as bar:
        for user in bar:
            modify_the_user(user)
    

Note that [`progressbar()`](../api/index#click.progressbar
"click.progressbar") updates the bar _after_ each iteration of the loop. So
code like this will render correctly:

    
    
    import time
    
    with click.progressbar([1, 2, 3]) as bar:
        for x in bar:
            print(f"sleep({x})...")
            time.sleep(x)
    

Another useful feature is to associate a label with the progress bar which
will be shown preceding the progress bar:

    
    
    with click.progressbar(all_the_users_to_process,
                           label='Modifying user accounts',
                           length=number_of_users) as bar:
        for user in bar:
            modify_the_user(user)
    

Sometimes, one may need to iterate over an external iterator, and advance the
progress bar irregularly. To do so, you need to specify the length (and no
iterable), and use the update method on the context return value instead of
iterating directly over it:

    
    
    with click.progressbar(length=total_size,
                           label='Unzipping archive') as bar:
        for archive in zip_file:
            archive.extract()
            bar.update(archive.size)
    

# Why Click?

There are so many libraries out there for writing command line utilities; why
does Click exist?

This question is easy to answer: because there is not a single command line
utility for Python out there which ticks the following boxes:

  * Is lazily composable without restrictions.
  * Supports implementation of Unix/POSIX command line conventions.
  * Supports loading values from environment variables out of the box.
  * Support for prompting of custom values.
  * Is fully nestable and composable.
  * Supports file handling out of the box.
  * Comes with useful common helpers (getting terminal dimensions, ANSI colors, fetching direct keyboard input, screen clearing, finding config paths, launching apps and editors, etc.).

There are many alternatives to Click; the obvious ones are `optparse` and
`argparse` from the standard library. Have a look to see if something else
resonates with you.

Click actually implements its own parsing of arguments and does not use
`optparse` or `argparse` following the `optparse` parsing behavior. The reason
it’s not based on `argparse` is that `argparse` does not allow proper nesting
of commands by design and has some deficiencies when it comes to POSIX
compliant argument handling.

Click is designed to be fun and customizable but not overly flexible. For
instance, the customizability of help pages is constrained. This constraint is
intentional because Click promises multiple Click instances will continue to
function as intended when strung together.

Too much customizability would break this promise.

Click was written to support the [Flask](https://palletsprojects.com/p/flask/)
microframework ecosystem because no tool could provide it with the
functionality it needed.

To get an understanding of what Click is all about, I strongly recommend
looking at the [Complex Applications](../complex/index#complex-guide) chapter.

## Why not Argparse?

Click is internally based on `optparse` instead of `argparse`. This is an
implementation detail that a user does not have to be concerned with. Click is
not based on `argparse` because it has some behaviors that make handling
arbitrary command line interfaces hard:

  * `argparse` has built-in behavior to guess if something is an argument or an option. This becomes a problem when dealing with incomplete command lines; the behaviour becomes unpredictable without full knowledge of a command line. This goes against Click’s ambitions of dispatching to subparsers.
  * `argparse` does not support disabling interspersed arguments. Without this feature, it’s not possible to safely implement Click’s nested parsing.

## Why not Docopt etc.?

Docopt, and many tools like it, are cool in how they work, but very few of
these tools deal with nesting of commands and composability in a way like
Click. To the best of the developer’s knowledge, Click is the first Python
library that aims to create a level of composability of applications that goes
beyond what the system itself supports.

Docopt, for instance, acts by parsing your help pages and then parsing
according to those rules. The side effect of this is that docopt is quite
rigid in how it handles the command line interface. The upside of docopt is
that it gives you strong control over your help page; the downside is that due
to this it cannot rewrap your output for the current terminal width, and it
makes translations hard. On top of that, docopt is restricted to basic
parsing. It does not handle argument dispatching and callback invocation or
types. This means there is a lot of code that needs to be written in addition
to the basic help page to handle the parsing results.

Most of all, however, it makes composability hard. While docopt does support
dispatching to subcommands, it, for instance, does not directly support any
kind of automatic subcommand enumeration based on what’s available or it does
not enforce subcommands to work in a consistent way.

This is fine, but it’s different from how Click wants to work. Click aims to
support fully composable command line user interfaces by doing the following:

  * Click does not just parse, it also dispatches to the appropriate code.
  * Click has a strong concept of an invocation context that allows subcommands to respond to data from the parent command.
  * Click has strong information available for all parameters and commands, so it can generate unified help pages for the full CLI and assist the user in converting the input data as necessary.
  * Click has a strong understanding of what types are, and it can give the user consistent error messages if something goes wrong. A subcommand written by a different developer will not suddenly die with a different error message because it’s manually handled.
  * Click has enough meta information available for its whole program to evolve over time and improve the user experience without forcing developers to adjust their programs. For instance, if Click decides to change how help pages are formatted, all Click programs will automatically benefit from this.

The aim of Click is to make composable systems. Whereas, the aim of docopt is
to build the most beautiful and hand-crafted command line interfaces. These
two goals conflict with one another in subtle ways. Click actively prevents
people from implementing certain patterns in order to achieve unified command
line interfaces. For instance, as a developer, you are given very little
choice in formatting your help pages.

## Why Hardcoded Behaviors?

The other question is why Click goes away from optparse and hardcodes certain
behaviors instead of staying configurable. There are multiple reasons for
this. The biggest one is that too much configurability makes it hard to
achieve a consistent command line experience.

The best example for this is optparse’s `callback` functionality for accepting
an arbitrary number of arguments. Due to syntactical ambiguities on the
command line, there is no way to implement fully variadic arguments. There are
always tradeoffs that need to be made and in case of `argparse` these
tradeoffs have been critical enough, that a system like Click cannot even be
implemented on top of it.

In this particular case, Click attempts to stay with a handful of accepted
paradigms for building command line interfaces that can be well documented and
tested.

## Why No Auto Correction?

The question came up why Click does not auto correct parameters given that
even optparse and `argparse` support automatic expansion of long arguments.
The reason for this is that it’s a liability for backwards compatibility. If
people start relying on automatically modified parameters and someone adds a
new parameter in the future, the script might stop working. These kinds of
problems are hard to find, so Click does not attempt to be magical about this.

This sort of behavior however can be implemented on a higher level to support
things such as explicit aliases. For more information see [Command
Aliases](../advanced/index#aliases).

# Windows Console Notes

Changelog

New in version 6.0.

Click emulates output streams on Windows to support unicode to the Windows
console through separate APIs and we perform different decoding of parameters.

Here is a brief overview of how this works and what it means to you.

## Unicode Arguments

Click internally is generally based on the concept that any argument can come
in as either byte string or unicode string and conversion is performed to the
type expected value as late as possible. This has some advantages as it allows
us to accept the data in the most appropriate form for the operating system
and Python version.

This caused some problems on Windows where initially the wrong encoding was
used and garbage ended up in your input data. We not only fixed the encoding
part, but we also now extract unicode parameters from `sys.argv`.

There is also another limitation with this: if `sys.argv` was modified prior
to invoking a click handler, we have to fall back to the regular byte input in
which case not all unicode values are available but only a subset of the
codepage used for parameters.

## Unicode Output and Input

Unicode output and input on Windows is implemented through the concept of a
dispatching text stream. What this means is that when click first needs a text
output (or input) stream on windows it goes through a few checks to figure out
of a windows console is connected or not. If no Windows console is present
then the text output stream is returned as such and the encoding for that
stream is set to `utf-8` like on all platforms.

However if a console is connected the stream will instead be emulated and use
the cmd.exe unicode APIs to output text information. In this case the stream
will also use `utf-16-le` as internal encoding. However there is some hackery
going on that the underlying raw IO buffer is still bypassing the unicode APIs
and byte output through an indirection is still possible.

  * This unicode support is limited to `click.echo`, `click.prompt` as well as `click.get_text_stream`.
  * Depending on if unicode values or byte strings are passed the control flow goes completely different places internally which can have some odd artifacts if data partially ends up being buffered. Click attempts to protect against that by manually always flushing but if you are mixing and matching different string types to `stdout` or `stderr` you will need to manually flush.
  * The raw output stream is set to binary mode, which is a global operation on Windows, so `print` calls will be affected. Prefer `click.echo` over `print`.
  * On Windows 7 and below, there is a limitation where at most 64k characters can be written in one call in binary mode. In this situation, `sys.stdout` and `sys.stderr` are replaced with wrappers that work around the limitation.

Another important thing to note is that the Windows console’s default fonts do
not support a lot of characters which means that you are mostly limited to
international letters but no emojis or special characters.