cleveragents-core/docs/cli.md

CLI Reference — v3.2.0 and v3.3.0 Features

This page provides a consolidated reference for the CLI commands introduced in the v3.2.0 (Decisions + Validations + Invariants) and v3.3.0 (Corrections + Subplans + Checkpoints) milestones.

For the full plan command reference see reference/plan_cli.md. For invariant management see reference/invariants.md. For checkpoint and rollback details see reference/checkpointing.md.

---

Decision Tree Commands (v3.2.0)

agents plan tree

Renders the decision tree for a plan as a visual hierarchy.

agents plan tree <PLAN_ID> [OPTIONS]

Option	Description
--format, -f	Output format: json, yaml, plain, table, rich (default: rich)
--show-superseded	Include superseded (corrected) decisions in the tree
--depth	Maximum tree depth to render (0 = unlimited, default: 0)

Examples:

# Render the full decision tree in rich format
agents plan tree 01HXYZ1234567890ABCDEFGH

# Include superseded decisions (useful for auditing corrections)
agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded

# Limit depth for large plans
agents plan tree 01HXYZ1234567890ABCDEFGH --depth 3

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

Note: Decision IDs displayed in the tree are full 26-character ULIDs (v3.8.0+), which can be copied directly and used in plan explain or plan correct commands.

See also: reference/plan_cli.md#agents-plan-tree

---

agents plan explain

Shows detailed information about a single decision node, including the question posed, the chosen option, alternatives considered, and optional context/reasoning.

agents plan explain <DECISION_ID> [OPTIONS]

Option	Description
--format, -f	Output format: json, yaml, plain, table, rich
--show-context	Include the context snapshot captured at decision time
--show-reasoning	Include the actor's raw LLM reasoning trace

Examples:

# Default rich output
agents plan explain 01HXYZ1234567890ABCDEFGH

# Full detail with context and reasoning
agents plan explain 01HXYZ1234567890ABCDEFGH --show-context --show-reasoning

# JSON for programmatic use
agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context

See also: reference/plan_cli.md#agents-plan-explain

---

Decision Correction Commands (v3.3.0)

agents plan correct

Re-executes a plan from a specific decision point using one of two correction modes.

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

Option	Description
--mode	Correction mode: revert or append (required)
--guidance	Operator guidance text for append mode (required for append)
--dry-run	Preview the impact without making changes
--yes, -y	Skip the confirmation prompt
--format, -f	Output format: json, yaml, plain, table, rich

--mode=revert

Invalidates the targeted decision and all its descendants (BFS traversal), then re-executes the plan from that decision point. Associated artifacts are archived and affected child plans are rolled back.

# Revert a decision and re-execute from that point
agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH

# Preview impact without making changes
agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH --dry-run

# Skip confirmation prompt
agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH --yes

What happens:

          D1 (target) <-- revert starts here
                |
           +----+----+
           D2        D3     <- all invalidated
                     |
                     D4     <- also invalidated

--mode=append

Preserves the original decision and spawns a new child plan rooted at the target node. The child plan carries the operator's guidance and produces additional decisions without disturbing the existing tree.

# Append a correction with guidance
agents plan correct --mode=append 01HXYZ1234567890ABCDEFGH \
  --guidance "Use a safer migration strategy that avoids table locks"

# Append with dry-run to preview
agents plan correct --mode=append 01HXYZ1234567890ABCDEFGH \
  --guidance "Prefer read-only operations where possible" \
  --dry-run

What happens:

          D1 (target)
               |
        +------+----------+
        D2 (original)  CP-new   <- child plan appended

Risk levels (based on affected decision count):

Affected Decisions	Risk Level
<= 3	low
4 - 10	medium
> 10	high

See also: reference/decision_correction.md

---

Invariant Management Commands (v3.2.0)

Invariants are natural-language constraints that govern plan execution. They are evaluated by the Invariant Reconciliation Actor at the start of the Strategize phase.

agents invariant add

Creates a new invariant constraint.

agents invariant add <NAME> --description <TEXT> [OPTIONS]

Option	Description
--description, -d	Invariant constraint text (required)
--global	Apply to every plan in the system (default scope)
--project <NAME>	Scope to a specific project
--action <NAME>	Scope to a specific action template
--format, -f	Output format

Examples:

# Global invariant (applies to all plans)
agents invariant add no-prod-deletes \
  --description "Never delete production data"

# Project-scoped invariant
agents invariant add api-test-coverage \
  --description "All API changes need tests" \
  --project myapp

# Action-scoped invariant
agents invariant add min-coverage \
  --description "Minimum 80% test coverage" \
  --action local/code-coverage

Scope hierarchy (highest to lowest precedence):

Scope	Description
PLAN	Attached directly to a specific plan (via plan use --invariant)
PROJECT	Applies to all plans targeting a project
GLOBAL	Applies to every plan in the system
ACTION	Defined in an action template; promoted to plan scope on plan use

---

agents invariant list

Lists all invariants, with optional scope filtering.

agents invariant list [REGEX] [OPTIONS]

Option	Description
--global	Show only global invariants
--project <NAME>	Show invariants for a specific project
--effective --project <NAME>	Show merged effective set for a project
--format, -f	Output format

Examples:

# List all invariants
agents invariant list

# Filter by scope
agents invariant list --global
agents invariant list --project myapp

# Show the merged effective set (with precedence applied)
agents invariant list --effective --project myapp

# Filter by regex pattern
agents invariant list "data.*safe"

# JSON output
agents invariant list --format json

---

agents invariant remove

Removes an invariant by its ULID.

agents invariant remove <INVARIANT_ID> [OPTIONS]

Option	Description
--yes, -y	Skip the confirmation prompt
--format, -f	Output format

Examples:

# Remove with confirmation prompt
agents invariant remove 01HXYZ1234567890ABCDEFGH

# Remove without confirmation (for scripts)
agents invariant remove 01HXYZ1234567890ABCDEFGH --yes

See also: reference/invariants.md

---

Checkpoint and Rollback Commands (v3.3.0)

agents plan rollback

Restores sandbox state to a previously captured checkpoint.

agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> [OPTIONS]

Option	Description
--yes, -y	Skip the interactive confirmation prompt
--format, -f	Output format: json, yaml, plain, table, rich

Examples:

# Rollback with confirmation prompt
agents plan rollback 01HPLAN... 01HCHECKPOINT...

# Rollback without confirmation (for scripts)
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT...

# JSON output for scripting
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT... --format json

Guards: Rollback is blocked if:

• The plan has already reached the applied terminal state.
• The sandbox has been cleaned up.

Automatic checkpoint triggers (v3.8.0+):

Trigger	When
on_tool_write	Before each write-tool execution
on_tool_write_complete	After each write-tool execution
on_subplan_spawn	Before first subplan execution attempt
on_error	When the Execute phase fails

See also: reference/checkpointing.md

---

Quick Reference

Command	Milestone	Description
agents plan tree <plan_id>	v3.2.0	Render decision tree
agents plan explain <decision_id>	v3.2.0	Show decision details
agents plan correct --mode=revert <decision_id>	v3.3.0	Re-execute from decision point
agents plan correct --mode=append <decision_id> --guidance <text>	v3.3.0	Append guidance as child plan
agents invariant add <name> --description <desc>	v3.2.0	Create invariant
agents invariant list	v3.2.0	List invariants
agents invariant remove <name>	v3.2.0	Remove invariant
agents plan rollback <plan_id> <checkpoint_id>	v3.3.0	Rollback to checkpoint

---

Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor