freemo
0382b2f722
- CHANGELOG: add Fixed entries for PRs #1574, #1570, #1569, #1547, #1548, #1522, #1524, #1525, #1520, #1553 covering rich output panels for session, actor, and plan commands, plus version commit SHA and provider fix - docs/reference/session_cli.md: document new rich output panels for session create (Settings, Actor Details), session list (Name column, Summary panel), session show (Automation field), session delete (Deletion Summary, Cleanup panels); update export to document --format md - docs/reference/actor_cli.md: document new rich output panels for actor remove (Actor Removed, Impact, Cleanup) and actor list (Summary panel) - docs/reference/plan_cli.md: document new rich output for plan list (Elapsed column, Filters panel, Summary panel) - docs/reference/cli_system_commands.md: document commit SHA resolution order (CLEVERAGENTS_COMMIT env var → git rev-parse → 'unknown') ISSUES CLOSED: #1574 #1570 #1569 #1547 #1548 #1522 #1524 #1525 #1520 #1553
9.6 KiB
Plan CLI Reference
The agents plan command group manages plans in the CleverAgents v3 plan lifecycle.
Commands
| Command | Description |
|---|---|
agents plan use |
Create plan from action + project(s) |
agents plan list |
List plans with optional filters |
agents plan status |
Show plan status / details |
agents plan execute |
Run Strategize + Execute (auto-apply if profile permits) |
agents plan apply |
Transition to Apply and complete it |
agents plan cancel |
Cancel a non-terminal plan |
agents plan diff |
Show ChangeSet as unified diff |
agents plan artifacts |
Show ChangeSet ID, sandbox refs, summary |
agents plan explain |
Explain a single decision |
agents plan tree |
Display decision tree for a plan |
agents plan use
Create a plan from an action template and one or more projects.
Synopsis
agents plan use <ACTION_NAME> [PROJECTS...] [OPTIONS]
Options
| Flag | Description |
|---|---|
--project, -p |
Project name (repeatable for multiple projects) |
--arg, -a |
Argument value in name=value format (repeatable) |
--automation-profile |
Automation profile name (e.g., trusted, manual) |
--invariant |
Invariant constraint text (repeatable) |
--strategy-actor |
Override strategy actor (namespace/name format) |
--execution-actor |
Override execution actor (namespace/name format) |
--estimation-actor |
Override estimation actor (namespace/name format) |
--invariant-actor |
Override invariant reconciliation actor |
--format, -f |
Output format: json, yaml, plain, table, rich |
Actor Override Validation
All actor override flags require namespaced format: namespace/name
(e.g., openai/gpt-4, anthropic/claude-3). Invalid formats are
rejected with a descriptive error.
Examples
# Basic usage with one project
agents plan use local/code-coverage my-project --arg target_coverage=80
# Multiple projects
agents plan use local/lint proj-1 proj-2
# With automation profile and invariants
agents plan use local/refactor my-project \
--automation-profile trusted \
--invariant "No new warnings" \
--invariant "Maintain backward compatibility"
# With actor overrides
agents plan use local/code-coverage my-project \
--strategy-actor openai/gpt-4 \
--execution-actor anthropic/claude-3 \
--estimation-actor openai/gpt-4
# JSON output
agents plan use local/lint my-project --format json
agents plan status
Show status of one or all v3 lifecycle plans.
Synopsis
agents plan status [PLAN_ID] [--format FORMAT]
When called without a plan ID, displays a summary table of all active plans including automation profile and invariant count columns.
Output Fields
- ID: Truncated plan ULID
- Name: Namespaced plan name
- Phase: Current lifecycle phase
- State: Processing state
- Profile: Automation profile name (if set)
- Invariants: Count of attached invariants
- Terminal: Whether the plan is in a terminal state
agents plan list
List v3 lifecycle plans with optional filtering.
Synopsis
agents plan list [REGEX] [OPTIONS]
Options
| Flag | Description |
|---|---|
--phase |
Filter by phase (strategize, execute, apply) |
--state |
Filter by processing state |
--processing-state |
Alias for --state |
--project, -p |
Filter by project name |
--action |
Filter by action name |
--format, -f |
Output format |
Rich Output
The rich format renders a Plans table with columns:
| Column | Description |
|---|---|
| ID | Truncated plan ULID (8 chars) |
| Phase | Current lifecycle phase |
| State | Processing state |
| Action | Action name |
| Project | First linked project name (or (none)) |
| Elapsed | Wall-clock time since plan creation (HH:MM:SS) |
After the table:
- Filters panel — shown only when at least one filter (
--phase,--state,--project,--action) is active. Lists the active filter values. - Summary panel — total plans, processing count, completed count, and errored count.
Followed by a ✓ OK N plan(s) listed success message.
agents plan execute
Run the current plan phase synchronously. Detects the plan's current phase and processes it inline:
- Strategize/queued — runs the strategize phase to completion, then auto-progresses to Execute if the automation profile permits.
- Strategize/complete — transitions to Execute and runs it.
- Execute/queued — runs the execute phase to completion.
When the automation profile's auto_apply threshold is met (< 1.0),
the execute command also drives the plan through the Apply phase to
the terminal applied state. This means plan execute with a
ci or full-auto profile completes the full lifecycle in a single
invocation: Strategize → Execute → Apply.
When no plan ID is given, auto-selects the single eligible plan.
agents plan execute [PLAN_ID] [--format FORMAT]
Internal Wiring
The CLI handler shares a single PlanLifecycleService instance between
the command logic and the PlanExecutor to avoid stale in-memory cache
reads after phase transitions. See
CLI Executor Wiring
for details.
agents plan apply
Transition a plan to Apply phase and complete it. Because Apply is a
destructive operation (it merges sandbox changesets into real project
resources), a confirmation prompt is displayed by default. Pass
--yes / -y to skip the prompt in scripts or CI pipelines.
When the plan is in Execute/complete, transitions to Apply. When the
plan is in Apply/queued (e.g. auto-progressed by plan execute),
completes the apply processing, driving the plan to the terminal
applied state. Apply is a metadata transition (no LLM call).
Synopsis
agents plan apply [--yes|-y] [PLAN_ID] [--format FORMAT]
Options
| Flag | Description |
|---|---|
--yes, -y |
Skip the confirmation prompt and apply immediately |
--format, -f |
Output format: json, yaml, plain, table, rich |
Arguments
| Argument | Description |
|---|---|
PLAN_ID |
Plan ID to apply (optional; auto-selects if only one eligible) |
agents plan cancel
Cancel a non-terminal plan.
agents plan cancel PLAN_ID [--reason REASON] [--format FORMAT]
agents plan diff
Show ChangeSet as unified diff for a plan.
agents plan diff PLAN_ID [--correction ID] [--format FORMAT]
agents plan artifacts
Show plan artifacts including ChangeSet ID and sandbox references.
agents plan artifacts PLAN_ID [--format FORMAT]
agents plan explain
Explain a single decision in the plan decision tree.
Synopsis
agents plan explain <DECISION_ID> [OPTIONS]
Options
| Flag | Description |
|---|---|
--format, -f |
Output format: json, yaml, plain, table, rich |
--show-context |
Include context snapshot details |
--show-reasoning |
Include rationale and actor reasoning |
Alternatives considered are always included in the output.
Examples
# Default rich output
agents plan explain 01HXYZ1234567890ABCDEFGH
# JSON with full context
agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context
# Show reasoning
agents plan explain 01HXYZ1234567890ABCDEFGH --show-reasoning
# YAML output with all details
agents plan explain 01HXYZ1234567890ABCDEFGH --format yaml \
--show-context --show-reasoning
agents plan tree
Display the decision tree for a plan.
Synopsis
agents plan tree <PLAN_ID> [OPTIONS]
Options
| Flag | Description |
|---|---|
--format, -f |
Output format: json, yaml, plain, table, rich |
--show-superseded |
Include superseded decisions in the tree |
--depth |
Maximum tree depth (0 = unlimited, default: 0) |
Examples
# Default rich tree view
agents plan tree 01HXYZ1234567890ABCDEFGH
# Table format
agents plan tree 01HXYZ1234567890ABCDEFGH --format table
# Include superseded decisions
agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded
# Limit depth to 2 levels
agents plan tree 01HXYZ1234567890ABCDEFGH --depth 2
# JSON output for scripting
agents plan tree 01HXYZ1234567890ABCDEFGH --format json