Logical Architecture

The FRAME CLI architecture is based on a strict separation between argument definition at the interface layer and low-level command execution logic.

Core Structure

The main anchor point for the binary lives in the central orchestrator:

cli/frame.ts: Acts as the master router. It captures terminal input, parses options, and delegates execution to the matching command.
utils/load-env.ts: Loads local configuration and secrets without mutating the filesystem when imported by application tooling.
cli/scripts/secrets/run.ts: Creates .env.local from .env.example when needed, fetches remote secrets in memory, and launches a child command with a merged, process-scoped environment.

Command Flow

The lifecycle of a command—from the moment the user presses Enter until resolution—is predictable:

graph TD
    A[frame <command>] --> B{Argument Parsing}
    B --> C(Local Environment Loading)

    C --> D{Secret Provider}
    D -->|configured| E[Fetch Secrets In Memory]
    D -->|not configured| F[Pass Through]

    E --> G[Child Process Environment]
    F --> G
    G --> H[Command]

    style A fill:#000000,stroke:#333,stroke-width:2px,color:#fff

Process and Native Dependencies

Unlike most FRAME packages, @frame/cli launches child processes and integrates with native secret-provider SDKs. Developers may keep local secrets in .env.local; secrets fetched from a provider remain in memory and are never written back to environment files.

Creating Commands

To extend the monorepo’s operational capabilities by adding a new CLI command:

Define the Parser: Create the argument definition logic (for example, options such as --force or --path).
Create the Runner: Implement the business function (e.g. runMyCommand(options)). Keep this function pure so it can be evaluated and tested without calling process.exit().
Style the Output: Use the @frame/cli/utils/prompts facade (intro, spinner, outro) to communicate action progress to the engineer in real time.