# CLI Commands — Complete Reference

## Global Options

Apply to every command:

```
agents [--data-dir PATH] [--config-path PATH] [--format rich|color|table|plain|json|yaml]
       [--help|-h] [--version] [--install-completion [SHELL]] [--show-completion [SHELL]]
       [-v...] <COMMAND> [<ARGS>...]
```

- `--data-dir PATH`: Override data directory (database, caches, sessions, logs)
- `--config-path PATH`: Override config file path
- `--format FORMAT`: Output rendering format (default: rich, from `core.format` config)
- `-v`: Increase verbosity (repeatable): -v=ERROR, -vv=WARN, -vvv=INFO, -vvvv=DEBUG, -vvvvv=TRACE

## Output Formats

| Format | Description | Use For |
|--------|-------------|---------|
| `rich` | Modern rich CLI with animation, spinners, progress bars | Interactive terminal (default) |
| `color` | Plain text with ANSI color codes | Color-capable terminals |
| `table` | ASCII box-drawing tables with color | Structured visual output |
| `plain` | Plain text, no color, no non-ASCII | Piping, logs, non-terminal consumers |
| `json` | Structured JSON | Scripts, CI/CD, programmatic consumption |
| `yaml` | Structured YAML | Configuration, programmatic consumption |

---

## Plan Commands

```bash
# List plans (filterable)
agents plan list [--phase PHASE] [--state STATE] [--project PROJECT] [--action ACTION] [<REGEX>]

# Create plan (Action → Strategize)
agents plan use [--automation-profile PROFILE]
               [--invariant INVARIANT]...
               [--strategy-actor ACTOR] [--execution-actor ACTOR]
               [--estimation-actor ACTOR] [--invariant-actor ACTOR]
               [--execution-environment RESOURCE_NAME]
               [--execution-env-priority fallback|override]
               [--arg/-a name=value]...
               <ACTION> <PROJECT>...

# Phase transitions
agents plan execute <PLAN_ID>
agents plan apply [--yes|-y] <PLAN_ID>

# Status and inspection
agents plan status <PLAN_ID>
agents plan tree [--show-superseded] <PLAN_ID>
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>
agents plan diff (--correction <CORRECTION_ATTEMPT_ID> | <PLAN_ID>)
agents plan artifacts <PLAN_ID>
agents plan errors <PLAN_ID>

# Correction
agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
                   [--dry-run] [--yes|-y] <DECISION_ID>

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

# Inject guidance mid-execution
agents plan prompt <PLAN_ID> <GUIDANCE>

# Cancel
agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
```

---

## Action Commands

```bash
agents action create --config|-c <CFG_FILE>
agents action list [(--namespace|-n) NS] [(--state|-s) STATE] [<REGEX>]
agents action show <ACTION_NAME>
agents action archive <ACTION_NAME>
```

---

## Session Commands

```bash
agents session create [--actor ACTOR]
agents session list
agents session show <SESSION_ID>
agents session delete [--yes|-y] <SESSION_ID>
agents session export [(--output|-o) FILE] <SESSION_ID>
agents session import (--input|-i) FILE
agents session tell --session <SESSION_ID> [--actor ACTOR] [--stream] <PROMPT>
```

---

## Project Commands

```bash
agents project create [(--description|-d) DESC] [--resource RESOURCE]...
                     [--invariant INVARIANT]... [--invariant-actor ACTOR] <NAME>
agents project link-resource [--read-only] <PROJECT> <RESOURCE>
agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME>
agents project list [(--namespace|-n) NS] [<REGEX>]
agents project show <PROJECT>
agents project delete [--force|-f] [--yes|-y] <NAME>

# Context configuration
agents project context set [--view strategize|execute|apply|default]
                          [--include-resource RESOURCE]...
                          [--exclude-resource RESOURCE]...
                          [--include-path GLOB]...
                          [--exclude-path GLOB]...
                          [--hot-max-tokens N]
                          [--warm-max-decisions N]
                          [--cold-max-decisions N]
                          [--query-limit N]
                          [--max-file-size BYTES]
                          [--max-total-size BYTES]
                          [--summarize|--no-summarize]
                          [--summary-max-tokens N]
                          [--strategy STRATEGY]...
                          [--default-breadth N]
                          [--default-depth INT_OR_NAME]
                          [--depth-gradient HOP:INT_OR_NAME]...
                          [--skeleton-ratio FLOAT]
                          [--temporal-scope current|recent|all]
                          [--auto-refresh|--no-auto-refresh]
                          [--execution-environment RESOURCE_NAME]
                          [--execution-env-priority fallback|override]
                          [--clear] <PROJECT>

agents project context show [--view strategize|execute|apply|default] <PROJECT>
agents project context inspect [--view ...] [--strategy S] [--focus UKO_URI]...
                               [--breadth N] [--depth INT_OR_NAME] <PROJECT>
agents project context simulate [--view ...] [--budget TOKENS]
                                [--focus UKO_URI]... [--strategy S]... <PROJECT>
```

---

## Actor Commands

```bash
agents actor run [(--output|-o) OUTPUT_FILE] [-v...] [--unsafe|-u]
               [--context CONTEXT_NAME] [--context-dir CONTEXT_PATH]
               [--load-context LOAD_CONTEXT_NAME]
               [(--temperature|-t) TEMP] [--allow-rxpy-in-run-mode]
               [--skill SKILL]... <NAME> <PROMPT>

agents actor add --config|-c <FILE> [--update]
agents actor remove <NAME>
agents actor list
agents actor show <NAME>

# Actor context management
agents actor context remove [--yes|-y] (--all|-a | <NAME>)
agents actor context list [<REGEX>]
agents actor context show <NAME>
agents actor context export (--output|-o) FILE <NAME>
agents actor context import [--update] (--input|-i) FILE [<NAME>]
agents actor context clear [--yes|-y] (--all|-a | <NAME>)
```

---

## Skill Commands

```bash
agents skill add --config|-c <FILE> [--update]
agents skill remove [--yes|-y] <NAME>
agents skill list [(--namespace|-n) NS] [--source SOURCE]
agents skill show <NAME>
agents skill tools <NAME>   # lists all tools in skill (including transitive)
```

---

## Tool Commands

```bash
agents tool add --config|-c <FILE> [--update]
agents tool remove [--yes|-y] <NAME>
agents tool list [(--namespace|-n) NS] [--source SOURCE] [--type tool|validation] [<REGEX>]
agents tool show <NAME>
```

---

## Validation Commands

```bash
agents validation add --config|-c <FILE> [--update]
agents validation attach [--project PROJECT | --plan PLAN_ID]
                        <RESOURCE> <VALIDATION> [<ARGS>...]
agents validation detach [--yes|-y] <ATTACHMENT_ID>
# list/show/remove via: agents tool list --type validation, agents tool show, agents tool remove
```

---

## Resource Commands

```bash
# Resource type management
agents resource type add --config|-c <FILE> [--update]
agents resource type remove [--yes|-y] <NAME>
agents resource type list [<REGEX>]
agents resource type show <NAME>

# Resource CRUD
agents resource add [(--description|-d) DESC] [--update] <TYPE> <NAME> [type-specific-flags...]
agents resource remove [--yes|-y] <NAME>
agents resource list [--all] [(--type|-t) TYPE]
agents resource show <RESOURCE>

# Resource exploration
agents resource inspect [--tree] [--file PATH] <RESOURCE>
agents resource tree [(--depth|-d) N] [(--type|-t) TYPE] <RESOURCE>

# DAG management
agents resource link-child <PARENT> <CHILD>
agents resource unlink-child [--yes|-y] <PARENT> <CHILD>

# Container management
agents resource stop <NAME>
agents resource rebuild <NAME>
```

---

## Invariant Commands

```bash
agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
                    [--action ACTION]... [--non-overridable] <INVARIANT_TEXT>
agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]
                     [--action ACTION] [--effective] [<REGEX>]
agents invariant remove [--yes|-y] <INVARIANT_ID>
```

---

## Automation Profile Commands

```bash
agents automation-profile add --config|-c <FILE> [--update]
agents automation-profile remove [--yes|-y] <NAME>
agents automation-profile list [<REGEX>]
agents automation-profile show <NAME>
```

---

## LSP Commands

```bash
agents lsp add --config|-c <FILE> [--update]
agents lsp remove [--yes|-y] <NAME>
agents lsp list [(--namespace|-n) NS] [--language LANG]
agents lsp show <NAME>
agents lsp serve [--log-level LEVEL]
```

---

## Config Commands

```bash
agents config set <key> <value>
agents config get <key>
agents config list [--filter-values REGEX] [<REGEX>]
```

---

## Utility Commands

```bash
agents version     # print CLI version + dependencies
agents info        # show runtime config and status
agents diagnostics # run health checks (config, providers, filesystem)
agents init [--yes|-y]  # first-time setup
```
