Configuration & Settings Management
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration & Settings Management system in flext-cli provides a centralized, type-safe infrastructure for managing application behavior, environment variables, and user preferences. It leverages Pydantic for validation and provides a singleton-based global state for consistent access across the CLI lifecycle.
Sources: README.md:20-22, tests/unit/test_settings.py:38-42, examples/ex_06_settings.py:11-20
Architecture Overview
The system is built around the FlextCliSettings class, which serves as the Single Source of Truth (SSOT). It manages settings through three primary mechanisms: a namespaced Cli configuration, global flags (like debug), and environment variable overrides.
Component Relationship
The following diagram illustrates the relationship between the public cli facade, the settings singleton, and the underlying configuration models.
The cli facade exposes cli.settings as a direct namespaced access point to the global settings instance.
Sources: tests/unit/test_settings.py:53-61, examples/ex_06_settings.py:37-45, src/flext_cli/settings.py
Core Settings Components
Global Settings (FlextCliSettings)
The top-level settings object includes cross-cutting concerns and the nested Cli namespace. It supports serialization/deserialization via Pydantic's model_dump and model_validate.
| Field | Type | Description |
|---|---|---|
debug | bool | Enables global debug mode. |
Cli | CliSettings | Nested namespace for CLI-specific behavior. |
Sources: tests/unit/test_settings.py:27-36, tests/unit/test_settings.py:82-87
CLI Namespace (CliSettings)
This section manages specific CLI interaction parameters, such as logging, output formats, and application identity.
| Option | Type | Default | Source |
|---|---|---|---|
app_name | str | "flext-cli" | examples/ex_06_settings.py:48 |
cli_log_level | str | "INFO" | examples/ex_06_settings.py:44 |
output_format | str | "table" | examples/ex_01_getting_started.py:55 |
verbose | bool | False | tests/unit/test_settings.py:35 |
quiet | bool | False | tests/unit/test_settings.py:87 |
Sources: src/flext_cli/_constants/settings.py, examples/ex_06_settings.py:40-50
Settings Lifecycle and Data Flow
Settings are initialized via cli.new_settings() and can be retrieved as a singleton using fetch_global(). The system supports environment-specific overrides (e.g., Development vs. Production) and profile-based cloning.
Initialization and Override Flow
Settings can be dynamically updated for testing or specific execution profiles using the .clone() method, which allows overriding specific fields while preserving the rest of the configuration.
Sources: examples/ex_06_settings.py:65-85, tests/unit/test_settings.py:44-48, pyproject.toml:150-151
Settings Management Operations
The CLI provides utility methods to audit and validate the settings environment.
Snapshot and Validation
- Settings Snapshot: Captured via
cli.settings_snapshot(), providing a metadata summary of the settings directory, its existence, and its read/write status. - Structure Validation: Performed via
u.Cli.validate_settings_structure(), checking for the existence of the canonical settings directory and required standard subdirectories.
Sources: tests/unit/test_cmd.py:53-67, tests/unit/test_cmd.py:101-115
Location Management
Settings are typically stored in the user's home directory within a hidden folder.
| Resource | Path Detail |
|---|---|
| Home Directory | Determined by Path.home() |
| Settings Directory | ~/.flext (via c.Cli.PATH_FLEXT_DIR_NAME) |
| Token File | Configurable via Cli.token_file |
Sources: examples/ex_06_settings.py:53-60, tests/unit/test_cmd.py:58-62
Profile-Based Configuration
Applications using flext-cli can implement profile-specific logic (e.g., Development, Testing, Production) by matching against deployment environments.
match profile_name:
case c.DeploymentEnvironment.PRODUCTION:
debug = False
output_format = c.Cli.OutputFormats.JSON
case c.DeploymentEnvironment.TESTING:
debug = True
output_format = c.Cli.OutputFormats.TABLE
Sources: examples/ex_06_settings.py:72-80, tests/unit/test_settings.py:73-76
The Configuration & Settings Management system ensures that flext-cli remains highly configurable yet type-safe, providing developers with clear patterns for managing both internal CLI state and external application settings.