https://github.com/kdeldycke/click-extra
🌈 Drop-in replacement for Click to make user-friendly and colorful CLI
https://github.com/kdeldycke/click-extra
ansi-colors cli click cloup colorization console json logging multiplatform pygments pytest python python-tabulate sphinx terminal toml yaml
Last synced: 19 days ago
JSON representation
🌈 Drop-in replacement for Click to make user-friendly and colorful CLI
- Host: GitHub
- URL: https://github.com/kdeldycke/click-extra
- Owner: kdeldycke
- License: gpl-2.0
- Created: 2021-10-18T08:02:27.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2026-03-01T06:11:53.000Z (3 months ago)
- Last Synced: 2026-03-01T09:34:22.257Z (3 months ago)
- Topics: ansi-colors, cli, click, cloup, colorization, console, json, logging, multiplatform, pygments, pytest, python, python-tabulate, sphinx, terminal, toml, yaml
- Language: Python
- Homepage: https://kdeldycke.github.io/click-extra
- Size: 23.8 MB
- Stars: 109
- Watchers: 1
- Forks: 8
- Open Issues: 14
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/funding.yml
- License: license
- Code of conduct: .github/code-of-conduct.md
- Citation: citation.cff
Awesome Lists containing this project
- best-of-python - GitHub - 12% open · ⏱️ 16.04.2026): (CLI Development)
README
[](https://pypi.org/project/click-extra/)
[](https://pypi.org/project/click-extra/)
[](https://pepy.tech/projects/click-extra)
[](https://github.com/kdeldycke/click-extra/actions/workflows/tests.yaml?query=branch%3Amain)
[](https://codecov.io/gh/kdeldycke/click-extra)
[](https://github.com/kdeldycke/click-extra/actions/workflows/docs.yaml?query=branch%3Amain)
[](https://doi.org/10.5281/zenodo.7116050)
## What is Click Extra?
It should be easy to write a good CLI in Python. [Click](https://click.palletsprojects.com) 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](https://kdeldycke.github.io/click-extra/upstream.html) 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](https://kdeldycke.github.io/click-extra/tutorial.html#from-script-to-cli-in-30-seconds).
## Demo
You can try Click Extra right now in your terminal, without installing any dependency or virtual env [thanks to `uvx`](https://docs.astral.sh/uv/guides/tools/):
```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:
Into this:
To undestrand how we ended up with the result above, [go read the tutorial](https://kdeldycke.github.io/click-extra/tutorial.html).
## Features
### Configuration
- [Multi-format configuration file](https://kdeldycke.github.io/click-extra/config.html) 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](https://kdeldycke.github.io/click-extra/config.html#dotted-keys): 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](https://kdeldycke.github.io/click-extra/config.html#standalone-option) from your CLI's options, with optional [dataclass schema typing](https://kdeldycke.github.io/click-extra/config.html#schema-only-configuration) so values arrive parsed and validated
- Remote loading of [configuration from URLs](https://kdeldycke.github.io/click-extra/config.html#remote-url)
- Optional [strict validation](https://kdeldycke.github.io/click-extra/config.html#strictness) of configuration with `--validate-config`
- [Extension hook](https://kdeldycke.github.io/click-extra/config.html#extending-validation) (`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](https://kdeldycke.github.io/click-extra/config.html#default-folder) on each platform (XDG spec. on Linux)
- [Glob search patterns](https://kdeldycke.github.io/click-extra/config.html#search-pattern) for configuration files
- A `--no-config` option to disable configuration file loading
- Respect of `CLI` > `Configuration` > `Environment` > `Defaults` [precedence](https://kdeldycke.github.io/click-extra/config.html#precedence)
### Help screens and theming
- [Colorized help screens](https://kdeldycke.github.io/click-extra/colorize.html): 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](https://kdeldycke.github.io/click-extra/colorize.html#cross-reference-highlighting)
- [Theme system](https://kdeldycke.github.io/click-extra/theme.html) with six built-in palettes ([`dark`, `light`, `dracula`, `monokai`, `nord`, `solarized_dark`](https://kdeldycke.github.io/click-extra/theme.html#built-in-themes))
- [User-defined themes and partial overrides loaded from the CLI's `--config` file](https://kdeldycke.github.io/click-extra/theme.html#themes-from-your-config-file) (`[tool..themes.]`), scoped per invocation so concurrent runs don't bleed into each other
- [`--theme` flag](https://kdeldycke.github.io/click-extra/theme.html#the-theme-option) on every command, with case-insensitive validation against the live registry
- `-h`/`--help` option names (see [rant on other inconsistencies](https://blog.craftyguy.net/cmdline-help/))
- Built-in [`help` subcommand](https://kdeldycke.github.io/click-extra/commands.html#help-subcommand) with a `--search` mode for groups
### Standard options on every CLI
- [Colored `--version`](https://kdeldycke.github.io/click-extra/version.html) with [template variables](https://kdeldycke.github.io/click-extra/version.html#variables) for git metadata (branch, hash, date, tag) and [pre-baking](https://kdeldycke.github.io/click-extra/version.html#pre-baking-git-metadata) for compiled binaries (Nuitka, PyInstaller)
- [Colored `--verbosity` LEVEL and logs](https://kdeldycke.github.io/click-extra/logging.html), plus `-v`/`--verbose` repetition for incremental bumping
- [`--show-params`](https://kdeldycke.github.io/click-extra/parameters.html#show-params-option) to debug parameter defaults, values, environment variables and provenance
- [`--time`/`--no-time`](https://kdeldycke.github.io/click-extra/timer.html) to measure command execution duration
- [`--table-format`](https://kdeldycke.github.io/click-extra/table.html#table-formats) to switch between 40+ table-rendering styles (uses [`print_table()`](https://kdeldycke.github.io/click-extra/table.html) and [`serialize_data()`](https://kdeldycke.github.io/click-extra/table.html#data-serialization))
- [`--jobs`](https://kdeldycke.github.io/click-extra/jobs.html) for parallel-execution worker counts
- `--telemetry`/`--no-telemetry` flag to opt-in/out of tracking code
- `--color`/`--no-color` option flag, with recognition of `NO_COLOR` ([no-color.org](https://no-color.org)), `FORCE_COLOR`, `CLICOLOR`, and `LLM` environment variables
- Recognition of `DO_NOT_TRACK` from [consoledonottrack.com](https://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`](https://kdeldycke.github.io/click-extra/types.html#enumchoice) — `click.Choice` subclass with proper `Enum` rendering, case-insensitive matching, alias support, and pluggable [choice sources](https://kdeldycke.github.io/click-extra/types.html#choice-source)
- [Click parameter introspection](https://kdeldycke.github.io/click-extra/parameters.html#introspecting-parameters) and a [shared parameter structure](https://kdeldycke.github.io/click-extra/parameters.html#parameter-structure) used by both `--show-params` and the config loader
### CLI wrapper
- [CLI wrapper](https://kdeldycke.github.io/click-extra/wrap.html) (`click-extra wrap`) applies help colorization, themes, and config loading to any Click CLI without modifying its source code
- [`show-params` subcommand](https://kdeldycke.github.io/click-extra/wrap.html#introspecting-external-clis) to introspect any external Click CLI's parameters
- [User-defined themes via `--config`](https://kdeldycke.github.io/click-extra/wrap.html#custom-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](https://kdeldycke.github.io/click-extra/commands.html#lazily-loading-subcommands) from module paths to speed up CLI startup time
- [Composition with third-party Click CLIs](https://kdeldycke.github.io/click-extra/commands.html#third-party-commands-composition) (`wrap_other_commands`)
### Documentation tooling
- [`click:source` and `click:run` Sphinx directives](https://kdeldycke.github.io/click-extra/sphinx.html#click-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`](https://kdeldycke.github.io/click-extra/sphinx.html#python-directives) — 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](https://kdeldycke.github.io/click-extra/sphinx.html#inline-tests) in documentation: every `click:run` block runs at build time and assertions fail the build
- Render [GitHub alerts](https://kdeldycke.github.io/click-extra/sphinx.html) into MyST admonitions in both Sphinx and MkDocs
- [ANSI-capable Pygments lexers](https://kdeldycke.github.io/click-extra/pygments.html#ansi-language-lexers) for shell session and console output, with [24-bit true-color rendering](https://kdeldycke.github.io/click-extra/pygments.html#bit-true-color) on by default
- [`AnsiHtmlFormatter`](https://kdeldycke.github.io/click-extra/pygments.html#ansi-html-formatter) for HTML output of ANSI-colored text
- [MkDocs plugin](https://kdeldycke.github.io/click-extra/mkdocs.html) for ANSI color rendering in code blocks
### Testing
- [`ExtraCliRunner`](https://kdeldycke.github.io/click-extra/testing.html) — `click.testing.CliRunner` subclass that captures `stdout` and `stderr` separately and preserves ANSI codes for assertion against colored output
- [pytest fixtures](https://kdeldycke.github.io/click-extra/pytest.html#fixtures) (`invoke`, `extra_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](https://kdeldycke.github.io/click-extra/upstream.html) across Click, Cloup, Pygments, tabulate, MyST-Parser, Furo, and unmaintained `click-contrib` packages
- Drop-in replacement for [Click](https://click.palletsprojects.com) and [Cloup](https://github.com/janluke/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.
## Used in
Check these projects to get real-life examples of `click-extra` usage:
-  [Meta Package Manager](https://github.com/kdeldycke/meta-package-manager#readme)
\- A unifying CLI for multiple package managers.
-  [Mail Deduplicate](https://github.com/kdeldycke/mail-deduplicate#readme) - A
CLI to deduplicate similar emails.
-  [fireproxng](https://github.com/Sprocket-Security/fireproxng#readme) - A rewrite of the fireprox tool.
-  [agent-catalog](https://github.com/couchbaselabs/agent-catalog#readme) - Couchbase agent catalog.
-  [badger-proxy](https://github.com/hugolundin/badger#readme) - 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.