cleveragents-core/docs/reference/plan_cli.md

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 lifecycle-list	List plans with optional filters
agents plan status	Show plan status / details
agents plan execute	Transition to Execute phase
agents plan lifecycle-apply	Transition to Apply phase
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 lifecycle-list

List v3 lifecycle plans with optional filtering.

Synopsis

agents plan lifecycle-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

Output Fields

Includes Profile and Invariants columns in all output formats when present on the plan.

agents plan execute

Transition a plan from Strategize to Execute phase.

agents plan execute [PLAN_ID] [--format FORMAT]

agents plan lifecycle-apply

Transition a plan from Execute to Apply phase.

agents plan lifecycle-apply [PLAN_ID] [--format FORMAT]

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