### Argfile configuration format example

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/config/option.html

Shows the plain-text argfile format used by load_argfile_config, with comments starting with a hash and one option per line.

```text
# Comments start with a hash sign.
--option-name some value
--flag
```

--------------------------------

### Define command with examples and show help

Source: https://kdeldycke.github.io/click-extra/commands.html

Define a Click Extra command with usage examples and view its generated help screen. The examples appear in the help output under an 'Examples:' section, and the command lines are emitted verbatim so they can be copied.

```python
from click_extra import command, echo, option


@command(
    examples=[
        ("Report the temperature in Fahrenheit", "forecast --units fahrenheit Oslo"),
        ("Report tomorrow's forecast", "forecast --day tomorrow Oslo"),
    ]
)
@option("--units", default="celsius", help="Temperature scale to display.")
def forecast(units):
    """Report the forecast for a city."""
    echo(f"Sunny, in {units}.")

```

```shell
$ forecast --help
Usage: forecast [OPTIONS]

  Report the forecast for a city.

Options:
  --units TEXT                 Temperature scale to display.  [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.
                               [default: ~/.config/forecast/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.

Examples:
  Report the temperature in Fahrenheit:
    $ forecast --units fahrenheit Oslo
  Report tomorrow's forecast:
    $ forecast --day tomorrow Oslo

```

--------------------------------

### Install all extras

Source: https://kdeldycke.github.io/click-extra/install.html

Installs all extras at once.

```shell
$ uv pip install click-extra[all]

```

--------------------------------

### ARGFILE configuration file example

Source: https://kdeldycke.github.io/click-extra/config-formats.html

Example ARGFILE configuration file. Each line is a command-line option, comments start with #, and both --option value and --option=value are supported. Boolean flags use --flag and --no-flag.

```plaintext
# Print more details.
--verbose

# Repeat the operation three times, in French.
--count 3
--language fr

# A list is fed one item per occurrence.
--my-list pip
--my-list npm

```

--------------------------------

### click-extra wrap --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Shows the full help output for the `click-extra wrap` command, including its options and usage examples. Use it to understand how to run or introspect any Click CLI through Click Extra, with modes like `--params`, `--man`, `--tree`, and `--help-format`. The examples illustrate running a CLI, reading subcommand help, reporting parameter sources, and installing a shell-completion spec.

```shell
$ click-extra wrap --help
Usage: click-extra wrap [OPTIONS] SCRIPT [ARGS]...
Aliases: run

  Run, or introspect, any Click CLI through Click Extra.

  By default, runs SCRIPT with keyword highlighting and themed styling for its
  help screens. The target CLI is not modified.

  With --params, --man, --tree or --help-format, SCRIPT is loaded and described
  without being run. The first three answer a question a person is asking right
  now; --help-format renders the target as an artifact for a program or a build
  step. Extra arguments after SCRIPT navigate into nested subcommands; for
  --params, any trailing options are replayed against the resolved command so
  the parameter table reports their value and source.

  Resolution order for SCRIPT: installed console_scripts entry point, a local
  project directory (its entry point is read from pyproject.toml or setup.cfg),
  Python file path, module:function notation, or Python module name.

Options:
  --params                Show the parameters of the target CLI and exit,
                          without running it.
  --man                   Read the manual page of the target CLI and exit,
                          without running it.
  --tree                  Show the tree of nested subcommands of the target CLI
                          and exit, without running it.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                          Render the target CLI in the given format and exit,
                          without running it.
  --output-dir DIRECTORY  With --help-format, write the rendering into this
                          directory instead of printing it. Created if missing.
  --install               With --help-format, write the rendering where its
                          consumer looks for it instead of printing it, and echo
                          the written path.
  --table-format FORMAT   With --params, the rendering style of the parameter
                          table. Falls back to the click-extra group's --table-
                          format when not set here.  [default: rounded-outline]
  --columns COLUMNS       Restrict and reorder table columns, SQL SELECT-style.
                          Comma-separated list of column IDs. Default: all
                          columns in canonical order.
  -h, --help              Show this message and exit.

Examples:

  Run a CLI with Click Extra's colored help:
    $ click-extra wrap -- my-cli --help
  Read the help of one of its subcommands:
    $ click-extra wrap -- my-cli pick --help
  Report what a subcommand accepts, and where each value comes from:
    $ click-extra wrap --params -- my-cli pick
  Write a shell-completion spec where its consumer looks for it:
    $ click-extra wrap --help-format carapace --install -- my-cli

```

