Command Registration & Routing
Relevant source files
The following files were used as context for generating this wiki page:
The Command Registration & Routing system in flext-cli provides a structured, type-safe framework for defining, validating, and executing developer commands. It leverages a public facade (cli) to orchestrate complex workflows while maintaining a consistent "Railway" pattern for error handling. The system is designed to handle everything from simple CLI tool execution to advanced Pydantic-driven parameter conversion, ensuring that command logic is separated from implementation details.
At its core, the system utilizes high-level services like FlextCliCmd to manage runtime state and execution status. It integrates with Pydantic models to automate parameter definition and validation, reducing the need for manual argument parsing. This architecture supports both synchronous execution and automated configuration snapshots, providing developers with clear visibility into the command environment.
Sources: tests/unit/test_cmd.py:41-55, examples/ex_12_pydantic_driven_cli.py:1-25
Command Execution Architecture
Command execution is managed through a central facade that routes requests to underlying service implementations. The primary entry point for status and basic execution is the execute() method, which returns a structured result containing service status and version information.
The diagram above illustrates the high-level flow from a user call through the public facade to the command service, resulting in a structured response.
Sources: tests/unit/test_cmd.py:57-65, src/flext_cli/_protocols/_base_parts/flextcliprotocolsbase_part_03.py:25-30
Key Execution Components
| Component | Description |
|---|---|
FlextCliCmd | Main service class responsible for coordinating command operations and settings snapshots. |
CommandRunner | A protocol defining the contract for executing external shell commands with strict error checking. |
p.Result | A functional-style container used for all return values to handle success and failure paths. |
Sources: src/flext_cli/_protocols/_base_parts/flextcliprotocolsbase_part_03.py:22-60, tests/unit/test_cmd.py:47-55
Pydantic-Driven Routing
The routing system supports advanced parameter conversion where CLI options are automatically derived from Pydantic models. This eliminates manual Click decorator management and ensures type consistency between configuration and execution.
Automatic Parameter Mapping
The CliModelConverter translates Pydantic fields into CLI-ready parameters, including types, defaults, and help text. This is often implemented using a "Railway Pattern" that chains validation steps before final execution.
This sequence shows how raw input is transformed into a typed model before reaching business logic.
Sources: examples/ex_12_pydantic_driven_cli.py:53-100, pyproject.toml:25-35
Implementation Example: Database Config Routing
The following snippet demonstrates how a CLI command routes data through multiple validation stages using the Result pattern.
def create_database_config_from_cli() -> p.Result[m.Examples.AdvancedDatabaseConfig]:
return (
validate_required_fields(cli_args)
.flat_map(convert_and_validate_with_pydantic)
.flat_map(validate_business_rules)
.flat_map(perform_connection_test)
)
Sources: examples/ex_12_pydantic_driven_cli.py:65-115
Configuration Routing & Snapshots
The system provides specialized routing for inspecting the environment and configuration state through settings_snapshot. This allows commands to be aware of their filesystem context (e.g., whether settings directories exist and are writable).
Settings Snapshot Data Model
| Field | Type | Description |
|---|---|---|
settings_dir | str | Path to the canonical configuration directory (typically in HOME). |
settings_exists | bool | Flag indicating if the directory exists. |
settings_readable | bool | Flag indicating read permissions. |
settings_writable | bool | Flag indicating write permissions. |
Sources: tests/unit/test_cmd.py:73-85, src/flext_cli/_utilities/cmd.py
External Command Routing
For commands that require executing external processes, the CommandRunner protocol defines standard routing methods. This ensures that sub-processes are called with consistent environment variables and timeout protections.
| Method | Purpose | Returns |
|---|---|---|
run | Execute command with zero-exit enforcement. | p.Result[CommandOutput] |
capture | Execute and return stripped stdout. | p.Result[str] |
run_raw | Execute without enforcing exit status. | p.Result[CommandOutput] |
run_checked | Simple success/failure check. | p.Result[bool] |
Sources: src/flext_cli/_protocols/_base_parts/flextcliprotocolsbase_part_03.py:25-50
Conclusion
The Command Registration & Routing module centralizes command orchestration through a type-safe, Pydantic-integrated architecture. By utilizing the Result pattern and structured snapshots, it ensures that developers can build complex CLI workflows that are both resilient and easy to debug. The separation between process execution (via CommandRunner) and parameter validation (via Pydantic) provides a scalable foundation for developer tools.