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.1.1.dev0 <https://github.com/kdeldycke/click-extra>. Do not edit by hand.
.TH "GREET" "1" "2026-09-09" "" ""
.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 --help-format man: click-extra wrap --help-format 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 --help-format man -- flask run). With uvx nothing needs to be installed up front:
$ uvx --from click-extra --with flask click-extra wrap --help-format 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 --help-format 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 --help-format) 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 --help-format 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 --help-format 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 --help-format 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 --help-format 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 (--help-format 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¶
A project already building its documentation with the click_extra.sphinx extension emits the same pages from that build, with one click_extra_manpages entry in conf.py. See from a Sphinx build.
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 beside 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__`, all git fields and all build 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-snippet(1)— Highlight a source file 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.
From a Sphinx build¶
The Sphinx extension can render the roff man page tree of any Click CLI alongside the HTML build, so a project’s docs site, release pipeline, and downstream packagers all share a single generator. Add one or more entries to click_extra_manpages in conf.py:
conf.py¶extensions = ["click_extra.sphinx"]
click_extra_manpages = [
{
"script": "my_pkg.cli:my_cli", # required
"prog_name": "my-cli", # optional, defaults to the resolved command's name
"output_dir": "man", # optional, defaults to "man"
"render_html": True, # optional, defaults to True
},
]
On every HTML build, the hook resolves each script with the same scanner as the click-extra wrap --help-format man CLI and writes one .1 file per (sub)command into <outdir>/<output_dir>/, mirroring what click-extra wrap --help-format man --output-dir DIR -- SCRIPT produces from the command line. An empty (or absent) list keeps the hook silent: no man pages, no warnings.
Only HTML-family builders (html, dirhtml, singlehtml) trigger the hook. Other builders (linkcheck, man, epub, coverage) skip it: roff in their output trees would be redundant or confusing.
The generator honors SOURCE_DATE_EPOCH for reproducible builds and inherits every option-group and Cloup-aware rendering rule documented in the layout reference.
HTML siblings¶
Browsers download .1 files rather than render them, so each emitted page is also passed through a roff → HTML renderer when one is available. The result lands next to the source as <page>.<section>.html (like my-cli.1.html).
The hook tries mandoc -Thtml first, then groff -Thtml -mandoc, picking whichever it finds on PATH. mandoc is preferred for its semantic anchors: every section and option gets a stable id, which makes deep-linking work. If neither renderer is installed, the build still produces the .1 files and logs a single info-level notice, which render_html: False suppresses.
A typical CI container ships one or the other: Debian and Ubuntu have groff in build-essential, BSDs and recent macOS images ship mandoc. To pin the renderer on GitHub Actions, install it explicitly:
.github/workflows/docs.yaml¶- name: Install mandoc
run: sudo apt-get install --yes mandoc
Cross-linking from prose¶
To make the standard :manpage: role link to the HTML siblings the hook emits, set Sphinx’s manpages_url to the matching path:
conf.py¶manpages_url = "man/{page}.{section}.html"
With that in place, :manpage:`my-cli(1)` in any docstring or .md file resolves to man/my-cli.1.html in the rendered docs. The same template covers every subcommand page, since {page} matches the full hyphenated name the generator produces (my-cli, my-cli-build, my-cli-build-all).
Leaving manpages_url unset is fine. The role still renders as styled text; only the hyperlink target is missing.
click-extra-manpages directive¶
For a discoverable landing page, drop the click-extra-manpages directive anywhere in the docs. It walks click_extra_manpages and emits a bullet list with one entry per (sub)command in each declared tree, linked to the HTML sibling produced by the hook:
```{click-extra-manpages}
```
The directive takes no arguments. URLs are computed relative to the enclosing page’s actual published location, not its source docname, so the same call resolves correctly on a top-level page, on a page nested under a subdirectory, and under any HTML-family builder: dirhtml publishes each page one directory deeper, as <docname>/index.html rather than <docname>.html, while singlehtml folds every document into one page at the build root, so its links need no directory traversal at all. When click_extra_manpages is empty, the directive renders nothing.
A live instance of the directive ships in the index above: the list there is what this project’s own click_extra_manpages entry produces at build time.
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]
-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.
[env var: WEATHER_CONFIG; default:
~/.config/weather/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables. [env var: WEATHER_CONFIG]
--validate-config LOCATION 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]
Output options:
--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]
--table-format FORMAT Rendering style of tables. [env var:
WEATHER_TABLE_FORMAT; default: rounded-outline]
Logging options:
--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]
--debug Shorthand for --verbosity DEBUG. [env var:
WEATHER_DEBUG]
Introspection options:
--time / --no-time Measure and print elapsed execution time. [env
var: WEATHER_TIME; default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit. [env var:
WEATHER_PARAMS]
--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]
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 section (--config, --verbosity, --version, --help, …), so a CLI built on it gets a complete, conventional options section without extra work.
Each option group becomes a .SS subsection of OPTIONS, which is the same split the --help screen draws. Click Extra’s own options are grouped, so OPTIONS always carries the four subsections they are sorted into. A CLI adding groups of its own with @option_group gets them first, and the options it leaves ungrouped gather between the two under an Other options heading:
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.1.1.dev0 <https://github.com/kdeldycke/click-extra>. Do not edit by hand.
.TH "FORECAST" "1" "2026-09-09" "" ""
.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\-\-help\fR / \fB\-h\fR
Show this message and exit.
.SS "Configuration options"
.TP
\fB\-\-config\fR \fILOCATION\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 \fILOCATION\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.
.br
[values: toml, yaml, json, json5, jsonc, hjson, xml, plist]
.SS "Output options"
.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\-\-table\-format\fR \fIFORMAT\fR
Rendering style of tables.
.br
[values: 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]
.SS "Logging options"
.TP
\fB\-\-verbosity\fR \fILEVEL\fR
Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
.br
[values: 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\-\-debug\fR
Shorthand for \-\-verbosity DEBUG.
.SS "Introspection options"
.TP
\fB\-\-time\fR / \fB\-\-no\-time\fR
Measure and print elapsed execution time.
.TP
\fB\-\-params\fR
Show all CLI parameters, their provenance, defaults and value, then exit.
.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.
.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__CLICK_DEFAULT_HELP\fR
Show this message and exit.
.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_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_DEBUG\fR
Shorthand for \-\-verbosity DEBUG.
.TP
\fBFORECAST_TIME\fR
Measure and print elapsed execution time.
.TP
\fBFORECAST_PARAMS\fR
Show all CLI parameters, their provenance, defaults and value, then exit.
.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.
.SH FILES
.nf
\fI~/.config/forecast/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jwcc,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,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.
$ 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._click_default_help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ WEATHER__CLICK_DEFAULT_HELP │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ 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 LOCATION │ click_extra.config.option.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ WEATHER_CONFIG │ '/home/runner/.config/weather/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jwcc,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '/home/runner/.config/weather/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jwcc,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,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.debug │ --debug │ click_extra.logging.DebugOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ WEATHER_DEBUG │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ 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_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 FORMAT │ 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 LOCATION │ click_extra.config.option.ValidateConfigOption │ click.types.UnprocessedParamType │ 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.