--------------------------------

### Install man page or Carapace spec with click-extra wrap --install

Source: https://kdeldycke.github.io/click-extra/machine-readable.html

Install a man page or Carapace spec for a Click CLI. The wrapper writes to the consumer's expected location, honoring XDG_DATA_HOME and XDG_CONFIG_HOME. Use --output-dir DIR to write elsewhere; --install is refused for other formats.

```shell
$ click-extra wrap --help-format man --install -- flask
/home/me/.local/share/man/man1/flask.1
/home/me/.local/share/man/man1/flask-run.1
$ click-extra wrap --help-format carapace --install -- flask
/home/me/.config/carapace/specs/flask.yaml

```

--------------------------------

### Install click-extra demo CLI with pipx

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the demo CLI globally using pipx.

```shell
$ pipx install click-extra
```

--------------------------------

### Install click-extra demo CLI with uv tool

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the demo CLI system-wide using uv tool.

```shell
$ uv tool install click-extra
```

--------------------------------

### Install Carapace spec with --install

Source: https://kdeldycke.github.io/click-extra/carapace.html

Writes the spec to the Carapace specs directory (`$XDG_CONFIG_HOME/carapace/specs/`, loaded on startup) instead of printing it. `--install` works across formats; `--output-dir` writes elsewhere, and both are refused for renderings that nothing looks for.

```shell
$ uvx --from "click-extra[carapace]" --with flask click-extra wrap --help-format carapace --install -- flask
/home/me/.config/carapace/specs/flask.yaml

```

--------------------------------

### Initialize environment with uv and install dbt-core and aws-sam-cli

Source: https://kdeldycke.github.io/click-extra/commands.html

Initializes a virtual environment with Click Extra, dbt-core, and aws-sam-cli installed. The ellipses indicate omitted output from the commands.

```shell
$ git clone https://github.com/kdeldycke/click-extra
(...)

$ cd click-extra
(...)

$ python -m pip install uv
(...)

$ uv venv
(...)

$ source .venv/bin/activate
(...)

$ uv sync --all-extras
(...)

$ uv pip install dbt-core
(...)

$ uv pip install aws-sam-cli
(...)

```

--------------------------------

### Argfile configuration file format

Source: https://kdeldycke.github.io/click-extra/config.html

Example of a plain-text argfile configuration file. Each line holds one command-line token, with options and values separated by spaces. Comments start with a hash sign, and flags can be listed without a value.

```plaintext
# Comments start with a hash sign.
--option-name some value
--flag

```

--------------------------------

### Install click-extra with Pygments extra

Source: https://kdeldycke.github.io/click-extra/pygments.html

Install the optional Pygments components using pip. This keeps the base install lean by only pulling in Pygments and its prerequisites when needed.

```bash
$ pip install click_extra[pygments]

```

--------------------------------

### TOML configuration file example

Source: https://kdeldycke.github.io/click-extra/config.html

Example TOML configuration file for the my-cli command. It sets int_param to 3 and includes extra keys that will be ignored.

```toml
[my-cli]
int_param = 3
random_stuff = "will be ignored"

[garbage]
dummy_flag = true

```

--------------------------------

### Install click-extra with pip

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the latest stable release and dependencies using pip.

```shell
$ python -m pip install click-extra
```

--------------------------------

