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:
To understand how we ended up with the result above, go read the tutorial.
Features
Configuration
- Multi-format configuration file loader for:
TOMLYAMLJSON,JSON5,JSONCandHJSONINI, with extended interpolation, multi-level sections and non-native types (list,set, …)XML
- Automatic
pyproject.tomlintegration: the CLI reads its[tool.<cli>]section from the user's project file, including a CWD-aware walk that skips unrelatedpyproject.tomlfiles - 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 rootedValidationErrorreporting - Respect the default application path on each platform (XDG spec. on Linux)
- Glob search patterns for configuration files
- A
--no-configoption to disable configuration file loading - Respect of
Prompt>CLI>Environment>Config>Defaultsprecedence
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 monochromemanpage) - User-defined themes and partial overrides loaded from the CLI's
--configfile ([tool.<cli>.themes.<name>]), scoped per invocation so concurrent runs don't bleed into each other --themeflag on every command, with case-insensitive validation against the live registry-h/--helpoption names (see rant on other inconsistencies)- Built-in
helpsubcommand with a--searchmode for groups
Standard options on every CLI
- Colored
--versionwith template variables for git metadata (branch, hash, date, tag) and pre-baking for compiled binaries (Nuitka, PyInstaller) - Colored
--verbosityLEVEL and logs, plus-v/--verboserepetition for incremental bumping --paramsto debug parameter defaults, values, environment variables and provenance--treeto print the whole hierarchy of nested subcommands with their descriptions--time/--no-timeto measure command execution duration--table-formatto switch between 40+ table-rendering styles (usesprint_table()andserialize_data())--jobsfor parallel-execution worker counts--telemetry/--no-telemetryflag to opt-in/out of tracking code--color[=WHEN]tri-state flag (auto/always/never) with a hidden--no-coloralias, recognizingNO_COLOR(no-color.org),FORCE_COLOR,CLICOLOR, andLLMenvironment variables- Recognition of
DO_NOT_TRACKfrom consoledonottrack.com for telemetry - Global
show_envvaroption to display all environment variables in help screens - Global
show_choicesto activate selection of choices on user input prompts - Auto-generation and normalization of environment variables for all options
Types and parameters
EnumChoice—click.Choicesubclass with properEnumrendering, case-insensitive matching, alias support, and pluggable choice sources- Click parameter introspection and a shared parameter structure used by both
--paramsand 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 --paramsmode to introspect any external Click CLI's parameters--treemode to print any external Click CLI's subcommand hierarchy without running it- User-defined themes via
--configwork transparently through the wrapper, so users can theme third-party CLIs from their ownpyproject.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:sourceandclick:runSphinx directives in MyST Markdown and reStructuredText to document CLI source code and their executionpython:source,python:run,python:render,python:render-myst,python:render-rst— the same machinery for arbitrary Python, with arender*family that parses the captured output as live document content (replaces thedocs_update.py+ marker-region pattern)- Inline testing of CLI examples in documentation: every
click:runblock 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
AnsiHtmlFormatterfor HTML output of ANSI-colored text- MkDocs plugin for ANSI color rendering in code blocks
Testing
CliRunner—click.testing.CliRunnersubclass that capturesstdoutandstderrseparately 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-contribpackages - Drop-in replacement for Click and Cloup: every
from click_extra import …and@click_extra.commandworks as a transparent superset. Cloup provides option groups, constraints, subcommand sections, aliases, andDid 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
click_extra-8.9.1.tar.gz
(1.3 MB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
click_extra-8.9.1-py3-none-any.whl
(453.4 kB
view details)
File details
Details for the file click_extra-8.9.1.tar.gz.
File metadata
- Download URL: click_extra-8.9.1.tar.gz
- Upload date:
- Size: 1.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
18a99d91d94375aaa27dc6a5efdebf6cb0cd0637bae49fd1cb6d8a6398cf8294
|
|
| MD5 |
6cdbc97da43980144cb70f1743732209
|
|
| BLAKE2b-256 |
fd59f527fbd7c2d36c057073900b69da480d928f2d91840d08dcf80929512c81
|
Provenance
The following attestation bundles were made for click_extra-8.9.1.tar.gz:
Publisher:
release.yaml on kdeldycke/click-extra
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
click_extra-8.9.1.tar.gz -
Subject digest:
18a99d91d94375aaa27dc6a5efdebf6cb0cd0637bae49fd1cb6d8a6398cf8294 - Sigstore transparency entry: 2475988584
- Sigstore integration time:
-
Permalink:
kdeldycke/click-extra@989742fb50da83d8794163babcea6eddf15d166a -
Branch / Tag:
refs/heads/main - Owner: https://github.com/kdeldycke
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yaml@989742fb50da83d8794163babcea6eddf15d166a -
Trigger Event:
push
-
Statement type:
File details
Details for the file click_extra-8.9.1-py3-none-any.whl.
File metadata
- Download URL: click_extra-8.9.1-py3-none-any.whl
- Upload date:
- Size: 453.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1491b38abd9de130addcc1a459aa4d04ff23cdebe978397ebe0e451342800af9
|
|
| MD5 |
f26ab26f66a25f12c946908463234902
|
|
| BLAKE2b-256 |
d7aba1407b2e1f55b702d6df86c283d9d5da4da417431c7ec986fc3b47cff6ae
|
Provenance
The following attestation bundles were made for click_extra-8.9.1-py3-none-any.whl:
Publisher:
release.yaml on kdeldycke/click-extra
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
click_extra-8.9.1-py3-none-any.whl -
Subject digest:
1491b38abd9de130addcc1a459aa4d04ff23cdebe978397ebe0e451342800af9 - Sigstore transparency entry: 2475987968
- Sigstore integration time:
-
Permalink:
kdeldycke/click-extra@989742fb50da83d8794163babcea6eddf15d166a -
Branch / Tag:
refs/heads/main - Owner: https://github.com/kdeldycke
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yaml@989742fb50da83d8794163babcea6eddf15d166a -
Trigger Event:
push
-
Statement type:
