cleveragents-core/docs/reference/plan_cli.md

Plan CLI Reference

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

Plan Use

agents plan use <ACTION> [PROJECT ...] [OPTIONS]

Create a plan from an action template. The first positional argument is the action name (namespaced, e.g. local/code-coverage). All subsequent positional arguments are project names the plan will operate on. Projects can also be supplied via the repeatable --project / -p option.

Options

Flag	Short	Description
--project	-p	Project name (repeatable)
--arg	-a	Argument value name=value (repeatable)
--automation-profile		Automation profile name for this plan
--invariant		Invariant constraint text (repeatable)
--strategy-actor		Override the strategy actor
--execution-actor		Override the execution actor
--estimation-actor		Override the estimation actor
--invariant-actor		Override the invariant reconciliation actor
--automation-level		manual, review_before_apply, or full_automation

Examples

# Single project via positional arg
agents plan use local/code-coverage my-project --arg target_coverage=80

# Multiple projects via positional args
agents plan use local/lint proj-a proj-b

# Projects via --project option
agents plan use local/lint --project proj-a --project proj-b

# With invariants and actor overrides
agents plan use local/refactor proj-1 \
  --invariant "No new warnings" \
  --invariant "Keep backward compat" \
  --strategy-actor openai/gpt-4 \
  --execution-actor anthropic/claude-3

# With automation profile
agents plan use local/code-coverage proj-1 --automation-profile trusted

Plan List (lifecycle-list)

agents plan lifecycle-list [REGEX] [OPTIONS]

Options

Flag	Short	Description
--phase		Filter by phase (strategize, execute, apply, applied)
--state		Filter by processing state (queued, processing, errored, complete, cancelled)
--processing-state		Alias for --state
--project	-p	Filter by project name
--action		Filter by action name

Positional Arguments

Argument	Description
REGEX	Optional regex pattern to filter names

Examples

# List all plans
agents plan lifecycle-list

# Filter by phase
agents plan lifecycle-list --phase strategize

# Filter by processing state
agents plan lifecycle-list --state complete

# Combine filters
agents plan lifecycle-list --phase execute --project my-project --action local/lint

Output Columns

Column	Description
ID	Truncated plan ULID
Name	Full namespaced plan name
Action	Source action name
Phase	Current lifecycle phase
State	Processing state
Projects	Linked project names
Created	Creation timestamp

Plan Status

agents plan status [PLAN_ID]

Without a plan ID, shows a summary table of all active plans. With a plan ID, shows full details including:

• Action: source action name
• Phase and Processing State
• Project links with aliases and read-only flags
• Arguments (ordered)
• Automation profile with provenance tag
• Actor overrides (strategy, execution, estimation, invariant)
• Timestamps (created, updated, phase start/complete times)

Plan Cancel

agents plan cancel <PLAN_ID> [OPTIONS]

Options

Flag	Short	Description
--reason	-r	Reason for cancellation

Example

agents plan cancel 01HXYZ... --reason "Requirements changed"

Source Location

• CLI commands: src/cleveragents/cli/commands/plan.py
• Lifecycle service: src/cleveragents/application/services/plan_lifecycle_service.py
• Plan model: src/cleveragents/domain/models/core/plan.py