### documented command with examples

Source: https://kdeldycke.github.io/click-extra/_modules/tests/test_command_doc.html

Defines a command with two usage examples, a positional argument, and an option with a Choice type. The examples show how to report the forecast in Fahrenheit and the default forecast.

```python
@command(
    examples=[
        ("Report the forecast in Fahrenheit", "weather Oslo --units fahrenheit"),
        ("Report the default forecast", "weather Oslo"),
    ]
)
@argument("city", help="The city to report on.")
@option("--units", type=Choice(["celsius", "fahrenheit"]), help="Temperature scale.")
def documented(city, units):
    """Report the forecast for a CITY."""
```

--------------------------------

### Canonical click example with help output

Source: https://kdeldycke.github.io/click-extra/tutorial.html

The canonical click example and its help screen output. Use this as a baseline to compare with the click-extra version.

```python
import click

@click.command
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name", help="The person to greet.")
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for _ in range(count):
        click.echo(f"Hello, {name}!")

```

```text
$ hello --help
Usage: hello [OPTIONS]

  Simple program that greets NAME for a total of COUNT times.

Options:
  --count INTEGER  Number of greetings.
  --name TEXT      The person to greet.
  --help           Show this message and exit.

```

--------------------------------

### Install click_extra[sphinx]

Source: https://kdeldycke.github.io/click-extra/sphinx.html

Install the Sphinx extra dependencies required for Click Extra's Sphinx helpers. Run this before enabling the extension in conf.py.

```console
$ pip install click_extra[sphinx]

```

--------------------------------

### Install sphinx extra

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the sphinx extra to enable click:source and click:run directives for live CLI documentation.

```shell
$ uv pip install click-extra[sphinx]

```

--------------------------------

### TOML configuration file for the dataclass schema example

Source: https://kdeldycke.github.io/click-extra/config-schema.html

Example TOML file at ~/.config/my-app/config.toml that sets values for the group and its greet subcommand. The key extra-categories is hyphenated and gets normalized to extra_categories in the dataclass.

```toml
[my-app]
verbose = true
extra-categories = ["docs", "tests"]
output-format = "json"

[my-app.greet]
name = "Alice"

```

--------------------------------

### format_examples(_ctx, _formatter)

Source: https://kdeldycke.github.io/click-extra/commands.html

Writes an 'Examples:' section listing the command's examples. Each entry renders its description and the command line indented behind a '$' prompt. Command lines go out verbatim to avoid wrapping.

```APIDOC
## format_examples(_ctx, _formatter)

### Description
Writes an `Examples:` section listing the command's `examples`. Each entry renders its description, then the command line it describes, indented behind a `$` prompt. A command declaring none writes nothing at all. The command lines go out verbatim rather than through `formatter.write_text()`.

### Parameters
- **ctx** (Context) - Required - The Click context.
- **formatter** (HelpFormatter) - Required - The formatter to write to.

### Return Type
`None`
```

--------------------------------

### Get ansi-color lexer by name

Source: https://kdeldycke.github.io/click-extra/pygments.html

After Click Extra installation, the ansi-color lexer is available to Pygments. Use get_lexer_by_name to retrieve it.

```python
>>> from pygments.lexers import get_lexer_by_name
>>> get_lexer_by_name("ansi-color")
<pygments.lexers.AnsiColorLexer>

```

--------------------------------

### Context.meta example: storing and retrieving language state

Source: https://kdeldycke.github.io/click-extra/_modules/click/core.html

Shows how to store and retrieve shared state in the context's meta dictionary using unique dotted keys. The example defines a module-specific key and two functions that set and get a language value, defaulting to 'en_US'.

```python
LANG_KEY = f'{__name__}.lang'

def set_language(value):
    ctx = get_current_context()
    ctx.meta[LANG_KEY] = value

def get_language():
    return get_current_context().meta.get(LANG_KEY, 'en_US')
```

--------------------------------

### Module header and imports for click_extra.pytest

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/pytest.html

The module starts with a copyright notice and imports necessary dependencies, including pytest, click, cloup, and internal modules. It raises an ImportError with a custom message if pytest is not installed.

```python
# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
"""Pytest fixtures and marks to help testing Click CLIs."""

from __future__ import annotations

from ._utils import missing_extra_message

try:
    import pytest
except ImportError as err:
    raise ImportError(missing_extra_message("pytest", subject="This module")) from err


import difflib
import os

import click
import cloup
from extra_platforms import is_windows

from .decorators import argument, command, group, option
from .envvar import temporary_env
from .testing import (
    CliRunner,
    RegexLineMismatch,
    regex_fullmatch_line_by_line,
)

TYPE_CHECKING = False
if TYPE_CHECKING:
    from collections.abc import Iterable
    from pathlib import Path
    from typing import Any

    from _pytest.mark import MarkDecorator
    from _pytest.mark.structures import ParameterSet
```

--------------------------------

### click-extra prebake --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Displays the help for the `click-extra prebake` command, which pre-bakes build-time metadata into Python source files. Lists its subcommands: all, field, help, and version.

```console
$ click-extra prebake --help
Usage: click-extra prebake [OPTIONS] COMMAND [ARGS]...

  Pre-bake build-time metadata into Python source files.

Options:
  -h, --help  Show this message and exit.

Commands:
  all      Pre-bake `__version__`, all git fields and all build fields in one...
  field    Replace an empty dunder variable with a value.
  help     Show help for a command.
  version  Inject Git commit hash into `__version__`.

```

--------------------------------

### OperationTrail.operation() usage example

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/spinner.html

Use inside a concurrent batch to time a single operation: create the handle, run the work, then call mark() with the outcome. The trail records the elapsed time automatically because the handle captured its start time on creation.

```python
def fetch(feed):
    op = trail.operation()
    ok, message = pull(feed)
    op.mark(ok, message)
```

--------------------------------

### HelpFormatOption.__init__: configure --help-format

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/command_doc.html

Constructor for the HelpFormatOption class. Sets the default parameter declaration to `--help-format`, makes it eager and non-exposing, assigns the `print_help_format` callback, and restricts the value to a `click.Choice` of sorted `HELP_FORMATS`. The help text reads "Render the command in the given format and exit.".

```python
    def __init__(
        self,
        param_decls: tuple[str, ...] | None = None,
        expose_value: bool = False,
        is_eager: bool = True,
        help: str = _("Render the command in the given format and exit."),
        **kwargs,
    ) -> None:
        if not param_decls:
            param_decls = ("--help-format",)
        kwargs.setdefault("callback", self.print_help_format)
        kwargs.setdefault("type", click.Choice(sorted(HELP_FORMATS)))
        super().__init__(
            param_decls,
            expose_value=expose_value,
            is_eager=is_eager,
            help=help,
            **kwargs,
        )

```

--------------------------------

### Install pygments extra for highlighting

Source: https://kdeldycke.github.io/click-extra/snippets.html

Installs the pygments extra required for syntax highlighting. Use uv pip install with the extra specification.

```bash
$ uv pip install click-extra[pygments]
```

--------------------------------

### Inject custom keywords with extra_keywords and show help output

Source: https://kdeldycke.github.io/click-extra/colorize.html

Use `extra_keywords` to inject additional strings for highlighting, grouped by category in a `HelpKeywords` dataclass so each gets the appropriate style. The example injects `--profile` as a long option, and the help output shows that `--profile` is highlighted in the option description. The output also displays the full help screen with all default options.

```python
from click_extra import HelpKeywords, command, echo, option

@command(
    extra_keywords=HelpKeywords(long_options={"--profile"}),
)
@option("--output", help="Write to file. See --profile for timing.")
def build(output):
    """Build the project."""
    echo("Building...")
```

