cleveragents-core/docs/reference/plan_cli.md

Plan CLI Reference

The agents plan command group manages plans in the CleverAgents v3 plan lifecycle.

Note (v3.8.0+): Mixing legacy plan commands with v3 plan workflows in the same session is no longer permitted. If you attempt to use legacy plan commands alongside v3 plan commands, the CLI will detect the conflict and surface a clear error message with migration guidance. Migrate fully to the v3 plan workflow before using agents plan.

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 01HXYZ1234567890ABCDEFXYZX

# JSON with full context
agents plan explain 01HXYZ1234567890ABCDEFXYZX --format json --show-context

# Show reasoning
agents plan explain 01HXYZ1234567890ABCDEFXYZX --show-reasoning

# YAML output with all details
agents plan explain 01HXYZ1234567890ABCDEFXYZX --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)

Full ULID Display

As of v3.2.0 (PR #6571), agents plan tree displays full 26-character ULIDs for all decision IDs instead of truncated 8-character prefixes. This means every ID shown in the tree output can be used directly in follow-up commands such as agents plan explain and agents plan correct without needing to look up the full ID elsewhere.

The output includes a "Decision IDs (for correction)" section that lists all decision ULIDs with human-readable labels derived from the decision type, making it easy to identify which ID to pass to correction commands.

Decision IDs (for correction)
  01HXYZ1234567890ABCDEFXYZX  strategize: initial strategy
  01HXYZ1234567890ABCDEFXYZY  execute: write src/foo.py
  01HXYZ1234567890ABCDEFXYZZ  execute: write tests/test_foo.py

Examples

# Default rich tree view (full ULIDs displayed)
agents plan tree 01HXYZ1234567890ABCDEFXYZW

# Table format
agents plan tree 01HXYZ1234567890ABCDEFXYZW --format table

# Include superseded decisions
agents plan tree 01HXYZ1234567890ABCDEFXYZW --show-superseded

# Limit depth to 2 levels
agents plan tree 01HXYZ1234567890ABCDEFXYZW --depth 2

# JSON output for scripting
agents plan tree 01HXYZ1234567890ABCDEFXYZW --format json

# Use a decision ID from tree output directly in explain
agents plan explain 01HXYZ1234567890ABCDEFXYZY

# Correct a decision using a tree ULID directly
agents plan correct 01HXYZ1234567890ABCDEFXYZZ --mode revert