Home
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT CLI is a developer-focused Command Line Interface foundation and library designed for building enterprise-grade, typed CLI tools. It provides a public facade (cli) that abstracts complex operations such as file I/O, prompt handling, and output formatting into a consistent, type-safe interface.
Sources: README.md:1-10, examples/README.md:1-10
Core Architecture and Design Patterns
The project is built around several key architectural pillars: the Public Facade, the Railway Result pattern, and Pydantic-driven validation.
The Public Facade (cli)
Developers are encouraged to interact with the library through the flext_cli.cli facade. This singleton-like pattern ensures consistency across different modules of a CLI application, providing unified access to settings, output formatting, and filesystem operations.
Sources: examples/README.md:12-25, examples/ex_11_complete_integration.py:34-45
Railway Result Pattern (r)
FLEXT CLI utilizes the "Railway" pattern for error handling. Fallible operations return a p.Result object (often instantiated via the r alias), which explicitly tracks success or failure without relying on exceptions for flow control.
Sources: examples/README.md:46-55, examples/ex_11_complete_integration.py:48-55
Pydantic Integration
The system leverages Pydantic 2 for data validation and settings management. CLI payloads are validated against Pydantic models, ensuring that data entering the application logic is strictly typed and well-formed.
Sources: examples/README.md:65-72, examples/ex_12_pydantic_driven_cli.py:1-20
Component Overview
The following diagram illustrates the high-level flow of data from a user request through the public facade to the underlying utilities.
The diagram shows how the cli facade acts as the central gateway for developers to access various subsystems like I/O, UI, and Settings.
Sources: examples/README.md:38-60, src/flext_cli/_utilities/init.py:1-50
Configuration and Dependencies
The project is configured via pyproject.toml and follows strict engineering standards defined in AGENTS.md.
Key Dependencies
| Dependency | Purpose |
|---|---|
click | Underlying CLI argument parsing |
pydantic | Data validation and settings models |
rich | Enhanced terminal output and formatting |
flext-core | Core protocols and result contracts |
tomlkit | TOML parsing for configuration files |
Sources: pyproject.toml:22-35
Development Quality Gates
The project enforces high code quality through a "Make Contract" and several automated gates:
- Linting: Ruff, Pyrefly, and Mypy.
- Testing: Pytest with a focus on 100% coverage via public interfaces.
- Formatting: Black and Taplo (for TOML).
Sources: README.md:44-48, AGENTS.md:100-115, src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_06.py:80-95
Integration Example
A typical integration involves deriving a service from the base class s and using the cli facade for execution.
from examples import p, r, s, t
from flext_cli import cli
class DataTask(s):
def execute(self) -> p.Result[t.JsonMapping]:
# Using the facade for a typed read
data_result = cli.read_json_file("data.json")
if data_result.failure:
return r[t.JsonMapping].fail(f"Read failed: {data_result.error}")
cli.print("Data loaded successfully!", style="green")
return r[t.JsonMapping].ok(data_result.value)
Sources: examples/README.md:30-45, examples/ex_11_complete_integration.py:58-75
Execution Flow
The sequence of a typical CLI command execution follows a structured path from initialization to result return.
This diagram demonstrates the interaction between the application logic, the public facade, and the result contract.
Sources: examples/ex_01_getting_started.py:48-90, examples/ex_11_complete_integration.py:100-120
Summary
FLEXT CLI provides a robust framework for building CLI tools by abstracting low-level terminal and filesystem operations. By enforcing the Railway Result pattern and Pydantic validation, it ensures that developers build resilient and type-safe applications while maintaining a consistent user experience through its public facade.