kdeldycke/click-extra: 🌈 Drop-in replacement for Click to make user-friendly and colorful CLI

It should be easy to write a good CLI in Python. Click makes it so. But there are still hundreds of tweaks to implement by yourself to have a user-friendly CLI.

Click Extra is a ready-to-use wrapper around Click to make your CLI look good and behave well. It is a drop-in replacement with good defaults that saves lots of boilerplate code and frustration by making all parts working together.

It also comes with workarounds and patches that have not reached upstream yet (or are unlikely to).

Who is this for?

Anyone building a CLI who doesn't have time to assemble the pieces from scratch:

• You use Click and want professional defaults without the boilerplate.
• You're a security researcher turning a proof-of-concept into a presentable tool to hand off, demo, or attach to an advisory.
• You're a DevOps engineer or sysadmin whose one-off script grew into a team tool and needs --help, --verbose, --config, and colored output.

Demo

You can try Click Extra right now in your terminal, without installing any dependency or virtual env thanks to uvx:

``shell-session $ uvx click-extra

This is a great way to play with Click Extra and check that it runs fine on your system, and renders properly in your terminal.

Example
It transforms this vanilla click CLI:

!click CLI help screen
Into this:
!click-extra CLI help screen
And here is the entire diff between the two. Click Extra proxies the whole click namespace, so aliasing it back leaves every decorator and call untouched:

The colors, and every option below --name, come from that one line. Both screens above are captured from the tutorial's own live examples.

• Colorized help screens: options, choices, metavars, arguments, defaults, ranges, required labels, environment variables, subcommands and aliases all get distinct styles. Option names referenced in descriptions and docstrings are highlighted automatically
• Theme system with seven built-in themes (dark, light, dracula, monokai, nord, solarized-dark, and a monochrome manpage), here recoloring the same help screen:

• User-defined themes and partial overrides loaded from the CLI's --config file ([tool..themes.]), scoped per invocation so concurrent runs don't bleed into each other
• --theme flag on every command, with case-insensitive validation against the live registry
• CLICK_EXTRA_THEME exported once from a shell profile themes every Click Extra CLI on the machine, with a per-CLI _THEME taking precedence over it
• --theme=auto reads the terminal's own background to pick between the dark and light palettes, from CLITHEME, COLORFGBG, or an opt-in OSC 11 query
• -h/--help option names (see rant on other inconsistencies)
• Built-in help subcommand with a --search mode for groups
• Usage examples declared as examples=[("description", "command")] on any command, rendered in the help screen, the man page and every machine-readable format

Listed in the order they show up in a --help screen:

• --time/--no-time to measure command execution duration
• --color[=WHEN] tri-state flag (auto/always/never) with a hidden --no-color alias, recognizing NO_COLOR (no-color.org), FORCE_COLOR, CLICOLOR, and LLM environment variables
• --params to debug parameter defaults, values, environment variables and provenance
• --table-format to switch between fifty table-rendering styles, from terminal grids to machine-readable json, yaml, toml, csv and xml (uses print_table() and serialize_data())
• Colored --verbosity LEVEL and logs, plus -v/--verbose repetition for incremental bumping
• --tree to print the whole hierarchy of nested subcommands with their descriptions, aliases and deprecations:

• --man to typeset the command's manual and page it, the way man does, for a CLI that ships no man page at all
• --help-format to render the command as JSON, Markdown, a man page or a Carapace spec, for the readers that are programs rather than people: one option carrying a format, not one flag per format
• Colored --version with template variables for git metadata (branch, hash, date, tag) and pre-baking for compiled binaries (Nuitka, PyInstaller)

• --jobs for parallel-execution worker counts
• --telemetry/--no-telemetry flag to opt-in/out of tracking code, recognizing DO_NOT_TRACK from consoledonottrack.com

• Global show_envvar option to display all environment variables in help screens
• Global show_choices to activate selection of choices on user input prompts
• Auto-generation and normalization of environment variables for all options

• CLI wrapper (click-extra wrap) applies help colorization, themes, and config loading to any Click CLI without modifying its source code:

• --params mode to introspect any external Click CLI's parameters, restricted to the columns you care about:

• --help-format carapace to export any Click CLI's Carapace completion spec, for identical completions in Bash, Zsh, Fish, Nushell, PowerShell, Elvish, Xonsh and more, with --install putting it where Carapace looks (and --help-format man --install doing the same for a man page):

• --man mode to read the manual of a CLI that never wrote one
• --help-format mode to describe any Click CLI as JSON, Markdown, a man page or a Carapace spec: usage line, option groups, subcommands and all, with no cooperation from the target
• --tree mode to print any external Click CLI's subcommand hierarchy without running it
• User-defined themes via --config work transparently through the wrapper, so users can theme third-party CLIs from their own pyproject.toml

• Automatic pyproject.toml integration: the CLI reads its [tool.] section from the user's project file, including a CWD-aware walk that skips unrelated pyproject.toml files
• Inference of the configuration file structure from your CLI's options, with optional dataclass schema typing so values arrive parsed and validated
• Remote loading of configuration from URLs
• Optional strict validation of configuration with --validate-config
• Extension hook (ConfigValidator) for user-defined sub-trees whose keys are data rather than CLI flags (per-plugin overrides, matrix axes, user-defined IDs), with rooted ValidationError reporting
• Respect the default application path on each platform (XDG spec. on Linux)
• Glob search patterns for configuration files
• A --no-config option to disable configuration file loading
• Reserved _default_subcommands and _prepend_subcommands keys to name which subcommands a bare invocation runs, and which ones always run in front of it
• Respect of Prompt > CLI > Environment > Config > Defaults precedence

• EnumChoice — click.Choice subclass with proper Enum rendering, case-insensitive matching, alias support, and pluggable choice sources
• Click parameter introspection and a shared parameter structure used by both --params and the config loader

• Lazy-loading of subcommands from module paths to speed up CLI startup time
• Composition with third-party Click CLIs (wrap_other_commands)

• click-extra screenshot captures any CLI's colored output as an SVG image or a self-contained HTML block, and the window it is drawn in is yours to set: terminal preset, light or dark chrome, gradient backdrop, caption, line numbers, transparency, credit line, border, shadow, corner radius and margins. Every capture in this readme is one, rewritten on each documentation build, and a pair of them can be switched on the reader's own color scheme:

• click:source and click:run Sphinx directives in MyST Markdown and reStructuredText to document CLI source code and their execution
• python:source, python:run, python:render, python:render-myst, python:render-rst — the same machinery for arbitrary Python, with a render* family that parses the captured output as live document content (replaces the docs_update.py + marker-region pattern)
• Inline testing of CLI examples in documentation: every click:run block runs at build time and assertions fail the build
• Render GitHub alerts into MyST admonitions in both Sphinx and MkDocs
• ANSI-capable Pygments lexers for shell session and console output, with 24-bit true-color rendering on by default
• AnsiHtmlFormatter for HTML output of ANSI-colored text
• MkDocs plugin for ANSI color rendering in code blocks

• CliRunner — click.testing.CliRunner subclass that captures stdout and stderr separately and preserves ANSI codes for assertion against colored output
• pytest fixtures (invoke, runner, create_config) and ready-made regex helpers (default_options_uncolored_help, default_debug_*) for click-extra-aware test suites

• Fixes 100+ bugs and addresses missing features across Click, Cloup, Pygments, tabulate, MyST-Parser, Furo, and unmaintained click-contrib packages
• Drop-in replacement for Click and Cloup: every from click_extra import … and @click_extra.command works as a transparent superset. Cloup provides option groups, constraints, subcommand sections, aliases, and Did you mean ? suggestions; click-extra adds everything above on top.

Check these projects to get real-life examples of click-extra usage.

• !GitHub stars Anki - A smart spaced repetition flashcard program.
• !GitHub stars pip-tools - A set of tools to keep your pinned Python dependencies fresh.
• !GitHub stars bump-my-version - A CLI updating every version string in a project.
• !GitHub stars SQLSpec - A query mapper for Python.
• !GitHub stars Extra Platforms - Detect architectures, platforms, shells, terminals and CI systems, grouped by family.