```shell
$ build --help
Usage: build [OPTIONS]

  Build the project.

Options:
  --output TEXT                Write to file. See --profile for timing.
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/build/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.
```

--------------------------------

### Example help output showing highlighted keywords

Source: https://kdeldycke.github.io/click-extra/colorize.html

Shows the help output of a command with various options, including color and theme options. This is the baseline output before any keyword exclusions are applied.

```bash
$ export --help
Usage: export [OPTIONS]

  Export data.

Options:
  --format [json|text]         Use json or text.
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/export/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.

```

--------------------------------

### click-extra prebake all --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Shows the help for the `click-extra prebake all` subcommand, which pre-bakes all git and build fields in one pass. It scans target files for empty dunder placeholders, resolves values from Git state and build host, and appends the Git short hash to `.dev` versions. The `--module` option is auto-discovered from `[project.scripts]` if not provided.

```console
$ click-extra prebake all --help
Usage: click-extra prebake all [OPTIONS]

  Pre-bake `__version__`, all git fields and all build fields in one pass.

  Scans each target file for empty `__<field>__` dunder placeholders, resolves
  their values from the current Git state and build host, and injects them.

  Also appends the Git short hash to `.dev` versions in `__version__` (same as
  `prebake version`).

  Supported git fields:
      git_branch, git_long_hash, git_short_hash, git_date, git_tag

  Supported build fields:
      build_time, build_os, build_target, build_target_arch

  Additional computed fields (`__git_tag_sha__`, `__git_distance__`,
  `__git_dirty__`) are baked if their dunder placeholder exists and a git
  resolution is available. Fields without a placeholder in the source file
  are skipped silently.

Options:
  --module PATH  Path to __init__.py to modify. Auto-discovered from
                 [project.scripts] if not provided.
  -h, --help     Show this message and exit.

```

--------------------------------

### Install click-extra with pytest extra group

Source: https://kdeldycke.github.io/click-extra/pytest.html

Install the additional dependencies required for the click_extra.pytest helpers using uv pip install with the pytest extra group.

```bash
$ uv pip install click-extra[pytest]
```

--------------------------------

### Test case for line number starting offset in click directive

Source: https://kdeldycke.github.io/click-extra/_modules/tests/sphinx/test_sphinx_click.html

Defines a test case for the click directive with a custom line number starting offset. The source block starts line numbers at 5, and the run block starts at 10, expecting the output to reflect the shifted line numbers.

```python
        :linenos:
        :lineno-start: 5

        from click import command, echo

        @command
        def numbered_example():
            echo("Line numbers should start from 5")
            echo("and continue incrementing")

```

```python
        :linenos:
        :lineno-start: 10

        invoke(numbered_example)

```

--------------------------------

### click-extra prebake help --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Shows the help for the `click-extra prebake help` subcommand, which displays help for a command. It accepts an optional COMMAND_PATH and a `--search` option to search all subcommands for matching options or descriptions.

```console
$ click-extra prebake help --help
Usage: click-extra prebake help [OPTIONS] [COMMAND_PATH]...

  Show help for a command.

Options:
  --search TEXT  Search all subcommands for matching options or descriptions.
  -h, --help     Show this message and exit.

```

--------------------------------

### click-extra version with enhanced help output

Source: https://kdeldycke.github.io/click-extra/tutorial.html

The same click example but using click_extra as a drop-in replacement. The help screen now includes configuration, output, logging, and introspection options.

```python
import click_extra as click

@click.command
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name", help="The person to greet.")
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for _ in range(count):
        click.echo(f"Hello, {name}!")

```

```text
$ hello --help
Usage: hello [OPTIONS]

  Simple program that greets NAME for a total of COUNT times.

Options:
  --count INTEGER              Number of greetings.  [default: 1]
  --name TEXT                  The person to greet.
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/hello/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.

```

--------------------------------

### click_extra.version.dependency_versions()

