Colored help¶
Click Extra extends Cloup’s help formatter and theme to automatically colorize every element of the help screen: options, choices, metavars, arguments, CLI and subcommand names, aliases, environment variables, defaults, ranges, and required labels.
Cross-reference highlighting¶
Option names are highlighted wherever they appear in the help screen, not only in the synopsis column. If an option name shows up in another option’s description or in the command’s docstring, it gets the same styling. This turns plain-text references into visual links, making it easier to scan for related options.
from click_extra import Choice, command, option, echo
@command
@option("--format", type=Choice(["json", "csv"]), help="Output format.")
@option("--output", help="Write to file instead of stdout.")
@option(
"--dry-run",
is_flag=True,
help="Preview what would be written to --output without --format validation.",
)
def export(format, output, dry_run):
"""Export data.
Combine --format and --output to write directly to a file.
Use --dry-run to preview without side effects.
"""
echo("Exporting...")
$ export --help
Usage: export [OPTIONS]
Export data.
Combine --format and --output to write directly to a file. Use --dry-run to
preview without side effects.
Options:
--format [json|csv] Output format.
--output TEXT Write to file instead of stdout.
--dry-run Preview what would be written to --output without
--format validation.
--time / --no-time Measure and print elapsed execution time. [default:
no-time]
--color, --ansi / --no-color, --no-ansi
Strip out all colors and all ANSI codes from output.
[default: color]
--config CONFIG_PATH Location of the configuration file. Supports local
path with glob patterns or remote URL. [default: ~/.c
onfig/export/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jso
nc,*.hjson,*.ini,*.xml,pyproject.toml}]
--no-config Ignore all configuration files and only use command
line parameters and environment variables.
--validate-config FILE Validate the configuration file and exit.
--show-params Show all CLI parameters, their provenance, defaults
and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one level
for each additional repetition of the option.
[default: 0]
--version Show the version and exit.
-h, --help Show this message and exit.
The same applies to choices (highlighted in the metavar list and in any description that references them), arguments, and subcommand names.
Disabling cross-reference highlighting¶
If the free-text matching produces false positives (option names or choices that coincide with common words), disable it via the theme:
from click_extra import HelpExtraTheme, group
safe_theme = HelpExtraTheme.dark().with_(cross_ref_highlight=False)
@group(context_settings={"formatter_settings": {"theme": safe_theme}})
def cli(): ...
With cross_ref_highlight=False, only structural elements are styled: bracket fields ([default: ...], [env var: ...], ranges, [required]), deprecated messages, and subcommand names in definition lists. Option names, choices, arguments, metavars, and CLI names in descriptions and docstrings are left unstyled.
Bracket fields¶
Trailing metadata brackets ([default: ...], [env var: ...], [required], and range expressions) each get their own style. All four fields can appear together:
from click_extra import command, option, IntRange
@command
@option(
"--threshold",
type=IntRange(1, 100),
default=50,
required=True,
show_default=True,
envvar="THRESHOLD",
show_envvar=True,
help="Sensitivity level.",
)
def analyze(threshold):
"""Run analysis."""
$ analyze --help
Usage: analyze [OPTIONS]
Run analysis.
Options:
--threshold INTEGER RANGE Sensitivity level. [env var: THRESHOLD,
ANALYZE_THRESHOLD; default: 50; 1<=x<=100;
required]
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--color, --ansi / --no-color, --no-ansi
Strip out all colors and all ANSI codes from
output. [default: color]
--config CONFIG_PATH Location of the configuration file. Supports local
path with glob patterns or remote URL. [default: ~
/.config/analyze/{*.toml,*.yaml,*.yml,*.json,*.json
5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}]
--no-config Ignore all configuration files and only use command
line parameters and environment variables.
--validate-config FILE Validate the configuration file and exit.
--show-params Show all CLI parameters, their provenance, defaults
and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one level
for each additional repetition of the option.
[default: 0]
--version Show the version and exit.
-h, --help Show this message and exit.
Note
When choices are Enum members, Click Extra colorizes their name attribute (not their value), matching Click’s own behavior. Use EnumChoice if you need user-friendly choice strings based on values or custom representations.
Why not use rich-click?¶
rich-click is a good project that aims to integrate Rich with Click. Like Click Extra, it provides a ready-to-use help formatter for Click.
But contrary to Click Extra, the help screen is rendered within a table, which takes the whole width of the terminal. This is not ideal if you try to print the output of a command somewhere else.
The typical use-case is users reporting issues on GitHub, and pasting the output of a command in the issue description. If the output is too wide, it will be akwardly wrapped, or adds a horizontal scrollbar to the page.
Without a table imposing a maximal width, the help screens from Click Extra will be rendered with the minimal width of the text, and will be more readable.
Hint
This is just a matter of preference, as nothing prevents you to use both rich-click and Click Extra in the same project, and get the best from both.
--color/--no-color flag¶
Click Extra adds a --color/--no-color flag (aliased as --ansi/--no-ansi) that controls whether ANSI codes are emitted. It is eager, so it takes effect before other eager options like --version.
The option respects the NO_COLOR, CLICOLOR, and CLICOLOR_FORCE environment variables. When any of these signals “no color”, the environment takes precedence over the default value (but an explicit --color or --no-color on the command line always wins).
All Click Extra commands and groups include this option by default. Use color_option as a standalone decorator when building CLIs with plain click.command:
import click
from click_extra import echo, color_option
@click.command
@color_option
def greet():
"""Say hello with optional color."""
ctx = click.get_current_context()
if ctx.color:
echo("\x1b[32mHello in green!\x1b[0m")
else:
echo("Hello without color.")
$ greet --color
Hello in green!
$ greet --no-color
Hello without color.
--help, -h aliases¶
Click Extra defaults help_option_names to ("--help", "-h"), adding the short -h alias that Click does not provide out of the box. This applies to all commands and groups created with Click Extra decorators:
from click_extra import command, echo
@command
def hello():
"""Greet the user."""
echo("Hello!")
$ hello -h
Usage: hello [OPTIONS]
Greet the user.
Options:
--time / --no-time Measure and print elapsed execution time. [default:
no-time]
--color, --ansi / --no-color, --no-ansi
Strip out all colors and all ANSI codes from output.
[default: color]
--config CONFIG_PATH Location of the configuration file. Supports local
path with glob patterns or remote URL. [default: ~/.c
onfig/hello/{*.toml,*.yaml,*.yml,*.json,*.json5,*.json
c,*.hjson,*.ini,*.xml,pyproject.toml}]
--no-config Ignore all configuration files and only use command
line parameters and environment variables.
--validate-config FILE Validate the configuration file and exit.
--show-params Show all CLI parameters, their provenance, defaults
and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one level
for each additional repetition of the option.
[default: 0]
--version Show the version and exit.
-h, --help Show this message and exit.
Colors and styles¶
The click-extra render-matrix command renders a matrix of all colors and styles, useful for testing terminal capabilities. Based on cloup.styling.Style:
$ click-extra render-matrix --matrix=colors
╭─────────────────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────╮
│ Foreground ↴ \ Background → │ black │ blue │ bright_black │ bright_blue │ bright_cyan │ bright_green │ bright_magenta │ bright_red │ bright_white │ bright_yellow │ cyan │ green │ magenta │ red │ reset │ white │ yellow │
├─────────────────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┤
│ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │ black │
│ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │
│ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │
│ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │
│ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │
│ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │
│ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │
│ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │
│ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │
│ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │
│ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │
│ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │ green │
│ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │
│ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │ red │
│ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │
│ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │ white │
│ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │
╰─────────────────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────╯
$ click-extra render-matrix --matrix=styles
╭───────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────╮
│ Color ↴ \ Style → │ bold │ dim │ underline │ overline │ italic │ blink │ reverse │ strikethrough │
├───────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┤
│ black │ black │ black │ black │ black │ black │ black │ black │ black │
│ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │ blue │
│ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │ bright_black │
│ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │ bright_blue │
│ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │ bright_cyan │
│ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │ bright_green │
│ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │ bright_magenta │
│ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │ bright_red │
│ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │ bright_white │
│ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │ bright_yellow │
│ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │ cyan │
│ green │ green │ green │ green │ green │ green │ green │ green │ green │
│ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │ magenta │
│ red │ red │ red │ red │ red │ red │ red │ red │ red │
│ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │ reset │
│ white │ white │ white │ white │ white │ white │ white │ white │ white │
│ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │ yellow │
╰───────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────╯
Caution
The rendering of colors and styles in this HTML documentation is not complete, and does not reflect the real output in a terminal.
pygments-ansi-color, the component we rely on to render ANSI code in Sphinx via Pygments, only supports a subset of the ANSI codes we use.
Tip
Run uvx click-extra render-matrix --matrix=colors or uvx click-extra render-matrix --matrix=styles in your terminal to see the real rendering with your color scheme.
click_extra.colorize API¶
classDiagram
ExtraOption <|-- ColorOption
HelpFormatter <|-- HelpExtraFormatter
HelpTheme <|-- HelpExtraTheme
… py:module:: click_extra.colorize
Helpers and utilities to apply ANSI coloring to terminal content.
… py:class:: HelpExtraTheme(invoked_command=
- module:
click_extra.colorize
Bases: :py:class:
~cloup.styling.HelpThemeExtends
cloup.HelpThemewithlogging.levelsand extra properties.… py:method:: HelpExtraTheme.critical()
- module:
click_extra.colorize
- rtype:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.TypeVar`\ \(``T``)`… py:method:: HelpExtraTheme.error()
- module:
click_extra.colorize
- rtype:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.TypeVar`\ \(``T``)`… py:method:: HelpExtraTheme.warning()
- module:
click_extra.colorize
- rtype:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.TypeVar`\ \(``T``)`… py:method:: HelpExtraTheme.info()
- module:
click_extra.colorize
- rtype:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.TypeVar`\ \(``T``)`… py:method:: HelpExtraTheme.debug()
- module: