--- adr_number: 21 title: CLI and Output Rendering status_history: - - '2026-02-16' - Proposed - Jeffrey Phillips Freeman - - '2026-02-16' - Accepted - Jeffrey Phillips Freeman tier: 4 authors: - Jeffrey Phillips Freeman superseded_by: null related_adrs: - number: 1 title: Layered Architecture relationship: The CLI resides in the Presentation Layer and calls into Application Layer facades - number: 5 title: Technical Stack relationship: Typer and Rich are the chosen CLI and rendering libraries - number: 24 title: Configuration System relationship: CLI flags participate in the five-tier configuration resolution chain acceptance: votes_for: - voter: Jeffrey Phillips Freeman comment: The noun-verb command pattern with six output formats covers both human and machine consumers well votes_against: [] abstentions: [] --- ## Context CleverAgents is a CLI-first application. The command-line interface is the primary entry point for all user interaction — creating actions, managing projects, executing plans, configuring the system, and reviewing results. The CLI must support a large number of entity types and operations, provide consistent command structure, and render output in multiple formats (human-readable terminal output, structured JSON/YAML for scripting, plain text for piping). ## Decision Drivers - The CLI is the primary entry point for all user interaction and must scale to many entity types and operations - Output must serve both human consumers (styled terminal) and machine consumers (JSON/YAML for scripting) - Command structure must be consistent and predictable across a large number of entity types - Entity definitions must be versionable and reviewable, favoring YAML-first registration over CLI-only creation - Log output and structured command output must be cleanly separated (stderr vs. stdout) ## Decision The CLI uses **Typer** (>= 0.9.0) with the `agents ` command pattern. Output rendering supports **six formats** (`rich`, `color`, `table`, `plain`, `json`, `yaml`) selectable via the `--format` flag or `core.format` configuration key. Rich (via Typer's built-in integration) provides styled terminal rendering with panels, tables, trees, syntax highlighting, progress spinners, and markdown. ## Design ### Command Structure All commands follow the `agents ` pattern: ``` agents plan create|use|execute|apply|show|list|correct|cancel agents action create|show|list|remove agents project create|link|unlink|show|list|remove|context agents actor add|show|list|remove agents tool add|show|list|remove agents skill add|show|list|remove agents validation add|attach|detach|show|list|remove agents resource add|show|list|remove agents resource-type add|show|list|remove agents invariant add|remove|list|show agents session new|list|show|resume|archive agents config set|get|list agents automation-profile add|show|list|remove ``` Typer's nested command group support maps directly to this pattern. Each noun is a Typer command group; each verb is a command within that group. ### Six Output Formats | Format | Description | Use Case | |--------|-------------|----------| | `rich` | Full Rich rendering: panels, tables, trees, syntax highlighting, spinners | Interactive terminal use (default) | | `color` | Colored text without Rich panels/tables | Simpler terminals | | `table` | Tabular output using Rich Table | Data comparison, tabular listings | | `plain` | Plain unformatted text | Piping to other tools, logs | | `json` | Structured JSON output | Scripting, API integration, `jq` processing | | `yaml` | Structured YAML output | Configuration review, human-readable structured data | The format is resolved per-invocation: `--format` CLI flag > `CLEVERAGENTS_FORMAT` env var > `core.format` config key > default (`rich`). ### Global CLI Flags | Flag | Description | |------|-------------| | `--format` | Output format (6 options) | | `--data-dir` | Override `core.data-dir` | | `--config-path` | Override `core.config-path` | | `-v` through `-vvvvv` | Verbosity (ERROR → WARN → INFO → DEBUG → TRACE) | ### Phase Transition Verbs The CLI verbs for plan lifecycle transitions are semantic — they describe the user's intent, not the internal phase name: | Verb | Meaning | |------|---------| | `create` | Create an action (template) | | `use` | Apply an action to a project → enters Strategize | | `execute` | Begin execution of the strategy → enters Execute | | `apply` | Commit sandbox changes to real resources → enters Apply | There is no `strategize` command — `use` implicitly transitions to the Strategize phase. ### Entity Configuration Pattern For entity registration commands (`agents actor add`, `agents tool add`, etc.), the CLI requires a `--config ` flag pointing to a YAML configuration file that fully defines the entity. CLI flags alongside `--config` serve as optional overrides for values in the YAML. This ensures that YAML is the complete, versionable entity definition. ### Rich Rendering Components The Rich library (transitive via Typer) provides: - **Panel**: Bordered information blocks for plan summaries, decision details. - **Table**: Structured tabular output for listings and comparisons. - **Tree**: Hierarchical display for decision trees, plan hierarchies, skill composition. - **Syntax**: Syntax-highlighted code display for diffs, file contents. - **Progress / Spinner**: Progress indication during long-running operations. - **Markdown**: Rendered markdown for documentation and descriptions. ### Future Presentation Surfaces The architecture supports additional presentation surfaces without modifying the Application Layer: - **Textual TUI**: Reactive terminal UI using the same Rich primitives. - **Textual Web**: TUI served as a web application. - **IDE Plugin**: Embedded TUI integration. - **A2A Server**: JSON-RPC 2.0 endpoint for server mode. All presentation surfaces consume the same Application Layer service facades. ## Constraints - All CLI commands must follow the `agents ` pattern. No top-level verbs without a noun group. - Every command that produces output must support all six output formats. The `--format` flag must be available on every output-producing command. - Entity registration commands must accept `--config ` as the primary definition mechanism. CLI-only entity creation (without a YAML file) is not supported for registered entities. - Structured formats (`json`, `yaml`) must produce machine-parseable output with no intermixed human-readable text, progress indicators, or log messages. - Log output from `-v` flags goes to stderr (or the configured `core.log.terminal-stream`), never to stdout, to avoid contaminating structured output. ## Consequences ### Positive - The `agents ` pattern provides a consistent, predictable command structure that scales to many entity types. - Six output formats support both interactive use and scripting/automation without separate APIs. - Typer's type inference from Python type hints reduces CLI boilerplate and ensures argument validation. - The YAML-first entity registration pattern makes entity definitions versionable and reviewable. ### Negative - Typer's abstraction occasionally limits fine-grained control over help text formatting and argument parsing. - Supporting six output formats for every command increases the implementation and testing surface. - The `agents ` pattern can produce long commands for complex operations. ### Risks - Adding new entity types or verbs could create command namespace conflicts if naming is not carefully managed. - Rich rendering assumes a modern terminal with Unicode and ANSI color support. Minimal terminals may produce garbled output. - The separation of log output (stderr) from command output (stdout) may confuse users who are not familiar with this pattern. ## Alternatives Considered **Click (without Typer)** — Typer is built on Click and provides automatic type inference, Rich integration, and more concise command definitions. Using Click directly would require more boilerplate for the same functionality. **`--json` flag instead of `--format`** — A boolean `--json` flag was considered but rejected in favor of the more general `--format` flag that supports six formats including `yaml`, `table`, and `plain`. ## Compliance - **Command structure tests**: Tests verify that all commands follow the `agents ` pattern and that help text is generated correctly. - **Format tests**: Each output-producing command is tested with all six format options to verify correct output structure. - **Structured output tests**: Tests verify that `json` and `yaml` outputs are valid, parseable, and contain no non-structured content. - **Stderr separation tests**: Tests verify that `-v` log output goes to stderr and does not appear in stdout when `--format json` is used. - **BDD scenarios**: Behave features exercise CLI workflows end-to-end with various format options.