commands

Register a global option available to all commands via Context.

Usage::

cli.global_option("environment", short="-e", default="local",
                  description="Config environment")

Register a hook that runs before every command.

The hook receives (ctx, command_name, kwargs) and can modify kwargs.

Usage::

@cli.before_command
def check_auth(ctx, command_name, kwargs):
    if not os.environ.get("API_KEY"):
        raise SystemExit("API_KEY not set")

Register a hook that runs after every command.

The hook receives (ctx, command_name, result).

Usage::

@cli.after_command
def log_result(ctx, command_name, result):
    ctx.log(f"{command_name} completed", level=1)

Register a function as a CLI command.

The function's type annotations drive:

• argparse argument generation
• MCP tool schema
• help text

Register a lazy-loaded command.

The handler module is not imported until the command is invoked. This keeps CLI startup fast for large command sets.

When providing a pre-computed schema, include"default"fields in properties for optional parameters so argparse receives the correct defaults without importing the handler module.

Register a function as an MCP resource.

Usage::

@cli.resource("config://app", description="App config")
def get_config() -> dict: ...

Register a function as an MCP prompt.

Usage::

@cli.prompt("deploy-checklist", description="Pre-deploy steps")
def checklist(environment: str) -> list[dict]: ...

Register a middleware function.

Usage::

@cli.middleware
def log_calls(ctx, call, next_fn):
    result = next_fn(call)
    return result

Create and register a command group.

Returns the Group for registering commands within it::

site = cli.group("site", description="Site operations")

@site.command("build", description="Build the site")
def build(output: str = "_site") -> str: ...

Mount another CLI as a command group. In-process, no subprocess.

Usage::

main = CLI(name="main")
sub = CLI(name="sub")
main.mount("sub", sub)
# sub's commands are now at main.sub.*

Look up a command by name, alias, or dotted path.

Dotted paths traverse groups:get_command("site.build") resolves to thebuild command inside the sitegroup.

Yield all commands in the tree as (dotted_path, CommandDef) tuples.

Top-level commands have simple names. Group commands use dots::

[("greet", greet_cmd), ("site.build", build_cmd), ...]

Run a command and capture output for testing.

Stdout and stderr are captured separately.outputcontains stdout (command results),stderrcontains log/error messages.

Usage::

result = cli.invoke(["greet", "--name", "Alice"])
assert result.exit_code == 0
assert "Alice" in result.output
assert result.stderr == ""  # no warnings

Programmatically call a command by name or dotted path.

Used by MCP server and for programmatic invocation::

cli.call("greet", name="Alice")
cli.call("site.build", output="_site")

Arguments are validated and string inputs are coerced against the command's generated schema before hooks or handlers run.

A host-providedctxcan route output and approvals without touching process-global streams. Context remains invisible to command schemas and is injected into the handler as usual.

Call a command without consuming generators.

Likecall(), but returns the raw result — if the handler returns a generator, it is not consumed. The MCP server uses this to streamProgressyields as notifications. Arguments use the same schema validation and coercion ascall().