kdeldycke/click-extra

What is Click Extra?

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.

Click Extra's defaults-first design means one decorator gets you there. See the 30-second quick start.

Demo

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

$ 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:

Into this:

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:

-import click
+import click_extra as click

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

Features

Help screens and theming

• 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.<cli>.themes.<name>]), 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 <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

Standard options on every CLI

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 40+ 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)

Two more options are one decorator away, for a CLI that wants them:

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

And every CLI gets these on top:

• 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

• 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:
• That same inventory in any machine-readable format, for a script that has to consume another CLI's interface:
• --help-format carapace to export any Click CLI's Carapace completion spec, for identical completions in Bash, Zsh, Fish, Nushell, PowerShell, Elvish and Xonsh, 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

Configuration

• Multi-format configuration file loader for:
  • TOML
  • YAML
  • JSON, JSON5, JSONC and HJSON
  • INI, with extended interpolation, multi-level sections and non-native types (list, set, …)
  • XML
• Automatic pyproject.toml integration: the CLI reads its [tool.<cli>] 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
• Respect of Prompt > CLI > Environment > Config > Defaults precedence

Types and parameters

• 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

Performance and structure

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

Documentation tooling

• 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

Testing

• 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

Upstream

• 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 <subcommand>? suggestions; click-extra adds everything above on top.

Used in

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

CLIs built on it

• Meta Package Manager - A unifying CLI for multiple package managers.
• Mail Deduplicate - A CLI to deduplicate similar emails.
• repomatic - Automate repository maintenance, releases and CI/CD workflows.
• agent-catalog - Couchbase agent catalog.
• octo-logo - Simple logos for complex projects.
• besta-tools - Tools for Besta devices and Besta RTOS proprietary formats.

Documentation rendered with it

These pull click-extra[sphinx] or click-extra[mkdocs] for GitHub alerts, ANSI-colored code blocks and live CLI examples, and build their own command line on something else:

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

Feel free to send a PR to add your project in either list if you are relying on Click Extra in any way.