Visuals and Help Formatting

You can customize the visual output of your CLI help pages and error messages by leveraging the built-in Rich integration. This allows for syntax highlighting, Markdown support, and organized help panels.

Enable Rich Help and Markup

By default, if the rich package is installed, this project uses it to format help pages with rich_markup_mode="rich". You can explicitly control the markup mode (Rich markup or Markdown) using the rich_markup_mode parameter in the typer.Typer constructor.

import typer

# Enable Markdown support in help docstrings
app = typer.Typer(rich_markup_mode="markdown")

@app.command()
def main(name: str):
    """
    Say hello to **NAME**.
    
    This docstring uses *Markdown* formatting.
    """
    print(f"Hello {name}")

if __name__ == "__main__":
    app()

To use Rich's own markup language instead of Markdown, set rich_markup_mode="rich":

app = typer.Typer(rich_markup_mode="rich")

@app.command()
def main():
    """
    Help with [bold]Rich[/bold] markup and [red]colors[/red].
    """
    pass

Group Options and Commands into Panels

You can organize your help page by grouping related options or subcommands into named panels using the rich_help_panel argument. This is supported in typer.Typer(), @app.command(), typer.Option(), and typer.Argument().

import typer

app = typer.Typer()

@app.command()
def create(
    username: str = typer.Option(..., rich_help_panel="User Credentials"),
    password: str = typer.Option(..., rich_help_panel="User Credentials"),
    force: bool = typer.Option(False, rich_help_panel="Advanced Options"),
):
    """Create a new user."""
    pass

@app.command(rich_help_panel="System Utilities")
def config():
    """Configure the system."""
    pass

Prevent Text Rewrapping

By default, the help formatter in typer/rich_utils.py strips single newlines and rewraps text to fit the terminal width. To preserve your manual line breaks and formatting, start a paragraph with the \b escape character in your docstring.

import typer

app = typer.Typer(rich_markup_mode="markdown")

@app.command()
def main():
    """
    \b
    This text will not be rewrapped.
    It preserves the manual
    line breaks
    exactly as written.
    """
    print("Hello World")

Configure Pretty Exceptions

When an error occurs, this project can print a "pretty" traceback using Rich. You can configure the level of detail or disable it entirely in the typer.Typer constructor.

import typer

app = typer.Typer(
    pretty_exceptions_enable=True,
    pretty_exceptions_show_locals=True,  # Include local variable values in tracebacks
    pretty_exceptions_short=True,        # Hide internal library frames (Typer/Click)
)

@app.command()
def error():
    x = 10
    raise ValueError("Something went wrong")

if __name__ == "__main__":
    app()

Customizing Default Styles

The visual theme is defined by several constants in typer/rich_utils.py. While these are internal, they dictate the default colors used for different elements:

• STYLE_OPTION: "bold cyan" (for options like --name)
• STYLE_SWITCH: "bold green" (for flags)
• STYLE_METAVAR: "bold yellow" (for placeholders like <text>)
• STYLE_USAGE: "yellow" (for the "Usage:" prefix)
• STYLE_ERRORS_PANEL_BORDER: "red" (for error message boxes)

Troubleshooting and Configuration

• Rich not working: Ensure the rich package is installed. If it is missing, the CLI will fall back to standard Click formatting.
• Environment Variables:
  • TYPER_USE_RICH: Set to 0 or False to disable Rich formatting globally.
  • TYPER_STANDARD_TRACEBACK: Set to 1 to disable pretty exceptions and use standard Python tracebacks.
  • TERMINAL_WIDTH: Override the detected terminal width for Rich output.
  • _TYPER_FORCE_DISABLE_TERMINAL: Set to 1 to force disable Rich terminal output (useful for logs).