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
--no-estimate	Skip estimation even if estimation actor is configured
--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

# Skip cost estimation
agents plan use local/refactor my-project --no-estimate

# 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

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