CLI¶
The click-extra package ships a CLI of the same name. It doubles as a live demo of the framework’s rendering features and as a toolbox of documentation and testing utilities. It comes with the package itself (see installation) or as a standalone binary.
Everything below is rendered at build time from the actual command tree, so this reference cannot drift from the code.
Commands¶
Help screen¶
$ click-extra --help
Usage: click-extra [OPTIONS] COMMAND [ARGS]...
Click Extra CLI.
Options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/{*.toml,*.yaml,*.
yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.
plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
--version Show the version and exit.
-h, --help Show this message and exit.
Demo:
8color Render all standard 8-color foreground/background...
colors Render every foreground color against every background...
gradient Render 24-bit RGB gradients vs.
palette Render a compact 256-color indexed swatch.
spinner Animate the spinner widget; --table lists the catalog...
styles Render every color with each text style (bold, dim,...
themes Render a sample help screen under every built-in theme,...
trail Trace a simulated batch of operations behind an...
Other commands:
convert-to-myst Convert reST docstrings to MyST markdown in Python...
help Show help for a command.
prebake Pre-bake build-time metadata into Python source files.
refresh-directives Refresh the self-updating blocks embedded in Markdown...
screenshot Capture a command's colored output and write it as an...
test-suite Run declarative CLI test cases against a command or...
wrap (run) Run, or introspect, any Click CLI through Click Extra.
click-extra 8color¶
$ click-extra 8color --help
Usage: click-extra 8color [OPTIONS]
Render all standard 8-color foreground/background combinations.
Options:
-h, --help Show this message and exit.
click-extra colors¶
$ click-extra colors --help
Usage: click-extra colors [OPTIONS]
Render every foreground color against every background color.
Options:
-h, --help Show this message and exit.
click-extra convert-to-myst¶
$ click-extra convert-to-myst --help
Usage: click-extra convert-to-myst [OPTIONS] [DIRECTORY]
Convert reST docstrings to MyST markdown in Python source files.
Transforms reST markup in docstrings and #: comment blocks to MyST. The
companion click_extra.sphinx.myst_docstrings Sphinx extension converts the
MyST back to reST at build time, so sphinx.ext.autodoc still works.
If DIRECTORY is not specified, auto-detects the source package directory from
the project's script entry points in pyproject.toml.
Safe to re-run: already-converted MyST syntax does not match the reST
patterns, so the conversion is idempotent.
Options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/{*.toml,*.yaml,*.
yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.
plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
--version Show the version and exit.
-h, --help Show this message and exit.
click-extra gradient¶
$ click-extra gradient --help
Usage: click-extra gradient [OPTIONS]
Render 24-bit RGB gradients vs. their 256-color quantized equivalents.
Options:
-h, --help Show this message and exit.
click-extra help¶
$ click-extra help --help
Usage: click-extra help [OPTIONS] [COMMAND_PATH]...
Show help for a command.
Options:
--search TEXT Search all subcommands for matching options or descriptions.
-h, --help Show this message and exit.
click-extra palette¶
$ click-extra palette --help
Usage: click-extra palette [OPTIONS]
Render a compact 256-color indexed swatch.
Options:
-h, --help Show this message and exit.
click-extra prebake¶
$ click-extra prebake --help
Usage: click-extra prebake [OPTIONS] COMMAND [ARGS]...
Pre-bake build-time metadata into Python source files.
Options:
-h, --help Show this message and exit.
Commands:
all Pre-bake `__version__` and all git fields in one pass.
field Replace an empty dunder variable with a value.
help Show help for a command.
version Inject Git commit hash into `__version__`.
click-extra prebake all¶
$ click-extra prebake all --help
Usage: click-extra prebake all [OPTIONS]
Pre-bake `__version__` and all git fields in one pass.
Scans each target file for empty `__<field>__` dunder placeholders, resolves
their values from the current Git state, and injects them.
Also appends the Git short hash to `.dev` versions in `__version__` (same as
`prebake version`).
Supported git fields:
git_branch, git_long_hash, git_short_hash, git_date, git_tag
Additional computed fields (`__git_tag_sha__`, `__git_distance__`,
`__git_dirty__`) are baked if their dunder placeholder exists and a git
resolution is available. Fields without a placeholder in the source file
are skipped silently.
Options:
--module PATH Path to __init__.py to modify. Auto-discovered from
[project.scripts] if not provided.
-h, --help Show this message and exit.
click-extra prebake field¶
$ click-extra prebake field --help
Usage: click-extra prebake field [OPTIONS] NAME VALUE
Replace an empty dunder variable with a value.
NAME is the template field name (like `git_tag_sha`) or the full dunder name
(like `__git_tag_sha__`). Double underscores are added automatically when
missing.
VALUE is the string to inject.
Only modifies variables that are currently empty. Already-populated values are
left untouched (idempotent).
Options:
--module PATH Path to __init__.py to modify. Auto-discovered from
[project.scripts] if not provided.
-h, --help Show this message and exit.
click-extra prebake help¶
$ click-extra prebake help --help
Usage: click-extra prebake help [OPTIONS] [COMMAND_PATH]...
Show help for a command.
Options:
--search TEXT Search all subcommands for matching options or descriptions.
-h, --help Show this message and exit.
click-extra prebake version¶
$ click-extra prebake version --help
Usage: click-extra prebake version [OPTIONS]
Inject Git commit hash into `__version__`.
Appends the Git short hash as a PEP 440 local version identifier (for example
`1.0.0.dev0` becomes `1.0.0.dev0+abc1234`).
Only modifies `.dev` versions without an existing `+` suffix. Release versions
and already pre-baked versions are left untouched.
Options:
--hash TEXT Git short hash to append. Auto-detected from HEAD if not
provided.
--module PATH Path to __init__.py to modify. Auto-discovered from
[project.scripts] if not provided.
-h, --help Show this message and exit.
click-extra refresh-directives¶
$ click-extra refresh-directives --help
Usage: click-extra refresh-directives [OPTIONS] PATHS...
Refresh the self-updating blocks embedded in Markdown files.
Walks each PATH (a Markdown file, or a directory scanned recursively for
Markdown sources) and rewrites every supported self-updating block in place:
- matrix blocks (directive fences and marker regions alike), regenerated
from the project git history;
- python:render blocks carrying the :mirror: flag, whose Python code is
executed to regenerate the mirrored region below the fence (inserted on
first refresh);
- click:run blocks carrying both :screenshot: and :mirror:, whose region
below the fence links to the capture the block writes at build time.
Examples nested inside longer code fences are never refreshed or executed.
Pass --check to report stale blocks without writing; the command then exits
with a non-zero status, so a continuous-integration job can fail on out-of-
date documentation.
Refreshing reads the project git history and needs the sphinx extra: install
it with click-extra[sphinx]. Beware: mirror blocks are arbitrary Python
executed with the privileges of this process, so only refresh documentation
you trust, exactly as you would only build trusted docs.
Options:
--check Do not write; exit with a non-zero status if any
block is stale.
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/{*.toml,*.yaml,*.
yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.
plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
--version Show the version and exit.
-h, --help Show this message and exit.
click-extra screenshot¶
$ click-extra screenshot --help
Usage: click-extra screenshot [OPTIONS] COMMAND_LINE...
Capture a command's colored output and write it as an image or HTML.
Runs COMMAND_LINE with colors forced on and its terminal width pinned, then
writes the captured output where --output points. Its extension picks the
format:
.svg a picture of a terminal window, for a surface that strips inline
HTML. A README on GitHub or PyPI has no other option.
.html selectable, searchable, copy-pasteable text, for a page you own.
Put -- before the command line so its own options are not mistaken for this
command's:
click-extra screenshot --output shot.svg -- my-cli --help
COMMAND_LINE is anything the shell can run, Click CLI or not. A Click CLI not
built on Click Extra prints its help uncolored, so --wrap routes it through
the wrap subcommand first and captures the colored rendering.
An SVG starts each run of text on its own column, so it renders correctly
outside a web browser, where a file manager, a git client or a thumbnailer
would otherwise slide the columns out of place.
Neither format needs an optional dependency.
Options:
--output FILE Path of the file to write. Its extension picks
the format: .svg for an image, .html for
selectable text. [required]
--columns INTEGER|auto Terminal width, in characters, the command wraps
its output to and the image is laid out at. Pass
auto to pin neither: the command finds its own
width, and the image is laid out at the longest
line it printed, so nothing folds inside the
picture. [default: 80]
--background [dark|light] Terminal chrome the capture is drawn on, and the
palette its colors resolve against. Match it to
the theme the captured CLI renders with: a
light-background theme washes out on the dark
default. [default: dark]
--preset [linux|macos|plain|windows]
Terminal to draw the capture as: its window
decorations, palette, font and prompt sigil.
Anything stated alongside wins over it. Left
out, the capture keeps the renderer's own
neutral window.
--border TEXT Color of the frame drawn around the terminal
window, as CSS names it. Pass none to draw no
frame. Defaults to the one the chrome can show.
--border-width INTEGER RANGE Thickness of that frame, in pixels. [default:
1; x>=0]
--radius INTEGER RANGE How round the window's corners are, in pixels.
Zero squares them. Defaults to 8, or to the
rounding --preset terminal draws. [x>=0]
--backdrop TEXT Color filling the image behind the window,
margin included, as CSS names it. Left
transparent by default, so the page shows
through. [default: none]
--shadow TEXT Color of the drop shadow lifting the window off
the page, as CSS names it. Pass none to draw no
shadow. Defaults to the one the chrome calls
for.
--margin INTEGER RANGE Transparent pixels left around the window, on
all four sides. The room the drop shadow falls
into, so a capture drawing one wants some.
[default: 48; x>=0]
--padding INTEGER RANGE Pixels added inside the window, around the
captured text, on top of the few the renderer
adds on its own. [default: 8; x>=0]
--opacity FLOAT RANGE How solid the window's body is. Under 1 it turns
see-through, the way a terminal set to
transparency does: whatever the capture sits on
shows through it, while its text, frame and
title bar keep their own paint. [default: 1.0;
0<=x<=1]
--watermark TEXT Credit line drawn in the image's bottom-right
corner, in the margin around the window. Pass an
empty string to draw none, or your own text to
credit your project instead. [default:
generated with click-extra 9.0.0]
--watermark-color TEXT Color that credit line is drawn in, as CSS names
it, alpha included. Defaults to a neutral gray:
the line sits in the transparent margin, so it
answers to the page embedding the image rather
than to the chrome.
--prompt TEXT Command line to display above the output, when
it differs from the one that is run. Pass an
empty string to draw no prompt at all. Defaults
to the command line itself.
--head INTEGER RANGE Keep only the first N lines of output. [x>=1]
--tail INTEGER RANGE Keep only the last N lines of output. [x>=1]
--truncation TEXT Line standing in for what --head or --tail cut
away. [default: [...]]
--merge-stderr Fold the command's stderr into the capture, for
a CLI printing its help there. Off by default,
which is what keeps a wrapper's build chatter
out of the image.
--line-numbers Number the captured lines in a gutter, the way
Pygments does inline. The prompt counts as line
1, being the invocation everything under it came
from.
--title TEXT Caption drawn in an SVG's window chrome, or an
HTML document's title. [default: ""]
--fragment For HTML, emit the bare block instead of a
standalone document, to paste into a page that
has its own.
--wrap Route COMMAND_LINE through the wrap subcommand,
so a Click CLI that is not built on Click Extra
is captured with its colors. Only works on a
target wrap can resolve.
--timeout FLOAT RANGE Seconds before the command is killed. Waits
forever by default. [x>0]
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/{*.toml,*.yaml,*
.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,
*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml
}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
--version Show the version and exit.
-h, --help Show this message and exit.
click-extra spinner¶
$ click-extra spinner --help
Usage: click-extra spinner [OPTIONS]
Animate the spinner widget; --table lists the catalog instead.
On an interactive terminal it animates a tour of the selected spinners. By
default a curated handful is shown; use --all for the whole catalog, --random
N for a random sample, or --select to name specific spinners (these three are
mutually exclusive). Pass --table to print a reference table instead of
animating: name, frames, per-frame interval, and the tour's per-spinner dwell
time.
Options:
--all Show the whole catalog instead of a curated selection.
--random N Show N spinners chosen at random.
--select NAME,... Show a comma-separated list of spinner names.
--table Print a reference table of the selected spinners.
-h, --help Show this message and exit.
click-extra styles¶
$ click-extra styles --help
Usage: click-extra styles [OPTIONS]
Render every color with each text style (bold, dim, italic, etc.).
Options:
-h, --help Show this message and exit.
click-extra test-suite¶
$ click-extra test-suite --help
Usage: click-extra test-suite [OPTIONS]
Run declarative CLI test cases against a command or binary.
Resolves the suite by precedence: --suite-file or --suite-envvar, then the
[tool.click-extra.test-suite] config (cases, then file), then a built-in
default. Each case invokes the target with its parameters and checks the exit
code and output.
Cases run in parallel by default (see --jobs): each is an independent process
invocation, so they overlap well. Pass --jobs max to use every logical core,
or --jobs 1 for sequential execution, which lets --exit-on-error stop on the
first failure.
On an interactive terminal a spinner reports how many cases have finished. It
stays silent in pipes and CI logs, and --no-progress or --accessible turns it
off.
Options:
--command, --binary COMMAND Path to the binary file to test, or a command
line to be executed. [required]
-F, --suite-file FILE_PATH Path to a test suite file; its format is taken
from the extension (YAML, TOML, JSON, JSON5,
JSONC, Hjson). Repeat to run multiple suites
in sequence. Without any suite source, a
built-in default suite runs.
-E, --suite-envvar ENVVAR_NAME Name of an environment variable holding a test
suite in YAML. Repeat to collect multiple
suites.
-t, --select-test INTEGER Only run the cases with these 1-based numbers.
Repeat to select several; omit to run them
all. [x>=1]
-s, --skip-platform [aarch64|aix|alacritty|all_agents|all_architectures|all_arm|all_ci|all_mips|all_platforms|all_shells|all_sparc|all_terminals|all_traits|all_windows|almalinux|alpine|altlinux|amzn|android|apple_terminal|arch|arch_32_bit|arch_64_bit|arm|armv5tel|armv6l|armv7l|armv8l|ash|azure_pipelines|bamboo|bash|big_endian|bourne_shells|bsd|bsd_without_macos|buildkite|buildroot|c_shells|cachyos|centos|chromeos|circle_ci|cirrus_ci|claude_code|clearlinux|cline|cloudlinux|cmd|codebuild|contour|csh|cursor|cygwin|dash|debian|dragonfly_bsd|endeavouros|exherbo|fedora|fish|foot|freebsd|generic_linux|gentoo|ghostty|github_ci|gitlab_ci|gnome_terminal|gnu_screen|gpu_terminals|guix|haiku|hermetic_build|heroku_ci|hurd|hyper|i386|i586|i686|ibm_mainframe|ibm_powerkvm|illumos|iterm2|kali|kitty|konsole|ksh|kvmibm|linux|linux_layers|linux_like|linuxmint|little_endian|loongarch|loongarch64|macos|mageia|mandriva|manjaro|midnightbsd|mips|mips64|mips64el|mipsel|multiplexers|native_terminals|netbsd|nixos|nobara|nushell|openbsd|opensuse|openwrt|oracle|os400|other_posix|other_shells|parallels|pidora|pikaos|powerpc|powershell|ppc|ppc64|ppc64le|raspbian|rhel|rio|riscv|riscv32|riscv64|rocky|s390x|scientific|sh|slackware|sles|slitaz|solaris|sourcemage|sparc|sparc64|sunos|system_v|tabby|tcsh|teamcity|tilix|tmux|travis_ci|tuxedo|ubuntu|ultramarine|unix|unix_layers|unix_without_macos|void|vscode_terminal|wasm32|wasm64|web_terminals|webassembly|wezterm|windows|windows_shells|windows_terminal|wsl1|wsl2|x86|x86_64|xenserver|xonsh|xterm|zellij|zsh]
Skip cases on these platforms. Repeat to skip
several.
-x, --exit-on-error Exit instantly on the first failed case
(sequential runs only).
-T, --timeout SECONDS Default timeout for each CLI call, unless the
case sets its own. [x>=0]
-W, --work-directory DIR_PATH Directory to run each case's command in.
Defaults to the current one. Moves the command
under test, not the runner: suite files are
read before any case starts.
--show-trace-on-error / --hide-trace-on-error
Show the execution trace of failed cases.
[default: show-trace-on-error]
--stats / --no-stats Print the worker summary and the result tally.
[default: stats]
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/{*.toml,*.yaml
,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.
xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyprojec
t.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected
format to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the
same as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long
operations. Disabled for non-interactive
output (pipes, dumb terminals, CI) and by
--accessible. [default: progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and
exit.
--version Show the version and exit.
--jobs [auto|max|INTEGER] Number of parallel jobs. Accepts an integer,
'auto' (the host's logical CPUs minus one) or
'max' (all logical CPUs). 0 runs sequentially.
[default: auto]
-h, --help Show this message and exit.
click-extra themes¶
$ click-extra themes --help
Usage: click-extra themes [OPTIONS]
Render a sample help screen under every built-in theme, one after another.
Each built-in palette is applied in turn to the same throwaway CLI so the
themes can be eyeballed back to back. A terminal keeps a single background, so
light-background themes (light, manpage) look washed out on a dark terminal,
and dark themes look washed out on a light one.
Options:
-h, --help Show this message and exit.
click-extra trail¶
$ click-extra trail --help
Usage: click-extra trail [OPTIONS]
Trace a simulated batch of operations behind an operation trail.
Roasts a handful of make-believe vegetables (each a short pause, the leeks
scorching) and reports them as they land. The display follows the batch: with
--jobs 1 each outcome echoes as a plain line; with two or more jobs a spinner
carries the running tally while outcomes stream above it; --progress-bar swaps
that spinner for a determinate progress bar. Add --time to append each
vegetable's roast time and the batch total; --elapsed and --eta turn that on
too, counting up from zero or down as an estimate. Honors --progress / --no-
progress and stays silent off an interactive terminal.
Options:
--progress-bar Drive the batch with a determinate progress bar
instead of a spinner.
--eta / --elapsed For --progress-bar, show the time remaining (--eta)
or elapsed (--elapsed); either one turns timing on,
like --time. A spinner always shows elapsed time.
--spinner NAME Aggregate spinner animation for concurrent runs
(see the spinner command for names). Defaults to
the built-in spinner; ignored with --progress-bar.
--jobs [auto|max|INTEGER] Number of parallel jobs. Accepts an integer, 'auto'
(the host's logical CPUs minus one) or 'max' (all
logical CPUs). 0 runs sequentially. [default:
auto]
-h, --help Show this message and exit.
click-extra wrap¶
$ click-extra wrap --help
Usage: click-extra wrap [OPTIONS] SCRIPT [ARGS]...
Aliases: run
Run, or introspect, any Click CLI through Click Extra.
By default, runs SCRIPT with keyword highlighting and themed styling for its
help screens. The target CLI is not modified.
With --params, --man, --tree or --help-format, SCRIPT is loaded and described
without being run. The first three answer a question a person is asking right
now; --help-format renders the target as an artifact for a program or a build
step. Extra arguments after SCRIPT navigate into nested subcommands; for
--params, any trailing options are replayed against the resolved command so
the parameter table reports their value and source.
Resolution order for SCRIPT: installed console_scripts entry point, a local
project directory (its entry point is read from pyproject.toml or setup.cfg),
Python file path, module:function notation, or Python module name.
Options:
--params Show the parameters of the target CLI and exit,
without running it.
--man Read the manual page of the target CLI and exit,
without running it.
--tree Show the tree of nested subcommands of the target CLI
and exit, without running it.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the target CLI in the given format and exit,
without running it.
--output-dir DIRECTORY With --help-format, write the rendering into this
directory instead of printing it. Created if missing.
--install With --help-format, write the rendering where its
consumer looks for it instead of printing it, and echo
the written path.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
With --params, the rendering style of the parameter
table. Falls back to the click-extra group's --table-
format when not set here. [default: rounded-outline]
--columns [id,spec,help,class,param_type,python_type,hidden,exposed,allowed_in_conf,envvars,default,is_flag,flag_value,is_bool_flag,multiple,nargs,prompt,confirmation_prompt,value,source,config_file]
Restrict and reorder table columns, SQL SELECT-style.
Comma-separated list of column IDs. Default: all
columns in canonical order.
-h, --help Show this message and exit.
Command |
Description |
|---|---|
Click Extra CLI |
|
Render all standard 8-color |
|
Render every foreground color against |
|
Convert reST docstrings to MyST markdown |
|
Render 24-bit RGB gradients vs |
|
Show help for a command |
|
Render a compact 256-color indexed swatch |
|
Pre-bake build-time metadata into Python |
|
Pre-bake |
|
Replace an empty dunder variable with a |
|
Show help for a command |
|
Inject Git commit hash into |
|
Refresh the self-updating blocks embedded |
|
Capture a command’s colored output and |
|
Animate the spinner widget; –table lists |
|
Render every color with each text style |
|
Run declarative CLI test cases against a |
|
Render a sample help screen under every |
|
Trace a simulated batch of operations |
|
Run, or introspect, any Click CLI through |
Configuration¶
The CLI reads its defaults from the [tool.click-extra] section of the nearest pyproject.toml, through click-extra’s own configuration machinery. The reference below is rendered live from its configuration schema:
prebake.module¶
Path to the __init__.py to pre-bake, resolved relative to the project root. Overrides the [project.scripts] auto-discovery; leave unset to keep it.
Type: str | Default: (none)
test-suite.cases¶
Test cases written natively in the config format, an alternative to a file suite, taking precedence over it when both are set.
Type: list[dict] | Default: []
Each entry is a mapping of CLITestCase directive names, equivalent to one
item of a suite list. In TOML this reads as a [[tool.<cli>.test-suite.cases]]
array of tables. Declared as an extension point so the configuration engine
passes the raw mappings through unprocessed; the test-suite command turns
them into CLITestCase instances.
Example:
[tool.click-extra]
test-suite.cases = []
test-suite.file¶
Path to a test suite file, resolved relative to the project root.
Type: str | Default: "./tests/cli-test-suite.toml"
Its format is detected from the extension; the default is TOML, which (like JSON) parses with no optional dependency, unlike YAML and the others.
Example:
[tool.click-extra]
test-suite.file = "./tests/cli-test-suite.toml"
test-suite.timeout¶
Default timeout (seconds) for each case that does not set its own.
Type: int | Default: (none)
None leaves cases unbounded unless --timeout is passed.
Option |
Description |
Default |
|---|---|---|
Path to the |
(none) |
|
Test cases written natively in the config format, an alternative to a |
|
|
Path to a test suite file, resolved relative to the project root. |
|
|
Default timeout (seconds) for each case that does not set its own. |
(none) |