Options — Click Documentation (8.3.x)

# Options

Adding options to commands can be accomplished with the `option()` decorator. At runtime the decorator invokes the `Option` class. Options in Click are distinct from positional arguments.

Useful and often used kwargs are:

- `default`: Passes a default.

- `help`: Sets help message.

- `nargs`: Sets the number of arguments.

- `required`: Makes option required.

- `type`: Sets parameter type

## Option Decorator

The `option()` decorator is usually passed two positional arguments: the option name and the decorated function argument name.

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

    $ echo --help
    Usage: echo [OPTIONS]

    Options:
      --string-to-echo TEXT
      --help                 Show this message and exit.

However, if the decorated function argument name is not passed in, then Click will try to infer it. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes.

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

    $ echo --string-to-echo 'Hi!'
    Hi!

More formally, Click will try to infer the decorated function argument name as follows:

1. If a positional argument is a valid Python identifier (and thus does not have dashes), it is chosen.

2. If multiple positional arguments are prefixed with `--`, the first one declared is chosen.

3. Otherwise, the first positional argument prefixed with `-` is chosen.

To get the argument name, the chosen positional argument is converted to lower case, a leading `-` or `--` is removed if found, and any remaining `-` characters are replaced with `_`.

Examples
Decorator Arguments | Inferred Argument Name
--- | ---
`"-f", "--foo-bar"` | foo_bar
`"-x"` | x
`"-f", "--filename", "dest"` | dest
`"--CamelCase"` | camelcase
`"-f", "-fb"` | f
`"--f", "--foo-bar"` | f
`"---f"` | _f

## Basic Example

A simple `click.Option` takes one option name. By default, it’s assumed that the decorated function argument is not required and the expected type is `str`. If the decorated function takes a positional argument but the option is not passed with the command, then `None` is passed.

    @click.command()
    @click.option('--text')
    def print_this(text):
        click.echo(text)

    $ print-this --text=this
    this
    $ print-this

    $ print-this --help
    Usage: print-this [OPTIONS]

    Options:
      --text TEXT
      --help       Show this message and exit.

## Setting a Default

Instead of setting the `type`, you may set a default and Click will try to infer the type.

    @click.command()
    @click.option('--n', default=1)
    def dots(n):
        click.echo('.' * n)

    $ dots --help
    Usage: dots [OPTIONS]

    Options:
      --n INTEGER
      --help       Show this message and exit.

## Multi Value Options

To make an option take multiple values, pass in `nargs`. Note you may pass in any positive integer, but not -1. The values are passed to the decorated function as a tuple.

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

    $ findme --pos 2.0 3.0
    2.0 / 3.0

## Multi Value Options as Tuples

Changelog

Added in version 4.0.

