cleveragents-core/docs/reference/plan_cli.md

Plan CLI Reference

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

!!! warning "Legacy/v3 Plan Workflow Mixing" agents plan commands detect and reject attempts to mix legacy plan commands with v3 plan workflows in the same session. If you attempt to use a legacy plan command alongside v3 commands, the CLI surfaces a clear error message with migration guidance. Migrate all plan workflows to v3 before mixing commands in a single session. (#1577)

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 correct	Correct a decision with new guidance
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
--namespace, -n	Filter by plan namespace
--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

Examples

# Filter by namespace
agents plan list --namespace myteam

# Short form
agents plan list -n myteam

# Combined namespace + state filter
agents plan list --namespace myteam --state processing

# Namespace filter with no results
agents plan list --namespace nonexistent

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 (--namespace, --phase, --state, --project, --action) is active. Lists the active filter values.
• Summary panel — total plans, processing count, completed count, and errored count.

Examples

# Filter by namespace
agents plan list --namespace myteam

# Combine namespace and phase filters
agents plan list --namespace myteam --phase execute

# JSON output with namespace filter
agents plan list -n myteam --format json

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

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

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

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

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

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

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

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

agents plan correct

Correct a recorded decision by providing updated guidance.

Synopsis

agents plan correct <DECISION_ID> --mode <MODE> [OPTIONS]

<MODE> must be either revert (re-run from the corrected decision) or append (add guidance without replaying the tree).

Options

Flag	Description
--mode MODE	Correction mode: revert recomputes from the decision; append records guidance only
--guidance, -g	Guidance text describing the corrected decision
--dry-run	Preview the correction impact without applying it
--yes, -y	Skip confirmation prompts when replaying corrections
--format, -f	Output format: json, yaml, plain, table, rich

Examples

# Revert decision with updated guidance
agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW9 --mode revert \
  --guidance "Prioritize incident triage before refactors"

# Append guidance without recomputing immediately
agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW9 --mode append \
  --guidance "Include database observability checks" --dry-run