Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT CLI is a developer-centric Command Line Interface framework designed for building type-safe, production-ready CLI applications. It leverages a "public facade" pattern to provide a consistent interface for output formatting, file I/O, and user prompts, all governed by Pydantic-driven validation and a railway-oriented result contract.
The framework emphasizes a structured approach to CLI development, utilizing service bases for typed settings access and standardized result handling via p.Result and the r helper. This ensures that CLI tools built with flext-cli remain robust, maintainable, and easy to test through built-in smoke testing utilities and executable documentation.
Sources: README.md:9-11, examples/README.md:1-12
Core Development Patterns
Developers interacting with flext-cli are encouraged to use a standardized set of aliases and facades to maintain consistency across the codebase.
Public Facade Usage
The cli object from flext_cli acts as the primary entry point for common operations. This facade abstracts internal services for printing, file operations, and interactive prompts.
from flext_cli import cli
from examples import c
# Using the facade for styled output
cli.print("FLEXT CLI Initialized", style=c.Cli.MessageStyles.GREEN)
# Typed file reading
result = cli.read_json_file("settings.json")
Sources: examples/README.md:46-53, examples/ex_01_getting_started.py:19
Standard Aliases
To streamline imports and improve readability, the project uses a set of single-character aliases within the examples package:
c: Constantsm: Models (Pydantic)p: Protocols/Types (specificallyp.Result)r: Result helpers (Railway pattern)s: Service base classest: Typingsu: Utilities
Sources: examples/README.md:38-40, examples/ex_01_getting_started.py:18
Workflow Architecture
The following diagram illustrates the typical data flow when executing a CLI command using the flext-cli architecture.
This diagram shows the transition from raw user input through Pydantic validation to the execution of logic via the public facade, ending in a standardized result contract.
Sources: examples/README.md:15-32, examples/ex_01_getting_started.py:64-131
Implementation Basics
The Service Base (s)
The recommended way to implement logic is by inheriting from the s base class. This provides direct, typed access to settings and ensures the execute method returns a standardized p.Result.
class MyCommand(s):
def execute(self) -> p.Result[t.JsonMapping]:
# Implementation logic here
return r[t.JsonMapping].ok({"status": "complete"})
Sources: examples/README.md:57-64, examples/ex_01_getting_started.py:22
Railway Result Contract
flext-cli uses a railway-oriented programming model. Functions return a Result object that is either ok (success) or fail (failure). This allows for chaining operations using map and flat_map without explicit try-except blocks in the main logic flow.
| Method | Purpose | Source |
|---|---|---|
r[T].ok(value) | Wraps a successful value of type T. | examples/ex_01_getting_started.py:32 |
r[T].fail(error) | Wraps a failure message. | examples/ex_01_getting_started.py:84 |
.map(func) | Transforms the success value. | examples/ex_12_pydantic_driven_cli.py:59 |
.flat_map(func) | Chains another result-returning function. | examples/ex_01_getting_started.py:44 |
Feature Modules
File Operations
The cli facade provides typed wrappers for JSON and YAML operations, replacing standard open/read/write boilerplate with result-aware methods.
cli.write_json_file(path, data): Persists JSON data.cli.read_json_model(path, model): Reads JSON directly into a Pydantic model.cli.load_file_auto_dict(path): Automatically detects format (JSON/YAML) and returns a dictionary.
Sources: examples/ex_04_file_operations.py:28-98, examples/ex_01_getting_started.py:42-46
Pydantic-Driven CLI
Configuration and CLI parameters can be auto-generated from Pydantic models. The CliModelConverter handles the transformation of Pydantic fields into Click options.
This sequence shows how the converter acts as a bridge between raw CLI input and typed Pydantic models.
Sources: examples/ex_12_pydantic_driven_cli.py:1-40, examples/ex_01_getting_started.py:64-88
Conclusion
Getting started with flext-cli involves adopting the public facade and service patterns to build structured, validated commands. By leveraging the railway result contract and Pydantic-driven models, developers can create CLI tools that are naturally resilient to errors and easy to integrate into larger automation pipelines.
Sources: examples/README.md:73-81, examples/ex_11_complete_integration.py:87-105