Parameters¶
Click Extra implements tools to manipulate your CLI’s parameters, options and arguments.
The cornerstone of these tools is the magical --params option, which is a X-ray scanner for your CLI’s parameters.
--params option¶
Click Extra adds a --params flag to every @command and @group. It dumps a colorized table of every parameter, its current value, where that value came from, the resolved environment variable, and the default:
from click_extra import command, option, echo
@command
@option("--int-param1", type=int, default=10)
@option("--int-param2", type=int, default=555)
def cli(int_param1, int_param2):
echo(f"int_param1 is {int_param1!r}")
echo(f"int_param2 is {int_param2!r}")
$ cli --int-param1 3 --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 │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────┼───────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────┼────────────────────┼──────────────┼──────────┼───────┼────────┼─────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ cli.accessible │ --accessible │ click_extra.accessibility.AccessibleOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_ACCESSIBLE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.color │ --color [auto|always|never] │ click_extra.color.ColorOption │ click_extra.color.ColorWhenChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_COLOR │ 'auto' │ ✘ │ 'always' │ ✘ │ ✘ │ 1 │ │ ✘ │ 'auto' │ DEFAULT │
│ cli.config │ --config CONFIG_PATH │ click_extra.config.option.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │ DEFAULT │
│ cli.config │ --no-config │ click_extra.config.option.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ None │ ✓ │ Sentinel.NO_CONFIG │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.export_config │ --export-config FORMAT │ click_extra.config.option.ExportConfigOption │ click.types.Choice │ str │ ✘ │ ✘ │ ✘ │ CLI_EXPORT_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_HELP │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.help_format │ --help-format [carapace|json|json-full|man|markdown|markdown-full] │ click_extra.command_doc.HelpFormatOption │ click.types.Choice │ str │ ✘ │ ✘ │ ✓ │ CLI_HELP_FORMAT │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.int_param1 │ --int-param1 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM1 │ 10 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '3' │ COMMANDLINE │
│ cli.int_param2 │ --int-param2 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM2 │ 555 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 555 │ DEFAULT │
│ cli.man │ --man │ click_extra.command_doc.ManOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_MAN │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.no_color │ --no-color │ click_extra.color.NoColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_NO_COLOR │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.params │ --params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_PARAMS │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ COMMANDLINE │
│ cli.progress │ --progress / --no-progress │ click_extra.spinner.ProgressOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_PROGRESS │ True │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ DEFAULT │
│ cli.quiet │ -q, --quiet │ click_extra.logging.QuietOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_QUIET │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.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 │ ✘ │ ✘ │ ✓ │ CLI_TABLE_FORMAT │ 'rounded-outline' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'rounded-outline' │ DEFAULT │
│ cli.theme │ --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_THEME │ 'dark' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'dark' │ DEFAULT │
│ cli.time │ --time / --no-time │ click_extra.execution.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TIME │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.tree │ --tree │ click_extra.tree.TreeOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TREE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.validate_config │ --validate-config FILE │ click_extra.config.option.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✘ │ CLI_VALIDATE_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_VERBOSE │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_VERBOSITY │ 'WARNING' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'WARNING' │ DEFAULT │
│ cli.version │ --version │ click_extra.version.VersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_VERSION │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┴───────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────┴────────────────────┴──────────────┴──────────┴───────┴────────┴─────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
--int-param1 shows 3 because it was passed on the command line. --int-param2 falls back to its 555 default. The --params option produces this table dynamically: every value is re-evaluated at invocation time from the current argv, environment, and config files.
Tip
Every command built with @command or @group captures the pre-parsed argv slice on ctx.meta as RAW_ARGS, which --params itself relies on to re-parse the original arguments. See the available keys table to read it from your own callbacks.
Hint
--params always displays all parameters, even those marked as not allowed in conf. In effect bypassing the excluded_params argument. So you can still see the --help, --version, -C/--config and --params options in the table.
Available columns¶
Each row in the table mirrors a single click.Parameter instance. The columns map to its public attributes (plus a handful of Click Extra-specific fields). The table below is auto-generated at build time from ShowParamsOption.TABLE_HEADERS: edit the ColumnSpec.description entries in click_extra/parameters.py to update it.
Column |
Description |
|---|---|
|
Fully-qualified parameter path ( |
|
Option/argument specification string (like |
|
The parameter’s own help text, as written by the CLI author. Opt-in: it is the only column carrying free-form prose, so it stays out of the default table and is selected by ID ( |
|
Fully-qualified class of the parameter: a subclass of |
|
Click value converter class: a subclass of |
|
Python built-in type the parsed value resolves to: |
|
Reflects |
|
Reflects |
|
Click Extra-specific: whether the parameter is reachable from a configuration file. Controlled by |
|
Environment variables read for this parameter: the explicit |
|
Default value returned by |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Current value of the parameter at invocation time, computed by |
|
Provenance of the resolved value: a |
|
The configuration file the effective value was loaded from, when |
Columns selection¶
Add Click Extra’s columns_option to your CLI so users can pick which columns --params emits, in the order they want, SQL SELECT-style:
$ cli-with-columns --no-color --columns id,is_flag,default,value --params
╭──────────────────────────────────┬─────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ID │ Is flag │ Default │ Value │
├──────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ cli-with-columns.accessible │ ✓ │ False │ False │
│ cli-with-columns.color │ ✘ │ 'auto' │ 'auto' │
│ cli-with-columns.columns │ ✘ │ () │ 'id,is_flag,default,value' │
│ cli-with-columns.config │ ✘ │ '/home/runner/.config/cli-with-columns/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │ '/home/runner/.config/cli-with-columns/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │
│ cli-with-columns.config │ ✓ │ None │ None │
│ cli-with-columns.export_config │ ✘ │ None │ None │
│ cli-with-columns.help │ ✓ │ False │ False │
│ cli-with-columns.help_format │ ✘ │ None │ None │
│ cli-with-columns.int_param1 │ ✘ │ 10 │ 10 │
│ cli-with-columns.int_param2 │ ✘ │ 555 │ 555 │
│ cli-with-columns.man │ ✓ │ False │ False │
│ cli-with-columns.no_color │ ✓ │ False │ True │
│ cli-with-columns.params │ ✓ │ False │ True │
│ cli-with-columns.progress │ ✓ │ True │ True │
│ cli-with-columns.quiet │ ✘ │ 0 │ 0 │
│ cli-with-columns.table_format │ ✘ │ 'rounded-outline' │ 'rounded-outline' │
│ cli-with-columns.theme │ ✘ │ 'dark' │ 'dark' │
│ cli-with-columns.time │ ✓ │ False │ False │
│ cli-with-columns.tree │ ✓ │ False │ False │
│ cli-with-columns.validate_config │ ✘ │ None │ None │
│ cli-with-columns.verbose │ ✘ │ 0 │ 0 │
│ cli-with-columns.verbosity │ ✘ │ 'WARNING' │ 'WARNING' │
│ cli-with-columns.version │ ✓ │ False │ False │
╰──────────────────────────────────┴─────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Unknown IDs raise a BadParameter listing the valid ones (--columns is built on top of the generic MultiChoice type, which does the validation at parse time). The standalone click-extra wrap --params exposes the same option for inspecting third-party CLIs.
One column is opt-in: Help carries each parameter’s own help text, the only free-form prose in the table, and would squeeze every other column out of shape if it showed up uninvited. Select it by ID to get it:
$ cli-with-columns --no-color --columns id,spec,help --params
╭──────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ID │ Spec. │ Help │
├──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ cli-with-columns.accessible │ --accessible │ Accessibility mode: disable colors and render tables in a borderless, screen-reader-friendly format. │
│ cli-with-columns.color │ --color [auto|always|never] │ Colorize the output. A bare --color is the same as --color=always. │
│ cli-with-columns.columns │ --columns COLUMNS │ Restrict and reorder table columns, SQL SELECT-style. Comma-separated list of column IDs. Default: all columns in canonical order. │
│ cli-with-columns.config │ --config CONFIG_PATH │ Location of the configuration file. Supports local path with glob patterns or remote URL. │
│ cli-with-columns.config │ --no-config │ Ignore all configuration files and only use command line parameters and environment variables. │
│ cli-with-columns.export_config │ --export-config FORMAT │ Export the configuration in the selected format to <stdout>, then exit. │
│ cli-with-columns.help │ -h, --help │ Show this message and exit. │
│ cli-with-columns.help_format │ --help-format [carapace|json|json-full|man|markdown|markdown-full] │ Render the command in the given format and exit. │
│ cli-with-columns.int_param1 │ --int-param1 INTEGER │ [default: 10] │
│ cli-with-columns.int_param2 │ --int-param2 INTEGER │ [default: 555] │
│ cli-with-columns.man │ --man │ Read the command's manual page and exit. │
│ cli-with-columns.no_color │ --no-color │ Disable colorization (alias of --color=never). │
│ cli-with-columns.params │ --params │ Show all CLI parameters, their provenance, defaults and value, then exit. │
│ cli-with-columns.progress │ --progress / --no-progress │ Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible. │
│ cli-with-columns.quiet │ -q, --quiet │ Decrease the default WARNING verbosity by one level for each additional repetition of the option. │
│ cli-with-columns.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] │ Rendering style of tables. │
│ cli-with-columns.theme │ --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark] │ Color theme used for help screens. │
│ cli-with-columns.time │ --time / --no-time │ Measure and print elapsed execution time. │
│ cli-with-columns.tree │ --tree │ Show the tree of nested subcommands and exit. │
│ cli-with-columns.validate_config │ --validate-config FILE │ Validate the configuration file and exit. │
│ cli-with-columns.verbose │ -v, --verbose │ Increase the default WARNING verbosity by one level for each additional repetition of the option. │
│ cli-with-columns.verbosity │ --verbosity LEVEL │ Either CRITICAL, ERROR, WARNING, INFO, DEBUG. │
│ cli-with-columns.version │ --version │ Show the version and exit. │
╰──────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
As structured data¶
--params speaks every structured format, which turns the table into a description of the CLI a tool can consume. It is what makes a Click Extra command introspectable by something other than a reader:
$ cli-with-columns --table-format json --columns id,spec,help,default,envvars --params
[
{
"ID": "cli-with-columns.accessible",
"Spec.": "--accessible",
"Help": "Accessibility mode: disable colors and render tables in a borderless, screen-reader-friendly format.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_ACCESSIBLE"
]
},
{
"ID": "cli-with-columns.color",
"Spec.": "--color [auto|always|never]",
"Help": "Colorize the output. A bare --color is the same as --color=always.",
"Default": "auto",
"Env. vars.": [
"CLI_WITH_COLUMNS_COLOR"
]
},
{
"ID": "cli-with-columns.columns",
"Spec.": "--columns COLUMNS",
"Help": "Restrict and reorder table columns, SQL SELECT-style. Comma-separated list of column IDs. Default: all columns in canonical order.",
"Default": "()",
"Env. vars.": [
"CLI_WITH_COLUMNS_COLUMNS"
]
},
{
"ID": "cli-with-columns.config",
"Spec.": "--config CONFIG_PATH",
"Help": "Location of the configuration file. Supports local path with glob patterns or remote URL.",
"Default": "/home/runner/.config/cli-with-columns/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}",
"Env. vars.": [
"CLI_WITH_COLUMNS_CONFIG"
]
},
{
"ID": "cli-with-columns.config",
"Spec.": "--no-config",
"Help": "Ignore all configuration files and only use command line parameters and environment variables.",
"Default": null,
"Env. vars.": [
"CLI_WITH_COLUMNS_CONFIG"
]
},
{
"ID": "cli-with-columns.export_config",
"Spec.": "--export-config FORMAT",
"Help": "Export the configuration in the selected format to <stdout>, then exit.",
"Default": null,
"Env. vars.": [
"CLI_WITH_COLUMNS_EXPORT_CONFIG"
]
},
{
"ID": "cli-with-columns.help",
"Spec.": "-h, --help",
"Help": "Show this message and exit.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_HELP"
]
},
{
"ID": "cli-with-columns.help_format",
"Spec.": "--help-format [carapace|json|json-full|man|markdown|markdown-full]",
"Help": "Render the command in the given format and exit.",
"Default": null,
"Env. vars.": [
"CLI_WITH_COLUMNS_HELP_FORMAT"
]
},
{
"ID": "cli-with-columns.int_param1",
"Spec.": "--int-param1 INTEGER",
"Help": "[default: 10]",
"Default": 10,
"Env. vars.": [
"CLI_WITH_COLUMNS_INT_PARAM1"
]
},
{
"ID": "cli-with-columns.int_param2",
"Spec.": "--int-param2 INTEGER",
"Help": "[default: 555]",
"Default": 555,
"Env. vars.": [
"CLI_WITH_COLUMNS_INT_PARAM2"
]
},
{
"ID": "cli-with-columns.man",
"Spec.": "--man",
"Help": "Read the command's manual page and exit.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_MAN"
]
},
{
"ID": "cli-with-columns.no_color",
"Spec.": "--no-color",
"Help": "Disable colorization (alias of --color=never).",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_NO_COLOR"
]
},
{
"ID": "cli-with-columns.params",
"Spec.": "--params",
"Help": "Show all CLI parameters, their provenance, defaults and value, then exit.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_PARAMS"
]
},
{
"ID": "cli-with-columns.progress",
"Spec.": "--progress / --no-progress",
"Help": "Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.",
"Default": true,
"Env. vars.": [
"CLI_WITH_COLUMNS_PROGRESS"
]
},
{
"ID": "cli-with-columns.quiet",
"Spec.": "-q, --quiet",
"Help": "Decrease the default WARNING verbosity by one level for each additional repetition of the option.",
"Default": 0,
"Env. vars.": [
"CLI_WITH_COLUMNS_QUIET"
]
},
{
"ID": "cli-with-columns.table_format",
"Spec.": "--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]",
"Help": "Rendering style of tables.",
"Default": "rounded-outline",
"Env. vars.": [
"CLI_WITH_COLUMNS_TABLE_FORMAT"
]
},
{
"ID": "cli-with-columns.theme",
"Spec.": "--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]",
"Help": "Color theme used for help screens.",
"Default": "dark",
"Env. vars.": [
"CLI_WITH_COLUMNS_THEME"
]
},
{
"ID": "cli-with-columns.time",
"Spec.": "--time / --no-time",
"Help": "Measure and print elapsed execution time.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_TIME"
]
},
{
"ID": "cli-with-columns.tree",
"Spec.": "--tree",
"Help": "Show the tree of nested subcommands and exit.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_TREE"
]
},
{
"ID": "cli-with-columns.validate_config",
"Spec.": "--validate-config FILE",
"Help": "Validate the configuration file and exit.",
"Default": null,
"Env. vars.": [
"CLI_WITH_COLUMNS_VALIDATE_CONFIG"
]
},
{
"ID": "cli-with-columns.verbose",
"Spec.": "-v, --verbose",
"Help": "Increase the default WARNING verbosity by one level for each additional repetition of the option.",
"Default": 0,
"Env. vars.": [
"CLI_WITH_COLUMNS_VERBOSE"
]
},
{
"ID": "cli-with-columns.verbosity",
"Spec.": "--verbosity LEVEL",
"Help": "Either CRITICAL, ERROR, WARNING, INFO, DEBUG.",
"Default": "WARNING",
"Env. vars.": [
"CLI_WITH_COLUMNS_VERBOSITY"
]
},
{
"ID": "cli-with-columns.version",
"Spec.": "--version",
"Help": "Show the version and exit.",
"Default": false,
"Env. vars.": [
"CLI_WITH_COLUMNS_VERSION"
]
}
]
Values come out as native types here (10, not "10"), and the Help column makes each row self-describing. This is the state of one invocation; for the command’s own interface (its description, usage line, subcommands and examples), --help-format covers what a parameter table cannot. Machine-readable help sets the two side by side.
Table format¶
The default table produced by --params can be a bit overwhelming, so you can change its rendering with the --table-format option:
$ cli --table-format vertical --params
***************************[ 1. row ]***************************
ID | cli.accessible
Spec. | --accessible
Class | click_extra.accessibility.AccessibleOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_ACCESSIBLE
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 2. row ]***************************
ID | cli.color
Spec. | --color [auto|always|never]
Class | click_extra.color.ColorOption
Param type | click_extra.color.ColorWhenChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_COLOR
Default | 'auto'
Is flag | ✘
Flag value | 'always'
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'auto'
Source | DEFAULT
***************************[ 3. row ]***************************
ID | cli.config
Spec. | --config CONFIG_PATH
Class | click_extra.config.option.ConfigOption
Param type | click.types.UnprocessedParamType
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_CONFIG
Default | '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}'
Source | DEFAULT
***************************[ 4. row ]***************************
ID | cli.config
Spec. | --no-config
Class | click_extra.config.option.NoConfigOption
Param type | click.types.UnprocessedParamType
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_CONFIG
Default | None
Is flag | ✓
Flag value | Sentinel.NO_CONFIG
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source | DEFAULT
***************************[ 5. row ]***************************
ID | cli.export_config
Spec. | --export-config FORMAT
Class | click_extra.config.option.ExportConfigOption
Param type | click.types.Choice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_EXPORT_CONFIG
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source | DEFAULT
***************************[ 6. row ]***************************
ID | cli.help
Spec. | -h, --help
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_HELP
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 7. row ]***************************
ID | cli.help_format
Spec. | --help-format [carapace|json|json-full|man|markdown|markdown-full]
Class | click_extra.command_doc.HelpFormatOption
Param type | click.types.Choice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_HELP_FORMAT
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source | DEFAULT
***************************[ 8. row ]***************************
ID | cli.int_param1
Spec. | --int-param1 INTEGER
Class | click_extra.parameters.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Exposed | ✓
Allowed in conf? | ✓
Env. vars. | CLI_INT_PARAM1
Default | 10
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 10
Source | DEFAULT
***************************[ 9. row ]***************************
ID | cli.int_param2
Spec. | --int-param2 INTEGER
Class | click_extra.parameters.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Exposed | ✓
Allowed in conf? | ✓
Env. vars. | CLI_INT_PARAM2
Default | 555
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 555
Source | DEFAULT
***************************[ 10. row ]***************************
ID | cli.man
Spec. | --man
Class | click_extra.command_doc.ManOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_MAN
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 11. row ]***************************
ID | cli.no_color
Spec. | --no-color
Class | click_extra.color.NoColorOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_NO_COLOR
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 12. row ]***************************
ID | cli.params
Spec. | --params
Class | click_extra.parameters.ShowParamsOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_PARAMS
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | True
Source | COMMANDLINE
***************************[ 13. row ]***************************
ID | cli.progress
Spec. | --progress / --no-progress
Class | click_extra.spinner.ProgressOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_PROGRESS
Default | True
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | True
Source | DEFAULT
***************************[ 14. row ]***************************
ID | cli.quiet
Spec. | -q, --quiet
Class | click_extra.logging.QuietOption
Param type | click.types.IntRange
Python type | int
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_QUIET
Default | 0
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 0
Source | DEFAULT
***************************[ 15. row ]***************************
ID | cli.table_format
Spec. | --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]
Class | click_extra.table.TableFormatOption
Param type | click_extra.types.EnumChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_TABLE_FORMAT
Default | 'rounded-outline'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'vertical'
Source | COMMANDLINE
***************************[ 16. row ]***************************
ID | cli.theme
Spec. | --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark]
Class | click_extra.theme.ThemeOption
Param type | click_extra.theme.ThemeChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_THEME
Default | 'dark'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'dark'
Source | DEFAULT
***************************[ 17. row ]***************************
ID | cli.time
Spec. | --time / --no-time
Class | click_extra.execution.TimerOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_TIME
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 18. row ]***************************
ID | cli.tree
Spec. | --tree
Class | click_extra.tree.TreeOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_TREE
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 19. row ]***************************
ID | cli.validate_config
Spec. | --validate-config FILE
Class | click_extra.config.option.ValidateConfigOption
Param type | click.types.Path
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_VALIDATE_CONFIG
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source | DEFAULT
***************************[ 20. row ]***************************
ID | cli.verbose
Spec. | -v, --verbose
Class | click_extra.logging.VerboseOption
Param type | click.types.IntRange
Python type | int
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_VERBOSE
Default | 0
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 0
Source | DEFAULT
***************************[ 21. row ]***************************
ID | cli.verbosity
Spec. | --verbosity LEVEL
Class | click_extra.logging.VerbosityOption
Param type | click_extra.types.EnumChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_VERBOSITY
Default | 'WARNING'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'WARNING'
Source | DEFAULT
***************************[ 22. row ]***************************
ID | cli.version
Spec. | --version
Class | click_extra.version.VersionOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_VERSION
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
Caution
Because both options are eager, the order in which they are passed matters. --table-format must be passed before --params, otherwise it will have no effect.
Color highlighting¶
By default, the table produced by --params is colorized to highlight important bits. If you do not like colors, you can disable them with the --no-color option:
$ cli --no-color --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 │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────┼───────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────┼────────────────────┼──────────────┼──────────┼───────┼────────┼─────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ cli.accessible │ --accessible │ click_extra.accessibility.AccessibleOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_ACCESSIBLE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.color │ --color [auto|always|never] │ click_extra.color.ColorOption │ click_extra.color.ColorWhenChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_COLOR │ 'auto' │ ✘ │ 'always' │ ✘ │ ✘ │ 1 │ │ ✘ │ 'auto' │ DEFAULT │
│ cli.config │ --config CONFIG_PATH │ click_extra.config.option.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}' │ DEFAULT │
│ cli.config │ --no-config │ click_extra.config.option.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ None │ ✓ │ Sentinel.NO_CONFIG │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.export_config │ --export-config FORMAT │ click_extra.config.option.ExportConfigOption │ click.types.Choice │ str │ ✘ │ ✘ │ ✘ │ CLI_EXPORT_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_HELP │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.help_format │ --help-format [carapace|json|json-full|man|markdown|markdown-full] │ click_extra.command_doc.HelpFormatOption │ click.types.Choice │ str │ ✘ │ ✘ │ ✓ │ CLI_HELP_FORMAT │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.int_param1 │ --int-param1 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM1 │ 10 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 10 │ DEFAULT │
│ cli.int_param2 │ --int-param2 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM2 │ 555 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 555 │ DEFAULT │
│ cli.man │ --man │ click_extra.command_doc.ManOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_MAN │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.no_color │ --no-color │ click_extra.color.NoColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_NO_COLOR │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ COMMANDLINE │
│ cli.params │ --params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_PARAMS │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ COMMANDLINE │
│ cli.progress │ --progress / --no-progress │ click_extra.spinner.ProgressOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_PROGRESS │ True │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ DEFAULT │
│ cli.quiet │ -q, --quiet │ click_extra.logging.QuietOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_QUIET │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.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 │ ✘ │ ✘ │ ✓ │ CLI_TABLE_FORMAT │ 'rounded-outline' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'rounded-outline' │ DEFAULT │
│ cli.theme │ --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_THEME │ 'dark' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'dark' │ DEFAULT │
│ cli.time │ --time / --no-time │ click_extra.execution.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TIME │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.tree │ --tree │ click_extra.tree.TreeOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TREE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.validate_config │ --validate-config FILE │ click_extra.config.option.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✘ │ CLI_VALIDATE_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_VERBOSE │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_VERBOSITY │ 'WARNING' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'WARNING' │ DEFAULT │
│ cli.version │ --version │ click_extra.version.VersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_VERSION │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┴───────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────┴────────────────────┴──────────────┴──────────┴───────┴────────┴─────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
Caution
Because both options are eager, the order in which they are passed matters. --no-color must be passed before --params, otherwise it will have no effect.
Introspecting parameters¶
If you need to dive deeper into parameters and their values, there is a lot of metadata available in the context. Here are some pointers:
from click import option, echo, pass_context
from click_extra import config_option, group
@group
@option("--dummy-flag/--no-flag")
@option("--my-list", multiple=True)
@config_option
@pass_context
def my_cli(ctx, dummy_flag, my_list):
echo(f"dummy_flag is {dummy_flag!r}")
echo(f"my_list is {my_list!r}")
echo(f"Raw parameters: {ctx.meta.get('click_extra.raw_args', [])}")
echo(f"Loaded, default values: {ctx.default_map}")
echo(f"Values passed to function: {ctx.params}")
@my_cli.command()
@option("--int-param", type=int, default=10)
def subcommand(int_param):
echo(f"int_parameter is {int_param!r}")
Hint
The click_extra.raw_args metadata field in the context referenced above is not a standard feature from Click, but a helper introduced by Click Extra. It is only available with @group and @command decorators.
Now if we feed the following ~/configuration.toml configuration file:
~/configuration.toml¶[my-cli]
verbosity = "DEBUG"
dummy_flag = true
my_list = ["item 1", "item #2", "Very Last Item!"]
[my-cli.subcommand]
int_param = 3
Here is what we get:
$ cli --config ~/configuration.toml default-command
dummy_flag is True
my_list is ('item 1', 'item #2', 'Very Last Item!')
Raw parameters: ['--config', '~/configuration.toml', 'default-command']
Loaded, default values: {'dummy_flag': True, 'my_list': ['pip', 'npm', 'gem'], 'verbosity': 'DEBUG', 'default-command': {'int_param': 3}}
Values passed to function: {'dummy_flag': True, 'my_list': ('pip', 'npm', 'gem')}
Introspecting external CLIs¶
The --params option works on your own Click Extra CLIs. To inspect a third-party CLI that doesn’t use Click Extra, use wrap --params, which loads the target and prints the same table without running it:
$ click-extra wrap --params --table-format vertical -- flask run
***************************[ 1. row ]***************************
ID | run.cert
Spec. | --cert PATH
Class | click.core.Option
Param type | flask.cli.CertParamType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_CERT
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 2. row ]***************************
ID | run.debug
Spec. | --debug / --no-debug
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Env. vars. | FLASK_RUN_DEBUG
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 3. row ]***************************
ID | run.debugger
Spec. | --debugger / --no-debugger
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_DEBUGGER
Default | None
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 4. row ]***************************
ID | run.exclude_patterns
Spec. | --exclude-patterns PATH
Class | click.core.Option
Param type | flask.cli.SeparatedPathType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_EXCLUDE_PATTERNS
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 5. row ]***************************
ID | run.extra_files
Spec. | --extra-files PATH
Class | click.core.Option
Param type | flask.cli.SeparatedPathType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_EXTRA_FILES
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 6. row ]***************************
ID | run.help
Spec. | --help
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Env. vars. | FLASK_RUN_HELP
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 7. row ]***************************
ID | run.host
Spec. | -h, --host TEXT
Class | click.core.Option
Param type | click.types.StringParamType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_HOST
Default | '127.0.0.1'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 8. row ]***************************
ID | run.key
Spec. | --key FILE
Class | click.core.Option
Param type | click.types.Path
Python type | str
Hidden | ✘
Exposed | ✘
Env. vars. | FLASK_RUN_KEY
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 9. row ]***************************
ID | run.port
Spec. | -p, --port INTEGER
Class | click.core.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_PORT
Default | 5000
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 10. row ]***************************
ID | run.reload
Spec. | --reload / --no-reload
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_RELOAD
Default | None
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 11. row ]***************************
ID | run.with_threads
Spec. | --with-threads / --without-threads
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_WITH_THREADS
Default | True
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
Parameter structure¶
The table --params prints is the flattened view of a tree, and ParamStructure is what builds it. The same tree is what --config maps a configuration file’s sections onto: a node is a subcommand, a leaf is a parameter, and the path from the root spells the fully-qualified ID.
Take a group with two subcommands:
import click
@click.group
@click.option("--unit", type=click.Choice(("celsius", "fahrenheit")), default="celsius")
def weather(unit):
"""Report the weather of a city."""
@weather.command
@click.option("--days", type=int, default=3)
@click.option("--tag", multiple=True)
@click.argument("city")
def forecast(days, tag, city):
"""Forecast the days to come."""
@weather.command
@click.option("--since", type=click.DateTime())
def history(since):
"""Look back at recorded weather."""
ParamStructure is a mixin: it expects the class using it to settle which parameters the tree covers. Freezing both filters open covers everything.
from click_extra.parameters import ParamStructure
class Structure(ParamStructure):
excluded_params = frozenset()
included_params = None
params_template then returns the command tree with every leaf nulled out, which is the skeleton a configuration file is expected to fill:
import json
with click.Context(weather):
print(json.dumps(Structure().params_template, indent=2))
{
"weather": {
"unit": null,
"help": null,
"forecast": {
"days": null,
"tag": null,
"city": null,
"help": null
},
"history": {
"since": null,
"help": null
}
}
}
The walk resolves its root command from the active context, which a CLI callback already sits in. Outside of one, a bare click.Context around the group is enough, as above.
params_objects is the same tree with the parameter objects kept at the leaves, which is what a consumer needs to coerce a configuration value or report where one came from:
with click.Context(weather):
structure = Structure()
print(structure.params_objects["weather"]["forecast"])
print(ParamStructure.get_tree_value(structure.params_objects, "weather", "forecast", "days"))
{'days': [<Option days>], 'tag': [<Option tag>], 'city': [<Argument city>], 'help': [<Option help>]}
[<Option days>]
get_tree_value() descends a path in one call, and raises a KeyError when the path leads nowhere. Its counterpart init_tree_dict() builds a nested dict from a path and a leaf, which is how the tree gets assembled one parameter at a time.
Fully-qualified IDs¶
Joining a path with PARAM_PATH_SEP produces the ID shown in the ID column of --params, and the same string excluded_params and included_params are matched against. walk_params() yields those paths directly, unfiltered and flat:
from click_extra.parameters import PARAM_PATH_SEP
with click.Context(weather):
for keys, param in Structure().walk_params():
param_type = ParamStructure.get_param_type(param)
print(f"{PARAM_PATH_SEP.join(keys):26} {param_type.__name__}")
weather.unit str
weather.help bool
weather.forecast.days int
weather.forecast.tag list
weather.forecast.city str
weather.forecast.help bool
weather.history.since str
weather.history.help bool
The second column is get_param_type(), which reduces a Click type to the Python type a configuration file has to carry, through the TYPE_MAP table. A repeatable parameter is a list whatever its items are, a boolean flag is a bool, and an unrecognized custom type falls back to str, since a command line carries nothing else.
--help sits in that tree like any other option, and a subcommand sharing its name with a parameter of the same level is left out of it, since a single path cannot address both. What a consumer does with the tree is its own decision: --params reports every node, while --config narrows it down through excluded_params.
click_extra.parameters API¶
classDiagram
Argument <|-- Argument
ExtraOption <|-- ShowParamsOption
Option <|-- ExtraOption
Option <|-- Option
ParamStructure <|-- ShowParamsOption
_ParameterMixin <|-- Argument
_ParameterMixin <|-- Option
Our own flavor of Option, Argument and parameters.
- class click_extra.parameters.P
Type variable bound to
click.Parameter, lettingrequire_sibling_param()return the exact subclass it was asked to find.alias of TypeVar(‘P’, bound=
Parameter)
- click_extra.parameters.PARAM_PATH_SEP = '.'
Separator joining the keys of a parameter’s fully-qualified path (
cli.subcommand.param).
- click_extra.parameters.search_params(params, klass, include_subclasses=True, unique=True)[source]
Search a particular class of parameter in a list and return them.
- Parameters:
params (
Iterable[Parameter]) – list of parameter instances to search in.klass (
type[Parameter]) – the class of the parameters to look for.include_subclasses (
bool) – ifTrue, includes in the results all parameters subclassing the providedklass. IfFalse, only matches parameters which are strictly instances ofklass. Defaults toTrue.unique (
bool) – ifTrue, raise an error if more than one parameter of the providedklassis found. Defaults toTrue.
- Return type:
- click_extra.parameters.last_param(params, klass)[source]
Return the last parameter of exactly
klassin params, orNone.Unlike
search_params(), this matches the exactklass(no subclasses) and tolerates duplicates: when an option is declared more than once (like an explicit@verbosity_optionstacked on a Click Extra command that already ships one), Click keeps the last occurrence, so this mirrors that here instead of erroring out on the ambiguity.
- click_extra.parameters.require_sibling_param(params, requester, klass)[source]
Return the sibling klass parameter declared on the same command, or raise.
Some options are inert on their own: they drive machinery owned by a sibling option.
--no-configand--validate-config, for instance, both depend on the--configoption (ConfigOption). This helper centralizes the lookup so every such option raises the sameRuntimeErrorwhen its required sibling is missing, naming the offending flag.- Parameters:
- Return type:
- click_extra.parameters.full_short_help(command)[source]
Return the command’s canonical one-line short help, untruncated.
Click’s
click.Command.get_short_help_str()truncates to 45 characters by default with a trailing"..."so subcommand listings fit a terminal column. That bound is wrong for generated documentation and completion specs, where the NAME / COMMANDS sections carry the full description and the renderer wraps text on its own.The lookup mirrors Click’s order: an explicit
short_helpwins, otherwise the first paragraph ofcommand.helpis joined into one line. A truthydeprecatedflag prepends(Deprecated)so the flag stays visible.- Return type:
- click_extra.parameters.resolve_param_help(param, ctx)[source]
Return a parameter’s help text, including the dynamically-generated ones.
Reading
param.helpcovers the options that carry a static string, and misses the ones that compute their help from the context: Click Extra’s own-v/-qderive theirs from the resolved base verbosity, and leave the attribute atNone(seeget_help_record()). Falling back to the help record picks those up.The record also carries Click’s bracket fields (
[default: …],[required],[env var: …]), appended to the prose behind two spaces. They are stripped here: they are not the author’s documentation, and every backend of this module renders them (or deliberately does not) from structured fields of its own.
- click_extra.parameters.param_spellings(param)[source]
All literal spellings of a parameter: primary
optsthensecondary_opts.A boolean flag pair yields both forms (
--foo,--no-foo); a plain option yields just its declared names.
- click_extra.parameters.short_long_opts(opts)[source]
Split option spellings into the first short (
-x) and long (--xy) form.Either element is the empty string when that form is absent.
- click_extra.parameters.option_value_kind(param)[source]
Classify how an option consumes a value, the basis for rendering its metavar.
"flag": takes no value. A boolean switch (--foo,--foo/--no-foo), a flag with a customflag_value(--no-config), or a counter (-v)."optional": the value may be omitted. Click models this asis_flag=Falsewith aflag_valueset, so a bare--colorstands for the flag value while--color=neverpasses an explicit one."required": consumes a value (--config CONFIG_PATH).
Note
The discriminator is Click’s
is_flag(pluscount), notis_bool_flag: a flag carrying a customflag_valuesuch asNoConfigOptionreportsis_bool_flag=Falseyet still takes no value.- Return type:
Literal['flag','optional','required']
- click_extra.parameters.resolve_flag_value(param)[source]
The value param’s primary declaration stands for.
Released Click materializes it in
flag_value:Nonefor a plain option or a counter,Truefor a boolean flag, and the declared value otherwise (--colorstanding foralways). Click’s development branch leaves that attribute as theUNSETsentinel and answers the same question lazily inflag_activation_value, so reading either attribute on its own is right on only one of the two, and storing the sentinel anywhere it will be read back as a value silently turns the flag off.- Return type:
- click_extra.parameters.is_repeatable(param)[source]
Whether the parameter may be supplied several times (
multipleorcount).- Return type:
- class click_extra.parameters.Argument(*args, help=None, **attrs)[source]
Bases:
_ParameterMixin,ArgumentWrap
cloup.Argument, itself inheriting fromclick.Argument.Inherits first from
_ParameterMixinto allow future overrides of Click’sParametermethods.
- class click_extra.parameters.Option(*args, group=None, **attrs)[source]
Bases:
_ParameterMixin,OptionWrap
cloup.Option, itself inheriting fromclick.Option.Inherits first from
_ParameterMixinto allow future overrides of Click’sParametermethods.
- class click_extra.parameters.ExtraOption(*args, group=None, **attrs)[source]
Bases:
OptionDedicated to option implemented by
click-extraitself.Provides a way to identify Click Extra’s own options with certainty, and restores the pre-Click-8.4.0 contract that a callback (or a type’s
convert()) can introspect its own parameter source from within itself.Note
This is the one click-extra class that deliberately keeps the
Extraprefix. The8.0.0cleanup dropped it everywhere else (ExtraCommandbecameCommand,ExtraContextbecameContext, and so on), shadowing the matching Cloup or Click class. Here the plainOptionname is already taken by the user-facing enhanced wrapper this class subclasses, so the prefix is not legacy baggage but a real distinction:ExtraOptionmarks click-extra’s own built-in options. That marker is load-bearing, sinceCommandsorts parameters withisinstance(param, ExtraOption)to push the built-in options to the end.Note
Bracket fields (envvar, default, range, required) cannot be pre-styled in
get_help_record()because Click’s text wrapper splits lines after the record is returned, which would break ANSI codes that span wrapped boundaries. Styling is instead applied post-wrapping inHelpFormatter._style_bracket_fields(), which uses the structured data fromOption.get_help_extra()to identify each field by its label.Note
Built-in option subclasses share a common shape: their
__init__defaultsparam_declsto the option’s canonical flags and wires an eager callback viakwargs.setdefault("callback", self.<callback>). Every callback name encodes its role with a verb prefix. The common roles are:set_<key>publishes a resolved value toctx.meta(set_color,set_no_color,set_theme,set_telemetry,set_progress,set_accessible,set_zero_exit, the verbosity options’set_level);init_<system>additionally installs actxhelper or records a snapshot (init_timer,init_formatter,init_columns,init_sort);validate_<thing>coerces and validates the raw input (validate_jobs,validate_config);print_*renders output and exits (print_man,print_params,print_and_exit).
A few options own a richer operation and name it with its own verb rather than forcing one of the above.
ConfigOptionwiresload_confto read, parse, and merge a configuration file, andNoConfigOptionwirescheck_sibling_config_optionto assert that a sibling--configoption exists.- handle_parse_result(ctx, opts, args)[source]
Record the parameter source before delegating to the base implementation.
Warning
Click
8.4.0(PR pallets/click#3404) reorderedParameter.handle_parse_resultsoctx.set_parameter_sourceruns afterprocess_value. Callbacks that introspect their own provenance viactx.get_parameter_source(self.name)therefore readNoneinstead of the actual source.ColorOption,ConfigOption, andShowParamsOptionrely on this introspection (from their eager callback) to decide whether an env var should override the default (--color), whether the--configpath was user-supplied, and what to render in theSourcecolumn of--params.JobsOptionrelies on the same introspection from its type’s non-eagerconvert()(JobCount), to decide whether anauto/maxcollapsing to a single job logs as a warning (explicit request) or at info level (the option’s own default).Click
8.4.1restored the pre-8.4.0contract upstream (PR pallets/click#3484), so this override only matters for Click8.4.0itself, which sits inside click-extra’s supported>= 8.3.1range. Pre-recording the source here, for every option regardless of eagerness, keeps that contract on every supported Click.super().handle_parse_resultre-records the same value at the canonical time, so the slot arbitration logic introduced by #3404 is unaffected:slot_emptyis computed fromctx.params, not from_parameter_source.consume_valueruns twice as a side effect: once here and once insuper. Both calls are pure for click-extra’s existing options (no env var side effects, no prompt):consume_valueonly resolves the raw value and its source, it never invokes the parameter’stype.convert(), so this pre-record cannot itself trigger a callback’s or a type’s logging or validation twice. Should a future subclass need prompt behavior, this override would need to cache the result instead.The pre-record is skipped when the slot already carries a source from an earlier option sharing the same
name(Click’s feature-switch pattern), so the arbitration logic insuperstill sees the originalexisting_sourcerather than a stale rewrite from this option.
- class click_extra.parameters.ParamStructure[source]
Bases:
objectUtilities to introspect CLI options and commands structure.
Structures are represented by a tree-like
dict.Access to a node is available using a serialized path string composed of the keys to descend to that node, separated by a dot
..- excluded_params: frozenset[str]
Fully-qualified IDs of the parameters to block from the structure.
Set by subclasses:
ShowParamsOptionfreezes an empty set, whileConfigOptionresolves a dynamic default (or the user-provided list) within the active context. The two filters are mutually exclusive, a constraint each subclass enforces in its own constructor.
- included_params: frozenset[str] | None
Allowlist of parameter IDs, mutually exclusive with
excluded_params.Nonedisables the allowlist. It is resolved intoexcluded_paramsbybuild_param_trees(), once every parameter ID is known.
- static init_tree_dict(*path, leaf=None)[source]
Utility method to recursively create a nested dict structure whose keys are provided by
pathlist and at the end is populated by a copy ofleaf.- Return type:
- static get_tree_value(tree_dict, *path)[source]
Get in the
tree_dictthe value located at thepath.Raises
KeyErrorif no item is found at the providedpath.- Return type:
- walk_params()[source]
Generate an unfiltered list of all CLI parameters.
Everything is included, from top-level groups to subcommands, and from options to arguments.
- Yields a 2-element tuple:
a tuple of keys leading to the parameter;
the parameter object itself.
Thin adapter over
walk_command_params(): it resolves the root CLI from the active context and drops the per-parameter context that the free function also yields.
- TYPE_MAP: ClassVar[dict[type[ParamType], type[str | int | float | bool | list]]] = {<class 'click.types.BoolParamType'>: <class 'bool'>, <class 'click.types.Choice'>: <class 'str'>, <class 'click.types.DateTime'>: <class 'str'>, <class 'click.types.File'>: <class 'str'>, <class 'click.types.FloatParamType'>: <class 'float'>, <class 'click.types.FloatRange'>: <class 'float'>, <class 'click.types.IntParamType'>: <class 'int'>, <class 'click.types.IntRange'>: <class 'int'>, <class 'click.types.Path'>: <class 'str'>, <class 'click.types.StringParamType'>: <class 'str'>, <class 'click.types.Tuple'>: <class 'list'>, <class 'click.types.UUIDParameterType'>: <class 'str'>, <class 'click.types.UnprocessedParamType'>: <class 'str'>}
Map Click types to their Python equivalent.
Keys are subclasses of
click.types.ParamType. Values are expected to be simple builtins Python types.This mapping can be seen as a reverse of the
click.types.convert_type()method.
- static map_click_type(click_type)[source]
Map a Click parameter type instance to its Python equivalent.
Returns
strfor unrecognised custom types, since command-line parameters are strings by default.See the list of custom types provided by Click.
- static get_param_type(param)[source]
Get the Python type of a Click parameter.
Returns
strfor unrecognised custom types, since command-line parameters are strings by default.See the list of custom types provided by Click.
- build_param_trees()[source]
Build and return the parameters tree structure.
This removes parameters whose fully-qualified IDs are in the
excluded_paramsblocklist.If
included_paramswas provided, it is resolved intoexcluded_paramshere, where all parameter IDs are available.
- click_extra.parameters.get_param_spec(param, ctx)[source]
Extract the option-spec string (like
-v, --verbose) from a parameter.Temporarily unhides hidden options so their help record can be produced.
Note
The
hiddenproperty is only supported byOption, notArgument.Todo
Submit a PR to Click to separate production of param spec and help record. That way we can always produce the param spec even if the parameter is hidden. See: https://github.com/kdeldycke/click-extra/issues/689
- click_extra.parameters.format_param_row(param, ctx, path, is_structured)[source]
Compute the structural table cells for a Click parameter.
Returns a
dict[column_id, cell]covering every column that can be derived from the parameter object alone (no runtime invocation state or config-file context). Specifically:id,spec,class,param_type,python_type,hidden,exposed,envvars,default,is_flag,flag_value,is_bool_flag,multiple,nargs,prompt, andconfirmation_prompt.Attributes only defined on
click.Option(hidden,is_flag,flag_value,is_bool_flag,prompt,confirmation_prompt) yieldNoneforclick.Argumentparameters: empty cell in visual formats,nullin structured ones.For structured formats (JSON, YAML, etc.), values are native Python types. For visual formats, values are themed strings matching help-screen styling.
The remaining table columns (
allowed_in_conf,value,source,config_file) require live context and are filled in byrender_params_table().
- click_extra.parameters.make_resilient_context(command, info_name=None, parent=None)[source]
Build an introspection context for a command.
Parses no arguments and sets
resilient_parsing=Trueso required-argument errors, prompts and eager-option side effects stay dormant: the canonical way to materialize aclick.Contextpurely to read a command’s structure (its parameters, env-var prefix and subcommands), shared by the man-page and Carapace exporters.- Return type:
- click_extra.parameters.iter_subcommands(command, ctx, *, skip_hidden=True)[source]
Yield a group’s direct subcommands as
(name, command)pairs.Subcommands are discovered dynamically through
click.Group.list_commands()/get_command(), in listing order, so lazily-registered commands are included. A non-group yields nothing, a name resolving toNoneis skipped, and hidden subcommands are skipped unlessskip_hiddenisFalse(completion specs keep them, flagged hidden; documentation drops them).
- click_extra.parameters.iter_params_for_display(command, ctx)[source]
Yield a command’s parameters in the order its help screen lists them.
A Click Extra command keeps two orders apart:
command.paramsis the processing order, which decides when each callback fires, while the help screen reads the presentation order Cloup caches inarguments,option_groupsandungrouped_options(seeclick_extra.commands.Command.param_priority()). Readingget_params()therefore renders a man page, a Markdown document or a completion spec whose flags no longer match the--helpits reader just saw. This is the accessor every such renderer should go through.Falls back to
get_params()for a command that carries no Cloup option groups, where the two orders are the same list. Any parameter attached after construction, and so absent from the cached groups, is yielded last rather than dropped.
- click_extra.parameters.walk_command_params(cmd, ctx, parent_keys=())[source]
Walk the parameter tree of a Click command and all its subcommands.
Yields
(path_keys, param, owning_ctx)for every parameter found on cmd and, recursively, on each subcommand. Each subcommand is walked under its own freshly-built child context, so context-sensitive metadata (notably the auto-generated environment variable, which derives fromContext.auto_envvar_prefix) is computed at the correct nesting level rather than inherited from the root.A subcommand whose name collides with a sibling parameter at the same level is skipped: a single fully-qualified path cannot address both an option and a subcommand at once.
- click_extra.parameters.replay_raw_args(subject_ctx)[source]
Re-parse the captured raw arguments to recover per-parameter values.
Click discards the pre-parsed arguments once processing is done, so the value and provenance of each parameter cannot be read back directly. When
RAW_ARGSwas captured on the context (byCommand/Group), replaying it through a fresh parser rebuilds theoptsmapping thatParameter.consume_valueconsults, without re-firing eager callbacks:handle_parse_resultis never called here, only the parser.Returns an empty mapping when no raw arguments were captured, so callers can fall back to parameter defaults.
- click_extra.parameters.param_config_source(root_ctx, keys)[source]
Return the configuration file supplying a parameter’s
default_mapvalue.keys is the parameter’s fully-qualified path, root command name first and parameter name last, as yielded by
walk_command_params(). ReturnsNonewhen no configuration file was loaded, when the parameter is absent from every loaded layer, or when the context carries no layereddefault_mapat all.The walk mirrors how Click resolves
default_map, so the attribution matches the value Click actually picks:Root-level parameters are looked up in the root context’s
~collections.ChainMap, whose first layers are the loaded files in precedence order (seeCONF_SOURCES): the first layer naming the parameter wins.A subcommand section resolves against that same
ChainMap, but Click keeps descending inside the single layer that named the first segment: the file owning a subcommand section owns its whole sub-tree.
Note
Lazy subcommands receive their section from the merged configuration document, injected into the front layer by
_apply_config_to_parent_context(): those values are attributed to the highest-precedence file even when several files contributed to the merge.
- click_extra.parameters.render_params_table(subject_ctx, *, default_columns=None)[source]
Introspect
subject_ctx.commandand print its parameter metadata table.Walks the command and any nested subcommands, emitting one row per parameter. The table format and column selection are read from
subject_ctx.meta(seeTABLE_FORMATandCOLUMNS); when neither is set, a sibling--table-format/--columnsoption on the command is consulted, then the default_columns fallback, then the canonical order.When
subject_ctx.metacarries pre-parsedRAW_ARGS, thevalueandsourcecolumns are resolved by replaying those arguments against the command parser; otherwise they fall back to the parameter defaults.This is the shared rendering core behind both
print_params()(introspecting the live CLI) and theclick-extra wrap --paramspath (introspecting a foreign target). The caller is responsible for exiting the context afterwards.Important
Click does not keep the raw, pre-parsed arguments around, so values and their provenance cannot be read back directly. The workaround replays
RAW_ARGS(captured on the context byCommand/Group) through the command parser, callingconsume_value()rather thanhandle_parse_result()so eager callbacks are not re-triggered.- Return type:
- class click_extra.parameters.ShowParamsOption(param_decls=None, is_flag=True, expose_value=False, is_eager=True, help='Show all CLI parameters, their provenance, defaults and value, then exit.', **kwargs)[source]
Bases:
ExtraOption,ParamStructureA pre-configured option adding a
--paramsoption.Between configuration files, default values and environment variables, it might be hard to guess under which set of parameters the CLI will be executed. This option print information about the parameters that will be fed to the CLI.
Note
The flag is named
--params, not--show-params. It names the view it prints, matching the neighbouring bare-noun informational flags (--help,--version,--man,--tree), none of which carry ashow-verb prefix. The class and@show_params_optiondecorator keep their historical names: the class is named for what it does (show the parameters), while the flag and the parameter’s ID use the bare noun.- TABLE_HEADERS: ClassVar[tuple[_ColumnSpec, ...]] = (ColumnSpec(id='id', label='ID', description='Fully-qualified parameter path (`cli.subcommand.param_name`) derived from the [`click.Command`](https://click.palletsprojects.com/en/stable/api/#click.Command) tree. Doubles as the key used to address the parameter from a configuration file, which also accepts the kebab-case spelling of the last segment.', max_width=None, optional=False), ColumnSpec(id='spec', label='Spec.', description='Option/argument specification string (like `-v, --verbose`) extracted from [`click.Parameter.get_help_record()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter).', max_width=None, optional=False), ColumnSpec(id='help', label='Help', description="The parameter's own help text, as written by the CLI author. Opt-in: it is the only column carrying free-form prose, so it stays out of the default table and is selected by ID (`--columns id,spec,help`). Structured formats are its main audience: it turns a `--params` dump into a self-describing inventory a tool or an agent can read without also parsing the rendered `--help` screen.", max_width=None, optional=True), ColumnSpec(id='class', label='Class', description="Fully-qualified class of the parameter: a subclass of [`click.Option`](https://click.palletsprojects.com/en/stable/api/#click.Option), [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument), [`cloup.Option`](https://cloup.readthedocs.io/en/stable/autoapi/cloup/index.html#cloup.Option), or one of Click Extra's own wrappers ([`click_extra.parameters.Option`](#click_extra.parameters.Option), [`click_extra.parameters.Argument`](#click_extra.parameters.Argument), [`click_extra.parameters.ExtraOption`](#click_extra.parameters.ExtraOption)).", max_width=None, optional=False), ColumnSpec(id='param_type', label='Param type', description='Click value converter class: a subclass of [`click.ParamType`](https://click.palletsprojects.com/en/stable/api/#click.ParamType) like [`click.IntRange`](https://click.palletsprojects.com/en/stable/api/#click.IntRange), [`click.Choice`](https://click.palletsprojects.com/en/stable/api/#click.Choice), or a Click Extra type.', max_width=None, optional=False), ColumnSpec(id='python_type', label='Python type', description='Python built-in type the parsed value resolves to: [`str`](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), [`int`](https://docs.python.org/3/library/functions.html#int), [`float`](https://docs.python.org/3/library/functions.html#float), [`bool`](https://docs.python.org/3/library/functions.html#bool), or [`list`](https://docs.python.org/3/library/stdtypes.html#list). Computed by [`ParamStructure.get_param_type()`](#click_extra.parameters.ParamStructure.get_param_type) from the Click `Param type`.', max_width=None, optional=False), ColumnSpec(id='hidden', label='Hidden', description="Reflects [`click.Option`'s `hidden`](https://click.palletsprojects.com/en/stable/api/#click.Option) constructor argument: the option is omitted from `--help` output. Empty for [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument), which does not support hiding.", max_width=None, optional=False), ColumnSpec(id='exposed', label='Exposed', description="Reflects [`click.Parameter`'s `expose_value`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) constructor argument: whether the parsed value is forwarded to the command callback. Eager options like `--params` and `--help` typically run a callback and exit, so they are not exposed.", max_width=None, optional=False), ColumnSpec(id='allowed_in_conf', label='Allowed in conf?', description='Click Extra-specific: whether the parameter is reachable from a configuration file. Controlled by [`ParamStructure.excluded_params`](#click_extra.parameters.ParamStructure.excluded_params) and [`included_params`](#click_extra.parameters.ParamStructure.included_params). Empty when the CLI has no [`--config` option](config.md).', max_width=None, optional=False), ColumnSpec(id='envvars', label='Env. vars.', description="Environment variables read for this parameter: the explicit [`click.Parameter`'s `envvar`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) plus the auto-resolved IDs documented in [Environment variables](envvar.md).", max_width=None, optional=False), ColumnSpec(id='default', label='Default', description='Default value returned by [`click.Parameter.get_default()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter.get_default), rendered as its Python `repr()`.', max_width=None, optional=False), ColumnSpec(id='is_flag', label='Is flag', description="Reflects [`click.Option`'s `is_flag`](https://click.palletsprojects.com/en/stable/api/#click.Option): whether the option behaves as a flag (no value taken from the command line). Empty for [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument).", max_width=None, optional=False), ColumnSpec(id='flag_value', label='Flag value', description="Reflects [`click.Option`'s `flag_value`](https://click.palletsprojects.com/en/stable/api/#click.Option): the Python value substituted for the option when its flag is used. Defaults to `True` for boolean flags, can be any value for flag-value style options (like `@option('--upper', 'transform', flag_value='upper')`).", max_width=None, optional=False), ColumnSpec(id='is_bool_flag', label='Is bool flag', description='Reflects `click.Option.is_bool_flag` (set internally by Click when `flag_value` is `True` or `False`): the option is a *true* boolean flag, as opposed to a flag-value style option.', max_width=None, optional=False), ColumnSpec(id='multiple', label='Multiple', description="Reflects [`click.Parameter`'s `multiple`](https://click.palletsprojects.com/en/stable/api/#click.Parameter): the parameter can be repeated on the command line, collecting values into a tuple.", max_width=None, optional=False), ColumnSpec(id='nargs', label='Nargs', description="Reflects [`click.Parameter`'s `nargs`](https://click.palletsprojects.com/en/stable/api/#click.Parameter): the number of CLI tokens the parameter consumes. `1` is the default; `-1` denotes a variadic argument.", max_width=None, optional=False), ColumnSpec(id='prompt', label='Prompt', description="Reflects [`click.Option`'s `prompt`](https://click.palletsprojects.com/en/stable/api/#click.Option): the text shown to the user when the option is not provided on the command line. Empty when no prompt is configured.", max_width=None, optional=False), ColumnSpec(id='confirmation_prompt', label='Confirmation prompt', description="Reflects [`click.Option`'s `confirmation_prompt`](https://click.palletsprojects.com/en/stable/api/#click.Option): whether the user is asked to enter the value twice for confirmation.", max_width=None, optional=False), ColumnSpec(id='value', label='Value', description='Current value of the parameter at invocation time, computed by [`click.Parameter.consume_value()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) from the merged sources (CLI, environment, config file, default).', max_width=None, optional=False), ColumnSpec(id='source', label='Source', description='Provenance of the resolved value: a [`click.core.ParameterSource`](https://click.palletsprojects.com/en/stable/api/#click.core.ParameterSource) enum member such as `COMMANDLINE`, `ENVIRONMENT`, `DEFAULT_MAP`, or `DEFAULT`.', max_width=None, optional=False), ColumnSpec(id='config_file', label='Config file', description='The configuration file the effective value was loaded from, when `Source` reports `DEFAULT_MAP`. With [`cascade=True`](config.md#cascading-configuration-files) several files are layered and this column names the one that won the parameter; with a single loaded file, every config-sourced parameter names that file. Empty for every other source and when no configuration file was loaded. Opt-in, like `help`: paths are wide and stay redundant with `Source` until several files take part.', max_width=None, optional=True))
Rich column registry for the
--paramstable.Each entry is a
click_extra.table.ColumnSpeccarrying the column’s stableid(used by--columnsand as structured-format key), its displaylabel, and a MyST/Markdowndescriptionconsumed by the documentation’s auto-generated Available columns section. Iteration yields columns in canonical display order.
- classmethod column_labels()[source]
Return just the display labels of
TABLE_HEADERS(in order).
- classmethod column_ids()[source]
Return just the stable IDs of
TABLE_HEADERS(in order).
- classmethod default_columns()[source]
Return the columns rendered when
--columnsasks for no projection.Every column but the
optionalones, which stay addressable by ID and out of the way until named.- Return type:
tuple[_ColumnSpec, …]
- classmethod default_column_ids()[source]
Return the stable IDs of
default_columns()(in order).
- classmethod default_column_labels()[source]
Return the display labels of
default_columns()(in order).
- classmethod find_column(column_id)[source]
Return the
ColumnSpecmatchingcolumn_id.Raises
KeyErrorif no column has this ID; callers should convert the error into aclick.UsageErrorwhen surfaced to a user.
- classmethod render_doc_table()[source]
Render
TABLE_HEADERSas a Markdown table for documentation.Used by the
show_params_columns_tableMyST substitution indocs/conf.pyto feed the Available columns section ofdocs/parameters.md: editing a description here automatically rebuilds the docs table on the nextsphinx-build.- Return type:
- excluded_params
Deactivates the blocking of any parameter.
- included_params
No allowlist filter; show all parameters.
- print_params(ctx, param, value)[source]
Introspect the current CLI and print its parameter metadata table.
Thin wrapper over
render_params_table(), the shared rendering core also drivingclick-extra wrap --paramsfor foreign CLIs. The live invocation context carries everything the core needs: the capturedRAW_ARGS(attached byCommand/Group) for value and source resolution, plus any sibling--table-format/--columnsoptions.- Return type: