Help Pages — Click Documentation (8.2.x)

# Help Pages

Click makes it very easy to document your command line tools. For most things Click automatically generates help pages for you. By design the text is customizable, but the layout is not.

## Help Texts

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

Simple example:

    @click.command()
    @click.argument('name')
    @click.option('--count', default=1, help='number of greetings')
    def hello(name: str, count: int):
        """This script prints hello and a name one or more times."""
        for x in range(count):
            if name:
                click.echo(f"Hello {name}!")
            else:
                click.echo("Hello!")

    $ hello --help
    Usage: hello [OPTIONS] NAME

      This script prints hello and a name one or more times.

    Options:
      --count INTEGER  number of greetings
      --help           Show this message and exit.

## Command Short Help

For subcommands, a short help snippet is generated. By default, it’s the first sentence of the docstring. If too long, then it will ellipsize what cannot be fit on a single line with `...`. The short help snippet can also be overridden with `short_help`:

    @click.group()
    def cli():
        """A simple command line tool."""

    @cli.command('init', short_help='init the repo')
    def init():
        """Initializes the repository."""

    $ cli --help
    Usage: cli [OPTIONS] COMMAND [ARGS]...

      A simple command line tool.

    Options:
      --help  Show this message and exit.

    Commands:
      init  init the repo

## Command Epilog Help

The help epilog is printed at the end of the help and is useful for showing example command usages or referencing additional help resources.

    @click.command(
        epilog='See https://example.com for more details',
        )
    def init():
        """Initializes the repository."""

    $ init --help
    Usage: init [OPTIONS]

      Initializes the repository.

    Options:
      --help  Show this message and exit.

      See https://example.com for more details

## Documenting Arguments

`click.argument` does not take a `help` parameter. This follows the Unix Command Line Tools convention of using arguments only for necessary things and documenting them in the command help text by name. This should then be done via the docstring.

A brief example:

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

    $ touch --help
    Usage: touch [OPTIONS] FILENAME

      Print FILENAME.

    Options:
      --help  Show this message and exit.

Or more explicitly:

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

        FILENAME is the name of the file to check.
        """
        click.echo(filename)

    $ touch --help
    Usage: touch [OPTIONS] FILENAME

      Print FILENAME.

      FILENAME is the name of the file to check.

    Options:
      --help  Show this message and exit.

## Showing Defaults

To control the appearance of defaults pass `show_default`.

    @click.command()
    @click.option('--n', default=1, show_default=False, help='number of dots')
    def dots(n):
        click.echo('.' * n)

    $ dots --help
    Usage: dots [OPTIONS]

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

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

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

## Click’s Wrapping Behavior

Click’s default wrapping ignores single new lines and rewraps the text based on the width of the terminal, to a maximum of 80 characters. In the example notice how the second grouping of three lines is rewrapped into a single paragraph.

    @click.command()
    def cli():
        """
        This is a very long 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
        that is compacted.
        """

    $ cli --help
    Usage: cli [OPTIONS]

      This is a very long 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 that is compacted.

    Options:
      --help  Show this message and exit.

## Escaping Click’s Wrapping

Sometimes Click’s wrapping can be a problem, such as when showing code examples where newlines are significant. This behavior can be escaped on a per-paragraph basis by adding a line with only `\b` . The `\b` is removed from the rendered help text.

Example:

    @click.command()
    def cli():
        """First paragraph.

        \b
        This is
        a paragraph
        without rewrapping.

        And this is a paragraph
        that will be rewrapped again.
        """

    $ cli --help
    Usage: cli [OPTIONS]

      First paragraph.

      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 rendering maximum width, pass `max_content_width` when calling the command.

    cli(max_content_width=120)

## Truncating Help Texts

Click gets `Command` help text from the docstring. If you do not want to include part of the docstring, add the `\f` escape marker to have Click truncate the help text after the marker.

Example:

    @click.command()
    def cli():
        """First paragraph.
        \f

        Words to not be included.
        """

    $ cli --help
    Usage: cli [OPTIONS]

      First paragraph.

    Options:
      --help  Show this message and exit.

## Placeholder / Meta Variable

The default placeholder variable (meta variable) in the help pages is the parameter name in uppercase with underscores. This can be changed for Commands and Parameters with the `options_metavar` and `metavar` kwargs.

    # This controls entry on the usage line.
    @click.command(options_metavar='[[options]]')
    @click.option('--count', default=1, help='number of greetings',
                  metavar='<int>')
    @click.argument('name', metavar='<name>')
    def hello(name: str, count: int) -> None:
        """This script prints 'hello <name>' a total of <count> times."""
        for x in range(count):
            click.echo(f"Hello {name}!")

Example:

    $ hello --help
    Usage: hello [[options]] <name>

      This script prints 'hello <name>' a total of <count> times.

    Options:
      --count <int>  number of greetings
      --help         Show this message and exit.

## Help Parameter Customization

Help parameters are automatically added by Click for any command. The default is `--help` but can be override by the context setting `help_option_names`. Click also performs automatic conflict resolution on the default help parameter so if a command itself implements a parameter named `help` then the default help will not be run.

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

    $ cli -h
    Usage: cli [OPTIONS]

    Options:
      -h, --help  Show this message and exit.