Source: https://kdeldycke.github.io/click-extra/version.html

Returns the Click and Cloup releases this install is sitting on, read from installed distributions.

```APIDOC
## `click_extra.version.dependency_versions()`

### Description
Returns the Click and Cloup releases this install is sitting on, read from installed distributions.

### Method
Function call

### Endpoint
`click_extra.version.dependency_versions()`

### Parameters
None

### Return Type
`str`

### Return Example
(Not provided in source)
```

--------------------------------

### click_extra.command_doc.install_manpages

Source: https://kdeldycke.github.io/click-extra/machine-readable.html

Write the command tree's man pages where `man` can find them.

```APIDOC
## `click_extra.command_doc.install_manpages`

### Description
Write the command tree's man pages where `man` can find them. Targets `$XDG_DATA_HOME/man/man1` when that variable is set, else `MAN_INSTALL_DIR`. Returns the written paths. The environment is read here rather than at import time, so a caller that sets `XDG_DATA_HOME` for one invocation (a test, a packaging script staging into a build root) is honored. This mirrors `install_carapace_spec()`, whose spec directory resolves the same way.

### Method
Function call

### Endpoint
`click_extra.command_doc.install_manpages(_command_, _prog_name=None_, **_overrides_)`

### Parameters
#### Path Parameters
- **command** (Click command) - Required - The command to render.

#### Query Parameters
- **prog_name** (str) - Optional - Program name to use.
- **overrides** (keyword arguments) - Optional - Overrides for `version`, `date`, `manual`, `authors`, `copyright`.

### Return Type
`list`[`Path`]
```

--------------------------------

### Run local version with uvx from file

Source: https://kdeldycke.github.io/click-extra/install.html

Runs a local version of the demo CLI from a local directory using uvx.

```shell
$ uvx --from file:///Users/me/code/click-extra -- click-extra
```

--------------------------------

### dark theme: subheading example

Source: https://kdeldycke.github.io/click-extra/theme.html

Subheading example in the 'dark' theme, styled with blue.

```text
◼ 3 mails sharing hash a1b2c3d4
◼ 7 mails sharing hash e5f6a7b8
```

--------------------------------

### dark theme: search example

Source: https://kdeldycke.github.io/click-extra/theme.html

Search example in the 'dark' theme, styled with green.

```text
--retry-budget INTEGER    The retry budget.
```

--------------------------------

### Show supported file patterns with @config_option(show_file_patterns=True)

Source: https://kdeldycke.github.io/click-extra/config-discovery.html

Shows the supported file patterns on the help screen by passing show_file_patterns=True to @config_option. The help output lists every pattern the running install searches for.

```python
from click import command

from click_extra import config_option

@command(context_settings={"show_default": True})
@config_option(show_file_patterns=True)
def cli():
    pass

```

```shell
$ cli --help
Usage: cli [OPTIONS]

Options:
  --config LOCATION  Location of the configuration file. Supports local path
                     with glob patterns or remote URL.  [default: ~/.config/cli/
                     {*.toml,*.yaml,*.yml,*.json,*.json5,*.jwcc,*.jsonc,*.hjson,
                     *.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.tom
                     l}]
  --help             Show this message and exit.

```

--------------------------------

### ManOption.__init__: configure --man flag

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/command_doc.html

Constructor for the ManOption class. Sets the default parameter declaration to `--man`, marks it as a flag, eager, and non-exposing, and assigns the `print_man` callback. The help text reads "Read the command's manual page and exit.".

```python
    def __init__(
        self,
        param_decls: tuple[str, ...] | None = None,
        is_flag: bool = True,
        expose_value: bool = False,
        is_eager: bool = True,
        help: str = _("Read the command's manual page and exit."),
        **kwargs,
    ) -> None:
        if not param_decls:
            param_decls = ("--man",)
        kwargs.setdefault("callback", self.print_man)
        super().__init__(
            param_decls,
            is_flag=is_flag,
            expose_value=expose_value,
            is_eager=is_eager,
            help=help,
            **kwargs,
        )

```

