Command Line Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Command Line Interface (CLI) for flext-infra serves as the primary entry point for build automation, code generation, and workspace management. It is designed as a modular system that routes user commands to specific infrastructure services, such as documentation generation, dependency management, and automated refactoring. The CLI is registered under the entry point flext-infra and supports complex sub-command structures categorized by functional groups.
Sources: pyproject.toml:92, src/flext_infra/_constants/cli_routes.py:93-100, README.md:9-11
CLI Architecture and Command Routing
The CLI utilizes a structured routing mechanism where commands are grouped into functional categories. Each route maps a command name to a Pydantic-backed model class and a specific handler function. This ensures that input parameters are strictly validated before execution.
Command Execution Flow
When a user executes a command, the system identifies the appropriate group and sub-command, validates the input using the assigned model, and dispatches the request to the relevant orchestrator or service.
The diagram shows the sequence from raw user input to the final execution of infrastructure logic via validated handlers.
Sources: src/flext_infra/_constants/cli_routes.py:100-110, src/flext_infra/_models/docs.py:20-30
Primary Command Groups
The CLI is organized into several high-level groups, each managing a specific domain of the infrastructure.
| Group | Purpose | Key Commands |
|---|---|---|
basemk | Makefile automation | generate |
check | Quality gates | run, fix-pyrefly-settings |
codegen | Code generation | init, scaffold, census, pipeline |
deps | Dependency management | detect, modernize, path-sync |
docs | Documentation services | audit, fix, generate, validate |
refactor | Automated code changes | migrate-mro, modernize-patterns, census |
workspace | Workspace orchestration | sync, orchestrate, detect |
Sources: src/flext_infra/_constants/cli_routes.py:93-350, src/flext_infra/_constants/make.py:27-40
Sub-System Details
Documentation Management (docs)
The docs group manages the lifecycle of project documentation. It includes tools for auditing broken links, fixing formatting issues, and generating API reference pages directly from code docstrings and package exports.
This diagram illustrates the flow of generating documentation artifacts based on the project's public API contract.
Sources: src/flext_infra/_utilities/docs_generate.py:53-100, src/flext_infra/_utilities/docs_api.py:165-180
Refactoring and Census (refactor)
The refactor module provides powerful tools for workspace-wide code analysis and modification. The census command identifies architectural violations, such as unused functions or missing runtime aliases, and can optionally apply automated fixes.
- Rules: Includes
runtime_alias,manual_typing_alias,mro_completeness, andunused. - Safety: Supports
dry_runmodes and generates impact maps to preview changes before they are applied to the disk.
Sources: tests/unit/refactor/test_main_cli.py:175-190, src/flext_infra/_constants/cli_routes.py:348-400
Dependency and Workspace Sync
The CLI handles the synchronization of internal FLEXT dependencies and external paths. The path-sync command is specifically used to rewrite dependency paths within pyproject.toml files to ensure workspace consistency.
Sources: src/flext_infra/_constants/cli_routes.py:180-200, tests/utilities.py:910-930
Configuration and Make Integration
The CLI is tightly integrated with a Makefile contract. Many CLI commands can be triggered via make verbs, with the CLI providing the underlying implementation for these tasks.
Make Verb Forwarding
Parameters passed to make are often forwarded directly to CLI models.
| Make Variable | CLI Parameter Mapping | Description |
|---|---|---|
CHECK_GATES | gates | Selects specific linting/quality gates |
DOCS_PHASE | phase | Specifies doc stage (audit, build, etc.) |
FIX | apply | Enables auto-fix/write mode |
PROJECTS | projects | Filters execution to specific workspace projects |
Sources: src/flext_infra/_constants/make.py:100-140, src/flext_infra/_constants/make.py:230-250
Conclusion
The flext-infra Command Line Interface acts as the central nervous system for the workspace, providing a unified and validated interface for complex infrastructure tasks. By leveraging Pydantic models for command routing and providing tight integration with standard development workflows (Make, GitHub Actions), it ensures that workspace management remains deterministic and scalable.