FLEXT CLI System

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/lib/cli.py
• src/flext/docs.py
• pyproject.toml
• AGENTS.md
• README.md
• scripts/maintenance/README.md

The FLEXT CLI System provides a unified orchestration layer for the FLEXT workspace, facilitating data integration, platform tooling, and operational connectors. It acts as the primary interface for developers and automated agents to interact with the repository's governed packages and maintenance tasks.

The system is built on a "pyproject-first" philosophy, where package metadata and scripts are managed through standardized configurations. It encompasses various command-line entry points, including flext-dev, flext-docs, and flext-workspace, which are mapped to specific implementation modules within the src/flext directory.
Sources: README.md:1-5, pyproject.toml:98-102, src/flext/docs.py:1-20

CLI Architecture and Orchestration

The CLI architecture relies on a central dispatcher located in scripts/lib/cli.py. This dispatcher handles argument parsing, environment variable promotion, and command routing. It facilitates the execution of "promoted Make verbs," which bridge the gap between high-level CLI commands and underlying build/maintenance tasks.

Command Execution Flow

The CommandCli class manages the lifecycle of a CLI call, from initial argument ingestion to final dispatch.

The execution flow ensures that KEY=value arguments are promoted to the process environment, allowing dynamic configuration during runtime.
Sources: scripts/lib/cli.py:19-75

Key Components

Component	Description	Source
CommandCli	Main orchestrator for parsing, rendering help, and routing commands.	scripts/lib/cli.py
CommandRegistry	Handles discovery and resolution of available commands and verbs.	scripts/lib/cli.py
CommandExecution	Responsible for the actual execution of the resolved commands.	scripts/lib/cli.py
CommandRenderer	Generates text representations for help and dry-run outputs.	scripts/lib/cli.py

Defined Entry Points

FLEXT defines several primary scripts in the project configuration that serve as the main interaction points for users.

• flext-dev: Mapped to flext.dev:main, intended for development-related operations.
• flext-docs: Mapped to flext.docs:main, serving as the workspace documentation entry point.
• flext-workspace: Mapped to flext.workspace:main, for general workspace management.

Sources: pyproject.toml:98-102, src/flext/docs.py:13-20

Documentation CLI (flext-docs)

The documentation CLI is implemented in src/flext/docs.py and utilizes a FlextRootDocs class. It leverages the flext_cli package to execute commands, focusing on generating, auditing, and validating Markdown documentation across the workspace.
Sources: src/flext/docs.py:13-27, scripts/maintenance/README.md:11-15

Command Dispatching Logic

The system uses a sophisticated dispatching logic that supports comma-separated "WHAT" values, allowing multiple targets to be processed in a single command.

    @staticmethod
    def normalize_what(raw: str) -> tuple[str, ...]:
        """Normalize comma-separated WHAT values."""
        items: list[str] = []
        for raw_item in raw.split(","):
            item = raw_item.strip()
            if not item:
                continue
            if "/" in item:
                item = item.rsplit("/", 1)[-1].strip()
            if item:
                items.append(item)
        if not items:
            return (c.Tests.MAKE_DEFAULT_COMMAND,)
        return tuple(dict.fromkeys(items))

Sources: scripts/lib/cli.py:138-155

Dry-Run Safety

For commands that mutate state, the CLI implements a dry-run check. If the MAKE_APPLY_PARAM environment variable is not explicitly set (e.g., to "Y"), the system renders a dry-run message instead of executing the underlying logic.
Sources: scripts/lib/cli.py:118-130

Canonical Governance and Make Verbs

The CLI system is strictly governed by the engineering laws defined in AGENTS.md. A key rule (Rule 17) dictates that all build, check, and test actions must run through canonical Make verbs or the documented CLI.

Common CLI/Make Commands

Users interact with the system using make <verb> WHAT=<x> syntax, which is internally routed through the CLI scripts.

Command	Purpose
make boot	Bootstrap the environment.
make check	Run quality gates (lint, format, mypy, etc.).
make test	Execute unit or integration tests.
make docs	Run documentation pipeline (generate, audit, validate).
make ship	Handle release operations (tag, push, PR).

Sources: AGENTS.md:273-281, scripts/maintenance/README.md:17-27

Maintenance Workflow

Documentation maintenance follows a specific lifecycle managed by the CLI:

1. Generate: Create API reference and documentation from code.
2. Fix: Apply automatic corrections where supported.
3. Audit: Lint Markdown documents.
4. Validate: Ensure compliance with documentation policies.

Sources: scripts/maintenance/README.md:1-15

Summary

The FLEXT CLI System is a robust orchestration layer that centralizes project management tasks. By enforcing a "Canonical Command Surface," it ensures that all workspace operations—from documentation generation to quality gate enforcement—are performed consistently and safely. The system's integration with the repository's governance laws ensures that both human developers and AI agents operate within validated boundaries.