--------------------------------

### dark theme: bracket example

Source: https://kdeldycke.github.io/click-extra/theme.html

Bracket example in the 'dark' theme, styled with dim.

```text
--port INTEGER    [env var: PORT; default: 8080; required]
```

--------------------------------

### Show click-extra version

Source: https://kdeldycke.github.io/click-extra/install.html

Run the demo CLI with --version to show the current version. The output is not shown in the source.

```shell
$ uvx click-extra --version

```

--------------------------------

### dark theme: envvar example

Source: https://kdeldycke.github.io/click-extra/theme.html

Envvar example in the 'dark' theme, styled with yellow dim.

```text
--threshold INTEGER   Acceptable error rate.
                      [env var: THRESHOLD, TEST_THRESHOLD]
```

--------------------------------

### Run demo CLI with uvx (latest release)

Source: https://kdeldycke.github.io/click-extra/install.html

Runs the demo CLI directly with uvx, without installing dependencies or a virtual environment.

```shell
$ uvx click-extra
```

--------------------------------

### click_extra.version.env_summary()

Source: https://kdeldycke.github.io/click-extra/version.html

Returns a one-line interpreter and platform summary, suitable for a plain `--version` output.

```APIDOC
## `click_extra.version.env_summary()`

### Description
Returns a one-line interpreter and platform summary, suitable for a plain `--version` output.

### Method
Function call

### Endpoint
`click_extra.version.env_summary()`

### Parameters
None

### Return Type
`str`

### Return Example
(Not provided in source)
```

--------------------------------

### dark theme: option examples

Source: https://kdeldycke.github.io/click-extra/theme.html

Option examples in the 'dark' theme, styled with cyan bold.

```text
--config LOCATION    Location of the configuration file.
-v, --verbose        Increase verbosity.
```

--------------------------------

### Show help in JSON format with --help-format json

Source: https://kdeldycke.github.io/click-extra/commands.html

Request the machine-readable JSON rendering of the command's help. The examples are included as structured entries rather than prose, and the output is truncated in the source.

```shell
$ forecast --help-format json
{
  "name": "forecast",
  "short_help": "Report the forecast for a city.",
  "version": null,
  "synopsis": "forecast [OPTIONS]",
  "description": "Report the forecast for a city.",
  "arguments": [],
  "option_groups": [
    {
      "title": "Options",
      "help": null,
      "options": [
        {
          "names": [
            "--units"
          ],
          "spec": "--units TEXT",
          "metavar": "TEXT",
          "choices": null,
          "help": "Temperature scale to display.",
          "required": false,
          "optional_value": false
        },
        {
          "names": [

```

--------------------------------

### dark theme: alias example

Source: https://kdeldycke.github.io/click-extra/theme.html

Alias example in the 'dark' theme, styled with cyan bold.

```text
  show, ls     Show the current state.
```

--------------------------------

### lazy_subcommands example

Source: https://kdeldycke.github.io/click-extra/commands.html

Example of a `lazy_subcommands` map with a single command name mapped to its import path.

```python
{"mycmd": "my_cli.commands.mycmd"}
```

--------------------------------

### Export configuration with --export-config (weather example)

Source: https://kdeldycke.github.io/click-extra/config.html

Defines a weather command with options and shows how --export-config renders the resolved configuration to TOML, including values set on the command line, and how to redirect the output to a configuration file.

```python
from click_extra import command, echo, option

@command
@option("--city", default="Lisbon")
@option("--temperature", type=int, default=18)
@option("--tags", multiple=True, default=("sunny",))
def weather(city, temperature, tags):
    echo(f"{city}: {temperature}C {tags!r}")

```

