cleveragents-core/docs/reference/plan_cli.md

Plan CLI Reference

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

Note: The legacy commands (tell, build, apply, new, current, list, cd, continue) are deprecated and emit deprecation warnings. Use the v3 lifecycle commands below instead.

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
--format	-f	Output format: json, yaml, plain, table, rich (default: rich)

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

# JSON output
agents plan use local/lint proj-a --format json

# YAML output
agents plan use local/lint proj-a --format yaml

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
--format	-f	Output format: json, yaml, plain, table, rich (default: rich)

Examples

# List all plans
agents plan lifecycle-list

# JSON output
agents plan lifecycle-list --format json

# YAML output
agents plan lifecycle-list --format yaml

# Filter by phase + JSON output
agents plan lifecycle-list --phase strategize --format json

JSON/YAML Output Keys

Key	Description
plan_id	Unique ULID identifier
namespaced_name	Full namespaced plan name
phase	Current lifecycle phase
processing_state	Processing state
project_links	List of linked projects
arguments	Resolved argument values
automation_profile	Automation profile name (or null)
action_name	Source action name

Plan Status

agents plan status [PLAN_ID] [OPTIONS]

Options

Flag	Short	Description
--format	-f	Output format (default: rich)

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

Examples

# Rich panel (default)
agents plan status 01HXYZ...

# JSON output
agents plan status 01HXYZ... --format json

# Plain text output
agents plan status 01HXYZ... --format plain

Plan Execute

agents plan execute [PLAN_ID] [OPTIONS]

Options

Flag	Short	Description
--format	-f	Output format (default: rich)

Plan Lifecycle-Apply

agents plan lifecycle-apply [PLAN_ID] [OPTIONS]

Options

Flag	Short	Description
--format	-f	Output format (default: rich)

Plan Cancel

agents plan cancel <PLAN_ID> [OPTIONS]

Options

Flag	Short	Description
--reason	-r	Reason for cancellation
--format	-f	Output format (default: rich)

Example

agents plan cancel 01HXYZ... --reason "Requirements changed"
agents plan cancel 01HXYZ... --reason "Changed" --format json

Deprecated Legacy Commands

The following commands are deprecated and will be removed in a future release. They emit deprecation warnings at runtime.

Legacy Command	Replacement
plan tell	plan use <action> [project]
plan build	plan execute [plan_id]
plan apply	plan lifecycle-apply [plan_id]
plan new	plan use <action> [project]
plan current	plan status [plan_id]
plan list	plan lifecycle-list
plan cd	plan status <plan_id>
plan continue	plan use <action> [project]

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
• Formatting helpers: src/cleveragents/cli/formatting.py