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`](reference/plan_cli.md).
For invariant management see [`reference/invariants.md`](reference/invariants.md).
For checkpoint and rollback details see [`reference/checkpointing.md`](reference/checkpointing.md).

---

## Decision Tree Commands (v3.2.0)

### `agents plan tree`

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

```bash
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:**

```bash
# 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`](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.

```bash
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:**

```bash
# 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`](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.

```bash
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.

```bash
# 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.

```bash
# 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`](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.

```bash
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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
agents invariant remove <INVARIANT_ID> [OPTIONS]
```

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

**Examples:**

```bash
# Remove with confirmation prompt
agents invariant remove 01HXYZ1234567890ABCDEFGH

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

See also: [`reference/invariants.md`](reference/invariants.md)

---

## Checkpoint and Rollback Commands (v3.3.0)

### `agents plan rollback`

Restores sandbox state to a previously captured checkpoint.

```bash
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:**

```bash
# 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`](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*