rich-click

rich-click is a drop-in wrapper around Click, the popular Python CLI toolkit, that renders help text and error messages using the Rich terminal-formatting library. Instead of Click’s plain-text help output, commands get colorized headers, grouped option panels, tables, and styled usage strings with almost no code changes required.

Beyond the import-swap usage (import rich_click as click), the project ships a standalone rich-click CLI tool that can richify the help output of any third-party Click or Typer-based command, plus over 100 built-in themes, HTML/SVG export of help text, and IDE-friendly type stubs for Click’s decorators.

What You Get

• Drop-in replacement for click — just import rich_click as click in existing code
• RichCommand/RichGroup classes for declarative use alongside unmodified Click
• Over 100 built-in color themes, selectable via RICH_CLICK_THEME env var
• Named panels for grouping commands and options in help output
• Standalone rich-click CLI to reformat help output of any other Click/Typer tool
• HTML and SVG export of rendered help text for docs and READMEs
• Type-stubbed decorators (.pyi files) for IDE autocomplete

Common Use Cases

• Polishing help/usage output for internal or open-source Python CLI tools
• Adding themeable, branded terminal output to a Click-based developer tool
• Generating HTML/SVG screenshots of CLI help text for documentation sites
• Reformatting a third-party CLI’s help output on the fly via the rich-click wrapper command

Under The Hood

Architecture - rich-click subclasses Click’s core primitives (RichCommand, RichGroup, RichContext) and overrides their help/error-formatting methods, routing output through a RichHelpFormatter that renders panels, tables, and styled text via the Rich library instead of Click’s plain-text writer; the patch.py module lets the import rich_click as click style monkey-patch Click’s own classes so existing code needs no structural changes, while cli.py implements the standalone wrapper command that intercepts and reformats another program’s Click output. Tech Stack - a pure-Python package (src/rich_click/) built on click>=8 and rich>=12, with typing-extensions for older Python versions and colorama pulled in only on Windows; packaging uses setuptools with dynamic versioning, and the dev/docs extras pull in mypy, ruff, pytest, and an mkdocs-material documentation site. Code Quality - the tests/ directory (nearly 1,800 lines across nine files) covers theme rendering, config precedence, exit codes, deprecation warnings, and a dedicated test_no_rich_imports.py guarding against accidental hard dependencies leaking into Click-only code paths; the package ships py.typed and .pyi stub files for IDE autocomplete, and CI runs lint/type-check/coverage workflows shown in the README badges. API Design - the library’s central design goal is zero-friction adoption: swapping one import line preserves an existing Click CLI’s behavior while unlocking rich formatting, and the declarative RichCommand/RichGroup path lets teams opt in incrementally without touching unrelated code, which keeps the public surface small and closely mirrored to Click’s own API.