API Reference

Protocols

CLIApplicationProtocol

Protocol for a top-level CLI application.

A CLIApplication owns a CLIRunnerProtocol and manages the full lifecycle of a CLI process: configuration loading, provider boot, command dispatch, and shutdown.

property runner() -> CLIRunnerProtocol

The underlying command runner.

async def boot() -> None

Start the application, boot providers, and prepare for dispatch.

async def shutdown() -> None

Tear down resources and exit cleanly.

---

CLIRunnerProtocol

Protocol for objects that can run CLI commands.

A CLIRunner discovers registered CommandProtocol implementations and dispatches invocations based on the command name. Implementations may wrap Click, Typer, argparse, or any other CLI framework.

def run(argv: list[str] | None = None) -> int

Parse argv (or sys.argv) and dispatch to the matching command.

Parameters

Parameter	Type	Description
`argv`	list[str] | None	Argument vector to parse. Defaults to ``sys.argv[1:]``.

Returns

Type	Description
int	Exit code (0 for success, non-zero for failure).

def register_command(command: CommandProtocol) -> None

Register a command with this runner.

Parameters

Parameter	Type	Description
`command`	CommandProtocol	A CommandProtocol implementation to register.

---

CommandProtocol

Protocol for CLI command implementations.

def execute(
    args: list[str],
    options: dict[str, Any]
) -> int

Execute the command.

Parameters

Parameter	Type	Description
`args`	list[str]	Positional arguments
`options`	dict[str, Any]	Parsed options dictionary

Returns

Type	Description
int	Exit code (0 for success)

property name() -> str

Command name.

property description() -> str

Command description.

def get_help() -> str

Get help text for the command.

Returns

Type	Description
str	Help text

---

Classes

CLIConfig

---

CLIContext

Shared context object passed through Typer to all commands.

Holds the OutputManager, loaded config, and global flag state.

def __init__(
    *,
    json_mode: bool = False,
    quiet: bool = False,
    debug: bool = False,
    no_color: bool = False,
    config_path: Path | None = None
) -> None

async def load_config_data() -> dict[str, Any]

Lazily load and return config data asynchronously.

property config_data() -> dict[str, Any]

Lazily load and return the config data for synchronous call sites.

def require_config() -> dict[str, Any]

Load config, raising ConfigNotFoundError if absent.

---

CLIModule

CLI command registration and configuration.

Call configure to configure the CLI provider.

Usage

from lexigram.cli.config import CLIConfig

@module(
    imports=[CLIModule.configure(CLIConfig(...))]
)
class AppModule(Module):
    pass

def configure(
    cls,
    config: Any | None = None
) -> DynamicModule

Create a CLIModule with explicit configuration.

Parameters

Parameter	Type	Description
`config`	Any | None	CLIConfig or ``None`` for framework defaults.

Returns

Type	Description
DynamicModule	A DynamicModule descriptor.

def stub(cls) -> DynamicModule

Return a no-op CLIModule for testing.

Registers the CLI provider with default configuration. No commands are registered by default.

Returns

Type	Description
DynamicModule	A DynamicModule with default CLI configuration.

---

OutputManager

Unified output manager for all CLI commands.

def __init__(
    *,
    json_mode: bool = False,
    quiet: bool = False,
    debug: bool = False,
    no_color: bool = False
) -> None

def success(
    message: str,
    data: dict[str, Any] | None = None
) -> None

Print a success message.

def error(
    message: str,
    hint: str | None = None
) -> None

Print an error message. Shown even in quiet mode.

def warning(message: str) -> None

Print a warning message.

def info(message: str) -> None

Print an informational message.

def table(
    headers: list[str],
    rows: list[list[str]]
) -> None

Print tabular data.

def key_value(data: dict[str, Any]) -> None

Print key-value pairs.

def cli_error(err: CliError) -> None

Render a structured CLIError with causes and suggestions.

def debug_msg(message: str) -> None

Print a debug message (only shown in debug mode).

def print(
    *args: Any,
    **kwargs: Any
) -> None

Pass-through to Rich console.print for one-off needs.

---

Functions

find_config

def find_config(
    *,
    explicit_path: Path | None = None,
    start_dir: Path | None = None
) -> Path

Locate the lexigram config file.

Parameters

Parameter	Type	Description
`explicit_path`	Path | None	If given, use this path directly.
`start_dir`	Path | None	Directory to start searching from (default: CWD).

Returns

Type	Description
Path	Resolved Path to the config file.

Raises

Exception	Description
ConfigNotFoundError	If no config file is found.

---

handle_errors

def handle_errors(func: F) -> F

Decorator that catches exceptions and renders friendly CLI errors.

Wraps a Typer command function to catch CliError (renders with causes/suggestions) and unexpected exceptions (renders with traceback hint).

---

load_config_yaml

def load_config_yaml(path: Path) -> dict[str, Any]

Load and parse a YAML config file from synchronous call sites.

---

Exceptions

CliError

Base exception for lexigram-cli operations.

def __init__(
    message: str | None = None,
    causes: list[str] | None = None,
    suggestions: list[str] | None = None,
    **kwargs: Any
) -> None

Initialize CLI error.

Parameters

Parameter	Type	Description
`message`	str | None	Human-readable error message.
`causes`	list[str] | None	List of potential causes for the error.
`suggestions`	list[str] | None	List of suggestions to resolve the error. **kwargs: Additional keyword arguments passed to parent.

---

ConfigNotFoundError

Raised when application.yaml configuration file is not found.

def __init__() -> None

Initialize config not found error.

---

ProviderNotInstalledError

Raised when a required provider package is not installed.

def __init__(provider: str) -> None

Initialize provider not installed error.

Parameters

Parameter	Type	Description
`provider`	str	Name of the missing provider.

---