API Reference

Protocols

CLIApplicationProtocol

source

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.

runner

property runner() -> CLIRunnerProtocol

source

The underlying command runner.

boot

async def boot() -> None

source

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

shutdown

async def shutdown() -> None

source

Tear down resources and exit cleanly.

---

CLIRunnerProtocol

source

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.

run

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

source

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).

register_command

def register_command(command: CommandProtocol) -> None

source

Register a command with this runner.

Parameters

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

---

CommandProtocol

source

Protocol for CLI command implementations.

execute

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

source

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)

name

property name() -> str

source

Command name.

description

property description() -> str

source

Command description.

get_help

def get_help() -> str

source

Get help text for the command.

Returns

Type	Description
str	Help text

---

Classes

CLIConfig

source

---

CLIContext

source

Shared context object passed through Typer to all commands.

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

__init__

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

source

load_config_data

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

source

Lazily load and return config data asynchronously.

config_data

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

source

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

require_config

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

source

Load config, raising ConfigNotFoundError if absent.

---

CLIModule

source

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

from lexigram.cli.config import CLIConfig

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

configure

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

source

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.

stub

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

source

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

source

Unified output manager for all CLI commands.

__init__

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

source

success

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

source

Print a success message.

error

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

source

Print an error message. Shown even in quiet mode.

warning

def warning(message: str) -> None

source

Print a warning message.

info

def info(message: str) -> None

source

Print an informational message.

table

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

source

Print tabular data.

key_value

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

source

Print key-value pairs.

cli_error

def cli_error(err: CliError) -> None

source

Render a structured CLIError with causes and suggestions.

debug_msg

def debug_msg(message: str) -> None

source

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

print

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

source

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

---

Functions

find_config

find_config

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

source

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

handle_errors

def handle_errors(func: F) -> F

source

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

load_config_yaml

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

source

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

---

Exceptions

CliError

source

Base exception for lexigram-cli operations.

__init__

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

source

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

source

Raised when application.yaml configuration file is not found.

__init__

def __init__() -> None

source

Initialize config not found error.

---

ProviderNotInstalledError

source

Raised when a required provider package is not installed.

__init__

def __init__(provider: str) -> None

source

Initialize provider not installed error.

Parameters

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

---