Man-page¶
click_extra.command_doc extracts a command once, into a CommandDoc, and renders that model several ways. This page covers the man page: reading one, shipping one, and the man-pages(7) layout each section is built to. Machine-readable help covers the rest.
Generating man pages¶
Every man-page section is produced mechanically by click_extra.command_doc from the command itself. It works on any Click command object (no console_scripts entry point required) and walks the command tree, discovering subcommands dynamically, into one roff page per command. Literal tokens (command and option names) are set bold and replaceable tokens (metavars, operands) italic, following the literal and replaceable slots split; Click’s \b no-rewrap marker becomes a roff .nf / .fi block.
Reading a manual¶
The @man_option decorator adds a --man flag that typesets the command’s manual and sends it to the pager, the way man itself does. A CLI gets a manual to read whether or not anyone ever shipped one for it:
import click
from click_extra import help_format_option, man_option
@click.command
@man_option
@help_format_option
@click.option("--name", help="Who to greet.")
def greet(name):
"""Greet someone."""
click.echo(f"Hello, {name}!")
@man_option and @help_format_option are siblings: a plain Click command takes either or both, and a Click Extra one gets them among its default options.
$ greet --man
GREET(1) General Commands Manual GREET(1)
NAME
greet - Greet someone.
SYNOPSIS
greet [OPTIONS]
...
Typesetting goes through groff or mandoc, whichever is installed. Where neither is (Windows, a slim container), the roff source is printed instead with a warning naming what to install: something on screen beats an error, and the source still carries every word.
Under --accessible the pager is bypassed and the bold-and-underline overstrike is stripped, since a screen reader voices N\x08NA\x08AM\x08ME\x08E rather than skipping it.
Shipping a manual¶
--man reads; --help-format man emits the roff source a packager installs. The two are one question apart: do you want to read the manual, or to ship it?
$ greet --help-format man
.\" Generated by Click Extra 9.0.0.dev0 <https://github.com/kdeldycke/click-extra>. Do not edit by hand.
.TH "GREET" "1" "2026-08-17" "" ""
.SH NAME
greet \- Greet someone.
.SH SYNOPSIS
\fBgreet\fR \fI[OPTIONS]\fR
.SH DESCRIPTION
Greet someone.
.SH OPTIONS
.TP
\fB\-\-man\fR
Read the command's manual page and exit.
.TP
\fB\-\-help\-format\fR \fI[carapace|json|json\-full|man|markdown|markdown\-full]\fR
Render the command in the given format and exit.
.TP
\fB\-\-name\fR \fITEXT\fR
Who to greet.
.TP
\fB\-\-help\fR
Show this message and exit.
.SH "EXIT STATUS"
.TP
\fB0\fR
Success.
.TP
\fB1\fR
A runtime error, or an aborted prompt (Ctrl\-C, a declined confirmation).
.TP
\fB2\fR
A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.
The quickest way to produce a man page is wrap --man: click-extra wrap --man -- SCRIPT resolves the target, loads the Click command, and prints its roff page to stdout without running it. Trailing arguments drill into subcommands (click-extra wrap --man -- flask run). With uvx nothing needs to be installed up front:
$ uvx --from click-extra --with flask click-extra wrap --man -- flask > flask.1
Multiple pages¶
For multi-command CLIs, --output-dir DIR writes the whole command tree as one .1 file per (sub)command into DIR (created if missing). The output replaces stdout, so this is the right form for a release pipeline or a distributor’s build phase:
$ uvx --from click-extra --with flask click-extra wrap --man --output-dir /tmp/man -- flask
/tmp/man/flask.1
/tmp/man/flask-run.1
/tmp/man/flask-routes.1
/tmp/man/flask-shell.1
--output-dir (and --man) must appear before SCRIPT, since arguments after SCRIPT navigate into nested subcommands. Mixing --output-dir with a SUBCOMMAND argument is rejected: the flag always emits the whole tree of SCRIPT.
Target resolution¶
SCRIPT is accepted in five forms, tried in this order. The example above uses the first; the others reach the same Click command from a different starting point:
A
console_scriptsentry point exposed by an installed package, the form shown above (flaskships one in theflaskdistribution).A local project directory, resolved from its
pyproject.toml([project.scripts]) orsetup.cfg(console_scripts) entry point. Its package is added tosys.path, though its dependencies are not installed (see Dependencies of the wrapped CLI):$ click-extra wrap --man -- ../my-project > my-project.1
module:functionnotation pointing straight at a Click command object. Useful when the entry point is a wrapper rather than the command itself, or when the command isn’t exposed as a console script at all:$ uvx --from click-extra --with flask click-extra wrap --man -- flask.cli:cli > flask.1
A
.pyfile path. The file is imported in place, with no install step required, which is the right hook for source trees that don’t ship a Python build system (Autotools, Meson, Bazel):$ click-extra wrap --man -- path/to/my_cli.py > my_cli.1
A bare Python module name invocable via
python -m. The resolver imports the module and picks up the Click command from its top-level attributes:$ click-extra wrap --man -- my_package.cli > my_package.1
wrap resolves SCRIPT the same way in every mode, so any of these forms works whether you run, introspect (--params), or document (--man) the target.
Programmatic API¶
Three entry points cover the Python API, from one-shot rendering up to writing the whole tree. Dates honor SOURCE_DATE_EPOCH for reproducible builds:
render_manpage(cli)returns one page’s roff as a string. Use it when you want to pipe togroffor post-process the output before writing it:from click_extra import render_manpage print(render_manpage(cli))
render_manpages(cli)returns a{filename: roff}mapping covering the whole command tree. Use it when you need to filter, rename, or splice pages before writing them:from pathlib import Path from click_extra import render_manpages for filename, roff in render_manpages(cli).items(): Path("man", filename).write_text(roff)
write_manpages(cli, target_dir)writes one.1file per command directly to disk: the build-system hook. A Debian package wires it intodebian/rulesfrom itsoverride_dh_installman:override_dh_installman: python -c "from myapp.cli import cli; from click_extra import write_manpages; write_manpages(cli, 'debian/tmp/manpages')" dh_installman -O--buildsystem=pybuild
Sphinx integration¶
Projects already using the click_extra.sphinx extension can publish the same pages alongside their HTML docs with a single click_extra_manpages entry in conf.py: see Man pages. The Sphinx hook reuses write_manpages under the hood and optionally renders a browser-viewable HTML sibling next to each .1 so the standard :manpage: role can link to them.
Index¶
The list below is auto-generated by the click-extra-manpages directive: one link per (sub)command declared in this project’s click_extra_manpages config, pointing at the HTML sibling rendered alongside the docs.
```{click-extra-manpages}
```
click-extra(1)— Click Extra CLI.click-extra-8color(1)— Render all standard 8-color foreground/background combinations.click-extra-colors(1)— Render every foreground color against every background color.click-extra-convert-to-myst(1)— Convert reST docstrings to MyST markdown in Python source files.click-extra-gradient(1)— Render 24-bit RGB gradients vs. their 256-color quantized equivalents.click-extra-help(1)— Show help for a command.click-extra-palette(1)— Render a compact 256-color indexed swatch.click-extra-prebake(1)— Pre-bake build-time metadata into Python source files.click-extra-prebake-all(1)— Pre-bake `__version__` and all git fields in one pass.click-extra-prebake-field(1)— Replace an empty dunder variable with a value.click-extra-prebake-help(1)— Show help for a command.click-extra-prebake-version(1)— Inject Git commit hash into `__version__`.click-extra-refresh-directives(1)— Refresh the self-updating blocks embedded in Markdown files.click-extra-screenshot(1)— Capture a command’s colored output and write it as an image or HTML.click-extra-spinner(1)— Animate the spinner widget; –table lists the catalog instead.click-extra-styles(1)— Render every color with each text style (bold, dim, italic, etc.).click-extra-test-suite(1)— Run declarative CLI test cases against a command or binary.click-extra-themes(1)— Render a sample help screen under every built-in theme, one after another.click-extra-trail(1)— Trace a simulated batch of operations behind an operation trail.click-extra-wrap(1)— Run, or introspect, any Click CLI through Click Extra.
Layout¶
Unix tools are conventionally documented with the section layout of man-pages(7): a one-line NAME, a SYNOPSIS, a prose DESCRIPTION, an itemized OPTIONS list, then ENVIRONMENT, FILES, and EXIT STATUS. A Click Extra command already carries everything those sections need. This page documents one small CLI top-to-bottom in that order, with each section backed by output rendered live from the running command.
from click_extra import Choice, argument, command, echo, option
@command(context_settings={"show_envvar": True})
@argument("city", help="Name of the city to report on.")
@option(
"--units",
type=Choice(["celsius", "fahrenheit"]),
default="celsius",
help="Temperature scale to display.",
)
def weather(city, units):
"""Report the current temperature for a city."""
echo(f"{city}: 21 degrees {units}.")
NAME¶
A man page opens with a single name - one-line description line, the one apropos and whatis index. Click has no dedicated slot for it: the equivalent is the program name paired with the first line of the command’s docstring, which Click also uses as the command’s short help. For this CLI the pairing reads:
weather - report the current temperature for a city
SYNOPSIS¶
The Usage: line is the synopsis. Click Extra styles its tokens along the same typographic split a man page draws between bold literal text and italic replaceable text, documented in literal and replaceable slots: the literal command name weather against the replaceable CITY operand and the [OPTIONS] placeholder.
Click prints the synopsis as the first line of the help screen. The rest of that screen, dissected in the two sections below, supplies the DESCRIPTION and the OPTIONS list:
$ weather --help
Usage: weather [OPTIONS] CITY
Report the current temperature for a city.
Positional arguments:
CITY Name of the city to report on.
Options:
--units [celsius|fahrenheit] Temperature scale to display. [env var:
WEATHER_UNITS; default: celsius]
--time / --no-time Measure and print elapsed execution time. [env
var: WEATHER_TIME; default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[env var: WEATHER_CONFIG; default: ~/.config/wea
ther/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc
,*.hjson,*.ini,*.xml,pyproject.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables. [env var: WEATHER_CONFIG]
--validate-config FILE Validate the configuration file and exit. [env
var: WEATHER_VALIDATE_CONFIG]
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit. [env var:
WEATHER_EXPORT_CONFIG]
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format. [env var: WEATHER_ACCESSIBLE]
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [env var: WEATHER_COLOR;
default: auto]
--no-color Disable colorization (alias of --color=never).
[env var: WEATHER_NO_COLOR]
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [env var:
WEATHER_PROGRESS; default: progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [env var:
WEATHER_THEME; default: dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit. [env var:
WEATHER_PARAMS]
--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. [env var:
WEATHER_TABLE_FORMAT; default: rounded-outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[env var: WEATHER_VERBOSITY; default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [env var: WEATHER_VERBOSE; default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [env var: WEATHER_QUIET; default: 0]
--tree Show the tree of nested subcommands and exit.
[env var: WEATHER_TREE]
--man Read the command's manual page and exit. [env
var: WEATHER_MAN]
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
[env var: WEATHER_HELP_FORMAT]
--version Show the version and exit. [env var:
WEATHER_VERSION]
-h, --help Show this message and exit.
DESCRIPTION¶
The DESCRIPTION explains what the program does and, in prose, what its operands mean. Click Extra sources it from the command’s docstring, rendered just under the synopsis above: “Report the current temperature for a city.” The CITY operand is the city to report on.
When an argument carries a help= string, Click Extra also itemizes operands in a dedicated Positional arguments: block (the CITY entry above). That is a structured take on operands that goes beyond what man-pages(7) prescribes, which keeps their meaning in the prose description rather than in a list.
OPTIONS¶
The OPTIONS section is the formal, per-item description of each option, rendered as the Options: block above. Every entry pairs the option’s literal name (--units) and its replaceable metavar ([celsius|fahrenheit]) with the help text and a trailing bracket field carrying the option’s environment variable and default. Click Extra injects its own options into the same list (--config, --verbosity, --version, --help, …), so a CLI built on it gets a complete, conventional options section without extra work.
When a CLI sorts its options into groups with @option_group, each group becomes a .SS subsection of OPTIONS; the options left ungrouped, including the ones Click Extra injects, gather under a trailing Other options heading. This is the same split the --help screen draws:
from click_extra import command, option, option_group
@command
@option_group(
"Location",
option("--city", help="City to report on."),
option("--country", help="Two-letter country code."),
)
@option("--fahrenheit", is_flag=True, help="Report in the Fahrenheit scale.")
def forecast(city, country, fahrenheit):
"""Report a multi-day forecast."""
$ forecast --help-format man
.\" Generated by Click Extra 9.0.0.dev0 <https://github.com/kdeldycke/click-extra>. Do not edit by hand.
.TH "FORECAST" "1" "2026-08-17" "" ""
.SH NAME
forecast \- Report a multi\-day forecast.
.SH SYNOPSIS
\fBforecast\fR \fI[OPTIONS]\fR
.SH DESCRIPTION
Report a multi\-day forecast.
.SH OPTIONS
.SS "Location"
.TP
\fB\-\-city\fR \fITEXT\fR
City to report on.
.TP
\fB\-\-country\fR \fITEXT\fR
Two\-letter country code.
.SS "Other options"
.TP
\fB\-\-fahrenheit\fR
Report in the Fahrenheit scale.
.TP
\fB\-\-time\fR / \fB\-\-no\-time\fR
Measure and print elapsed execution time.
.TP
\fB\-\-config\fR \fICONFIG_PATH\fR
Location of the configuration file. Supports local path with glob patterns or remote URL.
.TP
\fB\-\-no\-config\fR
Ignore all configuration files and only use command line parameters and environment variables.
.TP
\fB\-\-validate\-config\fR \fIFILE\fR
Validate the configuration file and exit.
.TP
\fB\-\-export\-config\fR \fIFORMAT\fR
Export the configuration in the selected format to <stdout>, then exit.
.TP
\fB\-\-accessible\fR
Accessibility mode: disable colors and render tables in a borderless, screen\-reader\-friendly format.
.TP
\fB\-\-color\fR\fI[=auto|always|never]\fR
Colorize the output. A bare \-\-color is the same as \-\-color=always.
.TP
\fB\-\-no\-color\fR
Disable colorization (alias of \-\-color=never).
.TP
\fB\-\-progress\fR / \fB\-\-no\-progress\fR
Show progress indicators during long operations. Disabled for non\-interactive output (pipes, dumb terminals, CI) and by \-\-accessible.
.TP
\fB\-\-theme\fR \fI[auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]\fR
Color theme used for help screens.
.TP
\fB\-\-params\fR
Show all CLI parameters, their provenance, defaults and value, then exit.
.TP
\fB\-\-table\-format\fR \fI[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]\fR
Rendering style of tables.
.TP
\fB\-\-verbosity\fR \fILEVEL\fR
Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
.TP
\fB\-\-verbose\fR / \fB\-v\fR
Increase the default WARNING verbosity by one level for each additional repetition of the option.
.TP
\fB\-\-quiet\fR / \fB\-q\fR
Decrease the default WARNING verbosity by one level for each additional repetition of the option.
.TP
\fB\-\-tree\fR
Show the tree of nested subcommands and exit.
.TP
\fB\-\-man\fR
Read the command's manual page and exit.
.TP
\fB\-\-help\-format\fR \fI[carapace|json|json\-full|man|markdown|markdown\-full]\fR
Render the command in the given format and exit.
.TP
\fB\-\-version\fR
Show the version and exit.
.TP
\fB\-h\fR / \fB\-\-help\fR
Show this message and exit.
.SH ENVIRONMENT
.TP
\fBFORECAST_CITY\fR
City to report on.
.TP
\fBFORECAST_COUNTRY\fR
Two\-letter country code.
.TP
\fBFORECAST_FAHRENHEIT\fR
Report in the Fahrenheit scale.
.TP
\fBFORECAST_TIME\fR
Measure and print elapsed execution time.
.TP
\fBFORECAST_CONFIG\fR
Location of the configuration file. Supports local path with glob patterns or remote URL.
.TP
\fBFORECAST_VALIDATE_CONFIG\fR
Validate the configuration file and exit.
.TP
\fBFORECAST_EXPORT_CONFIG\fR
Export the configuration in the selected format to <stdout>, then exit.
.TP
\fBFORECAST_ACCESSIBLE\fR
Accessibility mode: disable colors and render tables in a borderless, screen\-reader\-friendly format.
.TP
\fBFORECAST_COLOR\fR
Colorize the output. A bare \-\-color is the same as \-\-color=always.
.TP
\fBFORECAST_NO_COLOR\fR
Disable colorization (alias of \-\-color=never).
.TP
\fBFORECAST_PROGRESS\fR
Show progress indicators during long operations. Disabled for non\-interactive output (pipes, dumb terminals, CI) and by \-\-accessible.
.TP
\fBFORECAST_THEME\fR
Color theme used for help screens.
.TP
\fBFORECAST_PARAMS\fR
Show all CLI parameters, their provenance, defaults and value, then exit.
.TP
\fBFORECAST_TABLE_FORMAT\fR
Rendering style of tables.
.TP
\fBFORECAST_VERBOSITY\fR
Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
.TP
\fBFORECAST_VERBOSE\fR
Increase the default WARNING verbosity by one level for each additional repetition of the option.
.TP
\fBFORECAST_QUIET\fR
Decrease the default WARNING verbosity by one level for each additional repetition of the option.
.TP
\fBFORECAST_TREE\fR
Show the tree of nested subcommands and exit.
.TP
\fBFORECAST_MAN\fR
Read the command's manual page and exit.
.TP
\fBFORECAST_HELP_FORMAT\fR
Render the command in the given format and exit.
.TP
\fBFORECAST_VERSION\fR
Show the version and exit.
.TP
\fBFORECAST_HELP\fR
Show this message and exit.
.SH FILES
.nf
\fI~/.config/forecast/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}\fR
.fi
.SH "EXIT STATUS"
.TP
\fB0\fR
Success.
.TP
\fB1\fR
A runtime error, or an aborted prompt (Ctrl\-C, a declined confirmation).
.TP
\fB2\fR
A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.
ENVIRONMENT¶
The ENVIRONMENT section lists the variables that change the program’s behavior. Click Extra derives one per option from the command name (the WEATHER_ prefix here) and surfaces it in the help screen’s bracket field ([env var: WEATHER_UNITS; …] above) when show_envvar is enabled. The variable is live: setting it feeds the option, ranked below the command line but above the default in the precedence chain.
$ export WEATHER_UNITS=fahrenheit
$ weather Paris
Paris: 21 degrees fahrenheit.
--params prints the full mapping at once: every parameter, the environment variable it reads, its default, its resolved value, and the source that value came from.
$ weather --params
╭─────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────────────┬───────────────────────────────────┬─────────────┬────────┬─────────┬──────────────────┬─────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────┬────────────────────┬──────────────┬──────────┬───────┬────────┬─────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────╮
│ ID │ Spec. │ Class │ Param type │ Python type │ Hidden │ Exposed │ Allowed in conf? │ Env. vars. │ Default │ Is flag │ Flag value │ Is bool flag │ Multiple │ Nargs │ Prompt │ Confirmation prompt │ Value │ Source │
├─────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────┼───────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────┼────────────────────┼──────────────┼──────────┼───────┼────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ weather.accessible │ --accessible │ click_extra.accessibility.AccessibleOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_ACCESSIBLE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ weather.city │ │ click_extra.parameters.Argument │ click.types.StringParamType │ str │ │ ✓ │ ✓ │ │ None │ │ │ │ ✘ │ 1 │ │ │ None │ DEFAULT │
│ weather.color │ --color [auto|always|never] │ click_extra.color.ColorOption │ click_extra.color.ColorWhenChoice │ str │ ✘ │ ✘ │ ✓ │ WEATHER_COLOR │ 'auto' │ ✘ │ 'always' │ ✘ │ ✘ │ 1 │ │ ✘ │ 'auto' │ DEFAULT │
│ weather.config │ --config CONFIG_PATH │ click_extra.config.option.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ WEATHER_CONFIG │ '/home/runner/.config/weather/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '/home/runner/.config/weather/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ DEFAULT │
│ weather.config │ --no-config │ click_extra.config.option.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ WEATHER_CONFIG │ None │ ✓ │ Sentinel.NO_CONFIG │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ weather.export_config │ --export-config FORMAT │ click_extra.config.option.ExportConfigOption │ click.types.Choice │ str │ ✘ │ ✘ │ ✘ │ WEATHER_EXPORT_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ weather.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ WEATHER_HELP │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ weather.help_format │ --help-format [carapace|json|json-full|man|markdown|markdown-full] │ click_extra.command_doc.HelpFormatOption │ click.types.Choice │ str │ ✘ │ ✘ │ ✓ │ WEATHER_HELP_FORMAT │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ weather.man │ --man │ click_extra.command_doc.ManOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_MAN │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ weather.no_color │ --no-color │ click_extra.color.NoColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_NO_COLOR │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ weather.params │ --params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ WEATHER_PARAMS │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ COMMANDLINE │
│ weather.progress │ --progress / --no-progress │ click_extra.spinner.ProgressOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_PROGRESS │ True │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ DEFAULT │
│ weather.quiet │ -q, --quiet │ click_extra.logging.QuietOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ WEATHER_QUIET │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ weather.table_format │ --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] │ click_extra.table.TableFormatOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ WEATHER_TABLE_FORMAT │ 'rounded-outline' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'rounded-outline' │ DEFAULT │
│ weather.theme │ --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ WEATHER_THEME │ 'dark' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'dark' │ DEFAULT │
│ weather.time │ --time / --no-time │ click_extra.execution.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_TIME │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ weather.tree │ --tree │ click_extra.tree.TreeOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_TREE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ weather.units │ --units [celsius|fahrenheit] │ click_extra.parameters.Option │ click.types.Choice │ str │ ✘ │ ✓ │ ✓ │ WEATHER_UNITS │ 'celsius' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'celsius' │ DEFAULT │
│ weather.validate_config │ --validate-config FILE │ click_extra.config.option.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✘ │ WEATHER_VALIDATE_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ weather.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ WEATHER_VERBOSE │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ weather.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ WEATHER_VERBOSITY │ 'WARNING' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'WARNING' │ DEFAULT │
│ weather.version │ --version │ click_extra.version.VersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ WEATHER_VERSION │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
╰─────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┴───────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────┴────────────────────┴──────────────┴──────────┴───────┴────────┴─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
FILES¶
The FILES section documents the files a program reads. Click Extra’s --config option resolves a per-platform search path, shown as its default in the OPTIONS block above: the application directory for weather followed by a glob over every supported format (*.toml, *.yaml, *.json, *.ini, *.xml, and pyproject.toml). See the configuration guide for the search order and the precedence rules that govern which file wins.
EXIT STATUS¶
The EXIT STATUS section documents the process return codes. Click Extra inherits Click’s conventional scheme:
Code |
Meaning |
|---|---|
|
Success. |
|
A runtime error, or an aborted prompt ( |
|
A usage error: unknown option, invalid value, missing operand, or an unparsable |
A successful run returns 0:
$ weather Paris
Paris: 21 degrees celsius.
An invalid choice is a usage error, so the command exits 2:
$ weather --units kelvin Paris
Usage: weather [OPTIONS] CITY
Try 'weather --help' for help.
Error: Invalid value for '--units' (env var: '('WEATHER_UNITS',)'): 'kelvin' is not one of 'celsius', 'fahrenheit'.
Other renderings¶
A man page is one of several ways the same extracted command renders. The others, and the --help-format option reaching all of them, are documented in machine-readable help: JSON and Markdown for a tool or a model to read, a Carapace spec for a shell to complete from.