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:
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--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]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--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.
Demo:
8color Render all standard 8-color foreground/background...
colors Render every foreground color against every background...
gradient Render 24-bit RGB gradients beside their 256-color...
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 each theme, one after...
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...
snippet Highlight a source file and write it as an image or HTML.
test-suite Run declarative CLI test cases against a command or...
wrap (run) Run, or introspect, any Click CLI through Click Extra.
Examples:
Run any Click CLI through Click Extra's colored help:
$ click-extra wrap -- my-cli --help
Draw that help screen as a picture a README can show:
$ click-extra screenshot --output my-cli.svg -- my-cli --help
Report the parameters a CLI accepts, and where each value comes from:
$ click-extra wrap --params -- my-cli
Highlight a source file as a themed picture:
$ click-extra snippet --output basket.svg basket.py
See how a help screen reads under each built-in theme:
$ click-extra themes
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:
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--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]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--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.
Examples:
Convert the docstrings of the package in the current directory:
$ click-extra convert-to-myst
Convert the docstrings under another one:
$ click-extra convert-to-myst src/basket
click-extra gradient¶
$ click-extra gradient --help
Usage: click-extra gradient [OPTIONS]
Render 24-bit RGB gradients beside 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__`, all git fields and all build fields in one...
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__`, all git fields and all build fields in one pass.
Scans each target file for empty `__<field>__` dunder placeholders, resolves
their values from the current Git state and build host, 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
Supported build fields:
build_time, build_os, build_target, build_target_arch
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.
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--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]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--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.
Examples:
Refresh every self-updating block of a documentation tree:
$ click-extra refresh-directives docs
Refresh one page:
$ click-extra refresh-directives docs/recipes.md
Report the stale ones without writing, for a continuous-integration job:
$ click-extra refresh-directives --check docs
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.
--record runs the command under a pseudo-terminal instead, and writes an
animated SVG of every screen it drew: the frames a spinner or a progress bar
asks a terminal for, which a plain capture never sees. The invocation is drawn
above every frame, and the loop pauses on the final screen for as long as its
line count asks, see --hold.
Options:
--output FILE Path of the file to write. Its extension picks
the format: .svg for an image, .html for
selectable text, .ansi for the escape sequences
themselves. Pass - to print those to the
terminal, which draws no window. [required]
--columns [auto|INTEGER] 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 COLOR 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 PIXELS Thickness of that frame, in pixels. [default: 1;
x>=0]
--radius PIXELS 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 COLOR 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 COLOR 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 PIXELS 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 PIXELS Pixels added inside the window, around the drawn
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.2.1]
--watermark-color COLOR 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.
--head INTEGER RANGE Keep only the first N lines. [x>=1]
--tail INTEGER RANGE Keep only the last N lines. [x>=1]
--truncation [auto|TEXT] Line standing in for what --head or --tail cut
away, or auto to rule one across the width the
kept lines span. [default: auto]
--line-numbers Number the drawn lines in a gutter, the way
Pygments does inline. Line 1 is the first line
the picture shows.
--emphasize-lines LINES Draw a band behind the lines named, as 2,4-5.
Counted from 1 as the picture draws them. Ranges
are closed: state both ends.
--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.
--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.
--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.
--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 SECONDS Seconds before the command is killed. Waits
forever by default. With --record, this is also
where the recording stops. [x>0]
--record Run the command under a pseudo-terminal and write
an animated SVG of the screens it draws, spinners
and progress bars included. Needs an .svg
--output and a numeric --columns. Unix only.
--rows INTEGER RANGE With --record, the height of the terminal the
command runs in, in characters. Defaults to 24.
[x>=1]
--hold [auto|FLOAT] With --record, extra seconds the last frame stays
up before the animation starts over, or auto to
scale them to that frame's line count. Defaults
to auto.
--blank SECONDS With --record, seconds of empty screen closing
the cycle. Defaults to 0.6. [x>=0]
--cursor [auto|block|bar|underline]
Draw a terminal cursor where the command left it.
Bare, it takes the shape the --preset terminal
draws; name one to override that. Omitted, no
cursor is drawn.
--blink SECONDS With --cursor, seconds one blink takes. Pass 0 to
draw a steady cursor. Defaults to 1.0. [x>=0]
--closing-prompt / --no-closing-prompt
Draw the shell's prompt on the row under the
output, where it comes back once the command
exits. Costs no height alongside --cursor, which
already leaves that row for the cursor to wait
on. [default: no-closing-prompt]
--typing SECONDS With --record, open the animation by typing the
command line out, this many seconds per
character. Omitted, the prompt stands there from
the first frame. [x>0]
--submit SECONDS With --typing, seconds the finished command line
waits before its output starts. Defaults to 0.4.
[x>0]
--speed FLOAT RANGE With --record, how much faster to play than
recorded: 2 halves every frame's time. Defaults
to 1.0. [x>0]
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--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]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--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.
Examples:
Draw a help screen as a picture a README can show:
$ click-extra screenshot --output my-cli.svg -- my-cli --help
Draw it as selectable text, for a page you own:
$ click-extra screenshot --output my-cli.html -- my-cli --help
Capture a CLI that is not built on Click Extra, colored all the same:
$ click-extra screenshot --output flask.svg --wrap -- flask run --help
Record the frames a spinner draws, as an animation:
$ click-extra screenshot --output ripen.svg --record --columns 80 -- ripen
click-extra snippet¶
$ click-extra snippet --help
Usage: click-extra snippet [OPTIONS] SOURCE
Highlight a source file and write it as an image or HTML.
Colors SOURCE with Pygments, then draws it in the same window a captured
command is drawn in. Pass - to read the source from stdin, which needs
--language: there is no file name left to guess from.
click-extra snippet --output ripen.svg ripen.py
The window is painted the background the syntax style was designed against, so
a snippet looks like that theme does in an editor rather than like the same
theme dropped on a foreign surface.
Both formats are the screenshot command's:
- .svg: a picture, for a surface that strips inline HTML;
- .html: selectable, searchable, copy-pasteable text.
Highlighting needs the pygments extra.
Options:
--output FILE Path of the file to write. Its extension picks
the format: .svg for an image, .html for
selectable text, .ansi for the escape sequences
themselves. Pass - to print those to the
terminal, which draws no window. [required]
--columns [auto|INTEGER] Width, in characters, the image is laid out at.
Pass auto to take the longest line the source
holds, so nothing folds: a file was never wrapped
to a terminal's width, and code that soft-wrapped
in the picture would lose the indentation a
reader is there to read. [default: auto]
--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 COLOR 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 PIXELS Thickness of that frame, in pixels. [default: 1;
x>=0]
--radius PIXELS 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 COLOR 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 COLOR 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 PIXELS 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 PIXELS Pixels added inside the window, around the drawn
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.2.1]
--watermark-color COLOR 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.
--head INTEGER RANGE Keep only the first N lines. [x>=1]
--tail INTEGER RANGE Keep only the last N lines. [x>=1]
--truncation [auto|TEXT] Line standing in for what --head or --tail cut
away, or auto to rule one across the width the
kept lines span. [default: auto]
--line-numbers Number the drawn lines in a gutter, the way
Pygments does inline. Line 1 is the first line
the picture shows.
--emphasize-lines LINES Draw a band behind the lines named, as 2,4-5.
Counted from 1 as the picture draws them. Ranges
are closed: state both ends.
--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.
--language TEXT Language the source is highlighted as, as
Pygments names it. Guessed from the file name,
then from the content, when left out. See
https://pygments.org/languages/ for the ones it
knows.
--syntax-style STYLE Pygments style the source is colored with, which
also paints the window: a style states the
background its colors were designed against.
Defaults to monokai on the dark chrome and to
Pygments' own default on the light one.
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--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]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--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.
Examples:
Draw a source file as a picture a README can show:
$ click-extra snippet --output basket.svg basket.py
Draw it as selectable text, under a named theme:
$ click-extra snippet --output basket.html --theme dracula basket.py
Number the lines and point at the one that matters:
$ click-extra snippet --output basket.svg --line-numbers --emphasize-lines 12 basket.py
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 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 PLATFORM 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 DIRECTORY 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]
--jobs [auto|max|INTEGER] Number of parallel jobs. Accepts an integer,
auto (the host's logical CPUs minus one) or
max (all logical CPUs). --jobs 0 runs
sequentially. [default: auto]
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected
format to <stdout>, then exit.
Output options:
--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]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--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.
Examples:
Run the built-in default suite against a CLI:
$ click-extra test-suite --command my-cli
Run the cases a file declares, one at a time, stopping on the first failure:
$ click-extra test-suite --command my-cli --suite-file cases.yaml --jobs 1 --exit-on-error
Run two of them, skipping the cases a platform cannot answer:
$ click-extra test-suite --command my-cli --select-test 3 --select-test 7 --skip-platform windows
click-extra themes¶
$ click-extra themes --help
Usage: click-extra themes [OPTIONS] [auto|THEME]...
Render a sample help screen under each theme, one after another.
Each 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.
Without an argument the whole registry is rendered, alphabetically: the built-
in palettes, plus any a configuration file defines. Name palettes to render
only those, in the order given. The auto value stands for the palette the
terminal background resolves to, as it does on --theme.
Positional arguments:
[auto|THEME]... Palettes to render, in the order given. Defaults to all of
them.
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). --jobs 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 FORMAT 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 COLUMNS 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.
Examples:
Run a CLI with Click Extra's colored help:
$ click-extra wrap -- my-cli --help
Read the help of one of its subcommands:
$ click-extra wrap -- my-cli pick --help
Report what a subcommand accepts, and where each value comes from:
$ click-extra wrap --params -- my-cli pick
Write a shell-completion spec where its consumer looks for it:
$ click-extra wrap --help-format carapace --install -- my-cli
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 beside their |
|
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 |
|
Highlight a source file and write it as an |
|
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 each |
|
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) |