Help and Rich Formatting

Typer integrates deeply with the Rich library to provide visually appealing terminal output. This integration allows for formatted help text, organized command panels, and enhanced error reporting.

Basic Help Customization

The primary way to provide information to users is through help strings. In typer.main.Typer, help text can be defined at the application, command, or callback level using the help, short_help, and epilog parameters.

• help: The main description of the command or application.
• short_help: A concise version used in summary tables (e.g., when listing subcommands). If omitted, Typer derives it from the first line of the help text.
• epilog: Additional text displayed at the very bottom of the help output, useful for examples or copyright notices.

import typer

app = typer.Typer(
    help="A management tool for the system.",
    epilog="For more information, visit https://example.com"
)

@app.command(short_help="Create a user")
def create(username: str):
    """
    Create a new user in the system with the provided username.
    This command will initialize the home directory and default permissions.
    """
    print(f"Creating user: {username}")

Rich Markup and Markdown

Typer can render help text using Rich's markup or standard Markdown. This is controlled by the rich_markup_mode parameter in the Typer constructor. It supports three modes: "rich", "markdown", and None.

By default, Typer uses "rich" if the Rich library is installed.

Using Rich Markup

When rich_markup_mode="rich", you can use Rich's tag-based syntax (e.g., [bold red]text[/bold red]) directly in your docstrings or help parameters.

import typer

# Example based on tests/test_rich_markup_mode.py
app = typer.Typer(rich_markup_mode="rich")

@app.command()
def main(arg: str):
    """
    Main function with [bold red]Rich markup[/bold red].
    """
    print(f"Hello {arg}")

Using Markdown

Setting rich_markup_mode="markdown" allows you to use standard Markdown syntax. Typer will render headers, lists, and code blocks using Rich's Markdown capabilities.

Note that Markdown rendering handles newlines differently than plain text. As seen in tests/test_rich_markup_mode.py, single newlines in Markdown may be collapsed, while double newlines create paragraph breaks.

Organizing Help with Panels

For complex CLIs with many subcommands, you can group related items into "panels" using the rich_help_panel parameter. This creates a titled box around the grouped items in the help output.

This parameter is available in Typer.__init__, @app.command(), and app.add_typer().

import typer

# Example based on docs_src/commands/help/tutorial006_py310.py
app = typer.Typer()

@app.command(rich_help_panel="Utils and Configs")
def config(configuration: str):
    """Configure the system."""
    pass

@app.command(rich_help_panel="Help and Others")
def report():
    """Report an issue."""
    pass

In the resulting help output, config and report will appear in separate sections titled "Utils and Configs" and "Help and Others" respectively, rather than the default "Commands" section.

Pretty Exceptions

Typer leverages Rich to provide "pretty" exceptions that are easier to read than standard Python tracebacks. These are enabled by default if Rich is installed.

You can configure this behavior using several parameters in the Typer class:

• pretty_exceptions_enable: Set to False to revert to standard Python tracebacks.
• pretty_exceptions_show_locals: When True, the traceback will include the values of local variables for each frame, which is highly useful for debugging but should be used cautiously if your code handles sensitive data.
• pretty_exceptions_short: Defaults to True. It hides internal Typer and Click stack frames to focus on your application code.

import typer

app = typer.Typer(
    pretty_exceptions_enable=True,
    pretty_exceptions_show_locals=True,
    pretty_exceptions_short=False  # Show full trace including internal frames
)

Formatting Gotchas

• Text Wrapping: Typer/Click normally rewraps help text. To prevent this in plain text mode, developers often use the \b escape character at the start of a paragraph. However, when using Rich markup or Markdown, Rich handles the layout, and these escape characters are typically stripped or ignored.
• Markdown Lists: As noted in tests/test_rich_markup_mode.py, certain Markdown list styles (like single-newline bullets) might require specific spacing to render correctly in the terminal environment.
• Missing Rich: If the Rich library is not installed, Typer gracefully falls back to standard plain-text help output, ignoring markup tags and panel configurations. The rich_markup_mode defaults to None in this scenario.