kdeldycke/click-extra

What is Click Extra?

It should be easy to write a good CLI in Python. Click makes it so. But there is still hundrends 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:

To understand how we ended up with the result above, go read the tutorial.

Features

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

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)
• 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
• -h/--help option names (see rant on other inconsistencies)
• Built-in help subcommand with a --search mode for groups

Standard options on every CLI

• Colored --version with template variables for git metadata (branch, hash, date, tag) and pre-baking for compiled binaries (Nuitka, PyInstaller)
• Colored --verbosity LEVEL and logs, plus -v/--verbose repetition for incremental bumping
• --params to debug parameter defaults, values, environment variables and provenance
• --tree to print the whole hierarchy of nested subcommands with their descriptions
• --time/--no-time to measure command execution duration
• --table-format to switch between 40+ table-rendering styles (uses print_table() and serialize_data())
• --jobs for parallel-execution worker counts
• --telemetry/--no-telemetry flag to opt-in/out of tracking code
• --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
• Recognition of DO_NOT_TRACK from consoledonottrack.com for telemetry
• 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

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

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
• --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

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

• Meta Package Manager - A unifying CLI for multiple package managers.
• Mail Deduplicate - A CLI to deduplicate similar emails.
• fireproxng - A rewrite of the fireprox tool.
• agent-catalog - Couchbase agent catalog.
• badger-proxy - An mDNS-based reverse proxy for naming services on a local network.

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