Module

_command_defs

Command definition types and helpers.

8Classes3Functions

Classes

GlobalOption 6 ▼
A CLI-wide option available to all commands via Context.

A CLI-wide option available to all commands via Context.

Attributes

Name Type Description
name str —
short str —
option_type type —
default Any —
description str —
is_flag bool —
RootOptionSpec 8 ▼
Parser-independent metadata for a CLI-wide root option.

Parser-independent metadata for a CLI-wide root option.

Attributes

Name Type Description
flags tuple[str, ...] —
dest str —
description str —
action Literal['help', 'version_report', 'store', 'store_true', 'count'] —
default Any —
option_type type | None —
choices tuple[str, ...] —
metavar str —
ResourceDef 5 ▼
A registered MCP resource.

A registered MCP resource.

Attributes

Name Type Description
uri str —
name str —
description str —
handler Callable[..., Any] —
mime_type str —
PromptDef 4 ▼
A registered MCP prompt.

A registered MCP prompt.

Attributes

Name Type Description
name str —
description str —
handler Callable[..., Any] —
arguments tuple[dict[str, Any], ...] —
CommandDef 15 ▼
A registered CLI command.

A registered CLI command.

Attributes

Name Type Description
name str —
description str —
handler Callable[..., Any] —
schema dict[str, Any] —
aliases tuple[str, ...] —
tags tuple[str, ...] —
hidden bool —
surfaces tuple[CommandSurface, ...] —
examples tuple[dict[str, Any], ...] —
confirm str —
annotations dict[str, Any] —
display_result bool —
terminal_renderer Callable[[Any, Any], str] | None —
ui MCPAppToolMeta | None —

Methods

Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
LazyCommandDef 4 ▼
A command whose handler is imported on first use. Stores a dotted import path (``module:attribute`…

A command whose handler is imported on first use.

Stores a dotted import path (module:attribute) and defers the actual import until the command is invoked. This keeps CLI startup fast even with dozens of commands.

If schema is provided upfront, MCPtools/listand llms.txt can be generated without importing the handler module at all.

Methods

schema 0 dict[str, Any] ▼
Return pre-computed schema or resolve to get it.
property
def schema(self) -> dict[str, Any]
Returns
dict[str, Any]
handler 0 Callable[..., Any] ▼
Resolve and return the handler function.
property
def handler(self) -> Callable[..., Any]
Returns
Callable[..., Any]
resolve 0 CommandDef ▼
Import the handler and cache as a full CommandDef. Thread-safe. Raises `LazyIm…
def resolve(self) -> CommandDef

Import the handler and cache as a full CommandDef. Thread-safe.

RaisesLazyImportErrorif the module or attribute cannot be imported, wrapping the original exception with a clear message.

Returns
CommandDef
Internal Methods 1 ▼
__init__ 14 ▼
def __init__(self, name: str, import_path: str, description: str = '', *, schema: dict[str, Any] | None = None, aliases: tuple[str, ...] | list[str] = (), tags: tuple[str, ...] | list[str] = (), hidden: bool = False, surfaces: tuple[CommandSurface, ...] | list[CommandSurface] = ('cli', 'mcp', 'llms'), examples: tuple[dict[str, Any], ...] | list[dict[str, Any]] = (), confirm: str = '', annotations: dict[str, Any] | None = None, display_result: bool = True, terminal_renderer: Callable[[Any, Any], str] | None = None, ui: MCPAppToolMeta | None = None) -> None
Parameters
Name Type Description
name —
import_path —
description — Default:''
schema — Default:None
aliases — Default:()
tags — Default:()
hidden — Default:False
surfaces — Default:('cli', 'mcp', 'llms')
examples — Default:()
confirm — Default:''
annotations — Default:None
display_result — Default:True
terminal_renderer — Default:None
ui — Default:None
InvokeResult 5 ▼
Result of CLI.invoke() for testing.

Result of CLI.invoke() for testing.

Attributes

Name Type Description
output str —
exit_code int —
result Any —
exception Exception | None —
stderr str —
LazyImportError 1 ▼
Raised when a lazy command's import fails. Wraps the original exception with the command name and …

Raised when a lazy command's import fails.

Wraps the original exception with the command name and import path so callers can provide actionable error messages.

Methods

Internal Methods 1 ▼
__init__ 3 ▼
def __init__(self, command_name: str, import_path: str, cause: Exception) -> None
Parameters
Name Type Description
command_name —
import_path —
cause —

Functions

_normalize_surfaces 1 tuple[CommandSurface, ..… ▼
Validate and de-duplicate command discovery surfaces.
def _normalize_surfaces(surfaces: tuple[CommandSurface, ...] | list[CommandSurface]) -> tuple[CommandSurface, ...]
Parameters
Name Type Description
surfaces tuple[CommandSurface, ...] | list[CommandSurface]
Returns
tuple[CommandSurface, ...]
_make_command_def 13 CommandDef ▼
Build a CommandDef from a function and decorator kwargs.
def _make_command_def(name: str, func: Callable, *, description: str = '', aliases: tuple[str, ...] = (), tags: tuple[str, ...] = (), hidden: bool = False, surfaces: tuple[CommandSurface, ...] = ('cli', 'mcp', 'llms'), examples: tuple[dict[str, Any], ...] = (), confirm: str = '', annotations: dict[str, Any] | None = None, display_result: bool = True, terminal_renderer: Callable[[Any, Any], str] | None = None, ui: MCPAppToolMeta | None = None) -> CommandDef
Parameters
Name Type Description
name str
func Callable
description str Default:''
aliases tuple[str, ...] Default:()
tags tuple[str, ...] Default:()
hidden bool Default:False
surfaces tuple[CommandSurface, ...] Default:('cli', 'mcp', 'llms')
examples tuple[dict[str, Any], ...] Default:()
confirm str Default:''
annotations dict[str, Any] | None Default:None
display_result bool Default:True
terminal_renderer Callable[[Any, Any], str] | None Default:None
ui MCPAppToolMeta | None Default:None
Returns
CommandDef
_is_context_param 1 bool ▼
Check if a parameter is a Context injection point.
def _is_context_param(param: inspect.Parameter) -> bool
Parameters
Name Type Description
param inspect.Parameter
Returns
bool