```bash
$ weather --export-config toml
[weather]
city = "Lisbon"
temperature = 18
tags = ["sunny"]
time = false
accessible = false
color = "auto"
no-color = false
progress = true
theme = "dark"
table-format = "rounded-outline"
verbosity = "WARNING"
verbose = 0
quiet = 0
debug = false
tree = false
man = false
# help-format =

```

```bash
$ weather --city Oslo --temperature 4 --export-config toml
[weather]
city = "Oslo"
temperature = 4
tags = ["sunny"]
time = false
accessible = false
color = "auto"
no-color = false
progress = true
theme = "dark"
table-format = "rounded-outline"
verbosity = "WARNING"
verbose = 0
quiet = 0
debug = false
tree = false
man = false
# help-format =

```

```bash
$ weather --city Oslo --export-config toml > ~/.config/weather/config.toml

```

--------------------------------

### Run wrap.py and view generated help output

Source: https://kdeldycke.github.io/click-extra/commands.html

Run the wrap.py script with uv and observe its generated help output. The output shows the full CLI structure, including configuration, output, logging, and introspection options, plus the available subcommands (aws_sam, dbt, help).

```text
$ uv run -- python ./wrap.py
Usage: wrap.py [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/Library/Application Support/wrap.py/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.

Commands:
  aws_sam  AWS Serverless Application Model (SAM) CLI
  dbt      An ELT tool for managing your SQL transformations and data models.
  help     Show help for a command.

```

--------------------------------

### Install pytest extra

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the pytest extra to provide fixtures and utilities for testing Click CLIs.

```shell
$ uv pip install click-extra[pytest]

```

--------------------------------

### Install pygments extra

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the pygments extra to enable ANSI-capable formatter, filter, and lexers for Pygments.

```shell
$ uv pip install click-extra[pygments]

```

--------------------------------

### kitchen pantry jars --help

Source: https://kdeldycke.github.io/click-extra/sphinx.html

Shows the help screen for the `kitchen pantry jars` command, which lists jars on the shelf.

```console
$ kitchen pantry jars --help
Usage: kitchen pantry jars [OPTIONS]

  List jars on the shelf.

Options:
  -h, --help  Show this message and exit.

```

--------------------------------

### dark theme: metavar examples

Source: https://kdeldycke.github.io/click-extra/theme.html

Metavar examples in the 'dark' theme, styled with cyan dim italic.

```text
--output TEXT       Destination file.
--workers INTEGER   Worker count.
```

--------------------------------

### Subcommand with configuration file applied

Source: https://kdeldycke.github.io/click-extra/config.html

Run with the config file, showing the changed defaults.

```bash
$ my-cli subcommand
dummy_flag  is True
my_list     is ('item 1', 'item #2', 'Very Last Item!')
int_parameter is 3
```

--------------------------------

### Home-relative default configuration pattern

Source: https://kdeldycke.github.io/click-extra/click_extra.config.html

Shown in the get_help_extra() documentation, this is the pretty path displayed in help, relative to the user's home directory.

```text
~/folder/my_cli/{*.toml,*.json,*.ini}
```

--------------------------------

### Install mkdocs extra

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the mkdocs extra to enable ANSI color rendering in MkDocs code blocks.

```shell
$ uv pip install click-extra[mkdocs]

```

--------------------------------

### HelpTheme.light() static method

Source: https://kdeldycke.github.io/click-extra/_modules/cloup/styling.html

Returns a HelpTheme configured for a light terminal background, using yellow for invoked commands and column 1, bright blue for headings, and red for constraints.

```python
@staticmethod
    def light() -> "HelpTheme":
        """A theme assuming a light terminal background color."""
        return HelpTheme(
            invoked_command=Style(fg='yellow'),
            heading=Style(fg='bright_blue'),
            constraint=Style(fg='red'),
            col1=Style(fg='yellow'),
        )
```

--------------------------------

### Install toml extra

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the toml extra to enable the toml table format (--table-format toml).

```shell
$ uv pip install click-extra[toml]

```