Module

context

Execution context for CLI command handlers.

2Classes2Functions

Classes

Context 19 ▼
Execution context available to all command handlers. Handlers opt in by adding a ``ctx: Context`` …

Execution context available to all command handlers.

Handlers opt in by adding actx: Contextparameter::

@cli.command("build", description="Build the site")
def build(output: str = "_site", ctx: Context = None) -> str:
    ctx.log("Starting build...", level=1)  # verbose only
    return f"Built to {output}"

The context is injected automatically by the CLI dispatcher and excluded from argparse and MCP schemas.

Attributes

Name Type Description
verbosity int —
format str —
color bool —
dry_run bool —
output_file str —
globals dict[str, Any] —

Methods

quiet 0 bool ▼
True when --quiet was passed.
property
def quiet(self) -> bool
Returns
bool
verbose 0 bool ▼
True when --verbose was passed.
property
def verbose(self) -> bool
Returns
bool
debug 0 bool ▼
True when -vv (or higher) was passed.
property
def debug(self) -> bool
Returns
bool
is_ci 0 bool ▼
True when running in CI (CI env var is set).
property
def is_ci(self) -> bool
Returns
bool
is_interactive 0 bool ▼
True when stdin is a TTY.
property
def is_interactive(self) -> bool
Returns
bool
log 2 ▼
Print a message if verbosity is at or above *level*. level 0 = normal (always …
def log(self, message: str, *, level: int = 0) -> None

Print a message if verbosity is at or above level.

level 0 = normal (always shown unless quiet) level 1 = verbose (shown with --verbose) level 2 = debug (shown with -vv)

Parameters
Name Type Description
message —
level — Default:0
info 1 ▼
Print an informational message (level 0).
def info(self, message: str) -> None
Parameters
Name Type Description
message —
success 1 ▼
Print a success message (level 0).
def success(self, message: str) -> None
Parameters
Name Type Description
message —
warning 1 ▼
Print a warning message (always shown, even in quiet mode).
def warning(self, message: str) -> None
Parameters
Name Type Description
message —
error 1 ▼
Print an error message (always shown).
def error(self, message: str) -> None
Parameters
Name Type Description
message —
confirm 2 bool ▼
Prompt for yes/no confirmation. Returns default in non-interactive mode. In dr…
def confirm(self, message: str, *, default: bool = False) -> bool

Prompt for yes/no confirmation. Returns default in non-interactive mode.

In dry-run mode, always returns False.

Parameters
Name Type Description
message —
default — Default:False
Returns
bool
progress 2 CLIProgress ▼
Create an inline progress indicator for CLI commands. Usage:: with ctx.pr…
def progress(self, total: int = 0, *, label: str = '') -> CLIProgress

Create an inline progress indicator for CLI commands.

Usage::

with ctx.progress(total=100, label="Downloading") as p:
    for i in range(100):
        do_work()
        p.update(1)
Parameters
Name Type Description
total — Default:0
label — Default:''
Returns
CLIProgress
run_app 6 Any ▼
Launch an interactive App session and return the final state. Bridges CLI comm…
def run_app(self, reducer: Callable, template: str, initial_state: Any = None, *, env: Any = None, exit_template: str = '', tick_rate: float = 0.0) -> Any

Launch an interactive App session and return the final state.

Bridges CLI command handlers to the Elm-style App event loop. The command blocks until the user quits the App, then returns the final state for the handler to process further.

Usage in a CLI command::

@cli.command("pick", description="Pick a file")
def pick(directory: str = ".", ctx: Context = None) -> str:
    state = ctx.run_app(
        reducer=picker_reducer,
        template="picker.kida",
        initial_state=PickerState(root=directory),
        env=env,
    )
    return state.selected_file
Parameters
Name Type Description
reducer —
template —
initial_state — Default:None
env — Default:None
exit_template — Default:''
tick_rate — Default:0.0
Returns
Any
CLIProgress 5 ▼
Inline progress bar for CLI commands.

Inline progress bar for CLI commands.

Methods

update 1 ▼
Advance progress by n steps.
def update(self, n: int = 1) -> None
Parameters
Name Type Description
n — Default:1
set 1 ▼
Set progress to an absolute value.
def set(self, n: int) -> None
Parameters
Name Type Description
n —
Internal Methods 3 ▼
__init__ 4 ▼
def __init__(self, *, total: int = 0, label: str = '', color: bool = True, quiet: bool = False) -> None
Parameters
Name Type Description
total — Default:0
label — Default:''
color — Default:True
quiet — Default:False
__enter__ 0 CLIProgress ▼
def __enter__(self) -> CLIProgress
Returns
CLIProgress
__exit__ 1 ▼
def __exit__(self, *exc: object) -> None
Parameters
Name Type Description
*exc —

Functions

get_context 0 Context ▼
Get the current execution context. Returns a default Context if none has been …
def get_context() -> Context

Get the current execution context.

Returns a default Context if none has been set.

Returns
Context
set_context 1 None ▼
Set the current execution context.
def set_context(ctx: Context) -> None
Parameters
Name Type Description
ctx Context