By setting `nargs` to a specific number, each item in the resulting tuple is of the same type. Alternatively, 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 the `type`, `nargs` gets automatically set to the length of the tuple and the `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

The multiple options format allows options to take an arbitrary number of arguments (which is called variadic). The arguments are passed to the decorated function as a tuple. If set, `default` must be a list or tuple. Setting a string as `default` will be interpreted as a list of characters.

    @click.command()
    @click.option('--message', '-m', multiple=True)
    def commit(message):
        click.echo(message)
        for m in message:
            click.echo(m)

    $ commit -m foo -m bar -m here
    ('foo', 'bar', 'here')
    foo
    bar
    here

## Counting

To count the occurrence of an option, set `count=True`. If the option is not passed on the command line, then the count is 0. Counting is commonly used for verbosity.

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

    $ log
    Verbosity: 0
    $ log -vvv
    Verbosity: 3

## Boolean

Boolean options (boolean flags) take the values `True` or `False`. The simplest case sets the default value to `False` if the flag is not passed, and `True` if it is.

    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)

    $ info
    win32
    $ info --shout
    WIN32!!!!111

To implement this more explicitly, declare `--{on-option}/--{off-option}`. Click will automatically set `is_flag=True`.

    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)

    $ info
    win32
    $ info --shout
    WIN32!!!!111
    $ info --no-shout
    win32

Use cases for this more explicit pattern include:

- The default can be dynamic so the user can explicitly specify the option with either on or off option, or pass in no option to use the dynamic default.

- Shell scripts sometimes want to be explicit even when it’s the default

- Shell aliases can set a flag, then an invocation can add a negation of the flag

If a forward slash(`/`) is contained in your option name already, you can split the parameters using `;`. In Windows `/` is commonly used as the prefix character.

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

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.

    import sys

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

    $ info --help
    Usage: info [OPTIONS]

    Options:
      --shout / -N, --no-shout
      --help                    Show this message and exit.

## Flag Value

To have a flag pass a value to the decorated function set `flag_value`. This automatically sets `is_flag=True`. To mark the flag as default, set `default=True`. Setting flag values can be used to create patterns like this:

    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)())

    $ info --help
    Usage: info [OPTIONS]

    Options:
      --upper
      --lower
      --help   Show this message and exit.
    $ info --upper
    WIN32
    $ info --lower
    win32
    $ info
    WIN32

Note

The `default` value is given to the decorated function as-is. So if you set `default=None`, the value passed to the function is the `None` Python value. Same for any other type.

But there is a special case for flags. If a flag has a `flag_value`, then setting `default=True` is interpreted as the flag should be activated by default. So instead of the decorated function receiving the `True` Python value, it will receive the `flag_value`.

Which means, in example above, this option:

    @click.option('--upper', 'transformation', flag_value='upper', default=True)

is equivalent to:

    @click.option('--upper', 'transformation', flag_value='upper', default='upper')

Because the two are equivalent, it is recommended to always set `default` to the actual value you want to pass and avoid using the special `True` case. This makes the code more explicit and predictable.

## Values from Environment Variables

To pass in a value from a specific environment variable use `envvar`.

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

    $ export USERNAME=john
    $ greet
    Hello john!

If a list is passed to `envvar`, the first environment variable found is picked.

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

    $ export ALT_USERNAME=Bill
    $ export USERNAME=john
    $ greet
    Hello Bill!

Variable names are:

- Case-insensitive on Windows but not on other platforms.

- Not stripped of whitespace and should match the exact name provided to the `envvar` argument.

For flag options, there are two concepts to consider: the activation of the flag driven by the environment variable, and the value of the flag if it is activated.

The values read from environment variables are always strings and will require extra processing. We need to transform these strings into boolean values that will determine if the flag is activated or not.

Here are the rules used to parse environment variable values for flag options:

- `true`, `1`, `yes`, `on`, `t`, `y` are interpreted as activating the flag

- `false`, `0`, `no`, `off`, `f`, `n` are interpreted as deactivating the flag

- The presence of the environment variable without value is interpreted as deactivating the flag

- Empty strings are interpreted as deactivating the flag

- Values are case-insensitive, so the `True`, `TRUE`, `tRuE` strings are all interpreted as activating the flag

- Values are stripped of leading and trailing whitespace before being interpreted, so the `" True "` string is transformed to `"true"` and thus activates the flag

- If the flag option has a `flag_value` argument, passing that value in the environment variable will activate the flag, in addition to all the cases described above

- Any other value is interpreted as deactivating the flag

Caution

For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.

So an option defined as `--flag\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.

If the flag is activated, its value is set to `flag_value`. Otherwise, the value defaults to `None`.

## Multiple Options from Environment Values

As options can accept multiple values, pulling in such values from environment variables (which are strings) is a bit more complex. Click handles this by deferring customization of the behavior to the `type`. For both `multiple` and `nargs` with values other than `1`, Click will invoke the `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` and `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 on every colon (`:`), and for Windows, splitting on every semicolon (`;`).

    @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()

    $ export PATHS='./foo/bar;./test'
    $ perform
    ./foo/bar
    ./test

## Other Prefix Characters

Click can deal with prefix characters besides `-` for options, including `/` and `+`, as well as others. Note that alternative prefix characters are generally used very sparingly if at all within POSIX.

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

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

There are special considerations for using `/` as prefix character. See Boolean for more.

## 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 value will be `flag_value`.

    @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!