CLI Options with Help

In the First Steps section you saw how to add help for a CLI app/command by adding it to a function's docstring.

Here's how that last example looked like:

import typer


def main(name: str, lastname: str = "", formal: bool = False):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        typer.echo(f"Good day Ms. {name} {lastname}.")
    else:
        typer.echo(f"Hello {name} {lastname}")


if __name__ == "__main__":
    typer.run(main)

Now we'll add a help section to the CLI options:

import typer


def main(
    name: str,
    lastname: str = typer.Option("", help="Last name of person to greet."),
    formal: bool = typer.Option(False, help="Say hi formally."),
):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        typer.echo(f"Good day Ms. {name} {lastname}.")
    else:
        typer.echo(f"Hello {name} {lastname}")


if __name__ == "__main__":
    typer.run(main)

We are replacing the default values we had before with typer.Option().

As we no longer have a default value there, the first parameter to typer.Option() serves the same purpose of defining that default value.

So, if we had:

lastname: str = ""

now we write:

lastname: str = typer.Option("")

And both forms achieve the same: a CLI option with a default value of an empty string ("").

And then we can pass the help keyword parameter:

lastname: str = typer.Option("", help="this option does this and that")

to create the help for that CLI option.

Copy that example from above to a file main.py.

Test it:

$ python main.py --help

Usage: main.py [OPTIONS] NAME

  Say hi to NAME, optionally with a --lastname.

  If --formal is used, say hi very formally.

Options:
  --lastname TEXT         Last name of person to greet.
  --formal / --no-formal  Say hi formally.
  --install-completion    Install completion for the current shell.
  --show-completion       Show completion for the current shell, to copy it or customize the installation.
  --help                  Show this message and exit.

// Now you have a help text for the --lastname and --formal CLI options 🎉

Show default in help

You can tell Typer to show the default value in the help text with show_default=True:

import typer


def main(fullname: str = typer.Option("Wade Wilson", show_default=True)):
    typer.echo(f"Hello {fullname}")


if __name__ == "__main__":
    typer.run(main)

And it will show up in the help text:

$ python main.py

Hello Wade Wilson

// Show the help
$ python main.py --help

Usage: main.py [OPTIONS]

Options:
  --fullname TEXT       [default: Wade Wilson]
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  --help                Show this message and exit.

Tip

Notice the [default: Wade Wilson] in the help text.