cleveragents-core/docs/api/cli-reference.md

# CLI Reference

CleverAgents ships two equivalent entry points: **`agents`** and **`cleveragents`**.
Both accept the same commands, flags, and arguments.

See [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) for the design rationale
behind the CLI structure and output rendering framework.

---

## Synopsis

```
agents|cleveragents  [--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>...]
```

---

## Global Flags

These flags apply to every command and must appear **before** the subcommand name.

| Flag | Short | Description |
|------|-------|-------------|
| `--data-dir PATH` | | Override the global data directory (database, caches, sessions, logs). Defaults to the platform data location. |
| `--config-path PATH` | | Override the global configuration file path. |
| `--format FORMAT` | | Output rendering format. One of `rich` (default), `color`, `table`, `plain`, `json`, `yaml`. Can also be set via `core.format` config key. |
| `--help` | `-h` | Print help for the current command and exit. |
| `--version` | | Print the installed version and exit. |
| `--install-completion [SHELL]` | | Install shell tab-completion for the given shell. |
| `--show-completion [SHELL]` | | Print the completion script for the given shell. |
| `-v` | | Increase log verbosity (repeatable). `-v`=ERROR, `-vv`=WARN, `-vvv`=INFO, `-vvvv`=DEBUG, `-vvvvv`=TRACE. Affects the current invocation only. |

### Output Formats

| Format | Description | Best For |
|--------|-------------|----------|
| `rich` | Rich CLI elements with animated spinners, progress bars, and color | Interactive terminal use **(default)** |
| `color` | Plain scrolling text with ANSI color codes | Color-capable terminals |
| `table` | ASCII box-drawing tables and panels with color | Structured visual output |
| `plain` | Plain text, no color or non-ASCII characters | Piping, logs, non-terminal consumers |
| `json` | Structured JSON | Scripts, CI/CD pipelines |
| `yaml` | Structured YAML | Configuration, programmatic consumption |

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `CLEVERAGENTS_DATA_DIR` | Default data directory (overridden by `--data-dir`) |
| `CLEVERAGENTS_CONFIG_PATH` | Default config file path (overridden by `--config-path`) |
| `CLEVERAGENTS_DEFAULT_PROVIDER` | Pin the AI provider (`openai`, `anthropic`, `google`, …) |
| `CLEVERAGENTS_DEFAULT_MODEL` | Pin the model ID |
| `OPENAI_API_KEY` | OpenAI credentials |
| `ANTHROPIC_API_KEY` | Anthropic credentials |
| `GOOGLE_API_KEY` / `GOOGLE_GENAI_API_KEY` | Google credentials |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI credentials |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL |
| `AZURE_OPENAI_DEPLOYMENT` | Azure deployment name |
| `OPENROUTER_API_KEY` | OpenRouter credentials |
| `GEMINI_API_KEY` / `GOOGLE_GEMINI_API_KEY` | Gemini credentials |
| `COHERE_API_KEY` | Cohere credentials |
| `GROQ_API_KEY` | Groq credentials |
| `TOGETHER_API_KEY` | Together AI credentials |
| `CLEVERAGENTS_TESTING_USE_MOCK_AI` | Force mock provider in tests (`true`/`false`) |
| `CLEVERAGENTS_LANGSMITH_ENABLED` | Enable LangSmith tracing (`true`/`false`) |
| `CLEVERAGENTS_LANGSMITH_PROJECT` | LangSmith project name |
| `CLEVERAGENTS_LANGSMITH_API_KEY` | LangSmith API key |
| `CLEVERAGENTS_LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `WARN`, `ERROR`) |
| `CLEVERAGENTS_LOG_FORMAT` | Log format (`json`, `text`) |

---

## Top-Level Commands

| Command | Description |
|---------|-------------|
| `agents version` | Print version and exit |
| `agents info` | Print system snapshot (mode, paths, runtime, projects) |
| `agents diagnostics` | Check credentials, provider selection, and actor configuration |
| `agents init [--yes\|-y]` | Initialize a new CleverAgents workspace in the current directory |
| `agents tui` | Launch the interactive Textual TUI |

### `agents diagnostics`

Prints whether the provider registry can see your credentials, which actor/provider
is selected, and any configuration warnings.

```bash
agents diagnostics
```

### `agents tui`

Launches the full-screen interactive terminal UI.  Requires the `cleveragents[tui]`
extra (`pip install "cleveragents[tui]"`).

```bash
agents tui
```

---

## Action Commands

Actions are reusable YAML-defined plan templates.

| Command | Description |
|---------|-------------|
| `agents action create --config\|-c <FILE>` | Register a new action from a YAML config file |
| `agents action list [--namespace\|-n NS] [--state\|-s STATE] [REGEX]` | List registered actions, optionally filtered |
| `agents action show <ACTION_NAME>` | Show full details of an action |
| `agents action archive <ACTION_NAME>` | Archive (soft-delete) an action |

### Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--config FILE` | `-c` | Path to the action YAML configuration file |
| `--namespace NS` | `-n` | Filter by namespace |
| `--state STATE` | `-s` | Filter by state (`active`, `archived`) |

### Example

```bash
# Register an action from a YAML file
agents action create --config examples/actions/refactor.yaml

# List all active actions in the local namespace
agents action list --namespace local --state active

# Inspect a specific action
agents action show local/refactor

# Archive an action
agents action archive local/refactor
```

---

## Actor Commands

Actors are YAML-configured execution units that encapsulate an LLM and a set of tools.

| Command | Description |
|---------|-------------|
| `agents actor add --config\|-c <FILE> [--update]` | Register or update an actor from a YAML config file |
| `agents actor remove <NAME>` | Remove a custom actor |
| `agents actor list` | List all registered actors |
| `agents actor show <NAME>` | Show full details of an actor |
| `agents actor run [flags] <NAME> <PROMPT>` | Run an actor with a prompt |
| `agents actor set-default <NAME>` | Set the default actor for CLI commands |
| `agents actor context list [REGEX]` | List saved actor contexts |
| `agents actor context show <NAME>` | Show a saved actor context |
| `agents actor context export --output\|-o <FILE> <NAME>` | Export a context to a file |
| `agents actor context import [--update] --input\|-i <FILE> [NAME]` | Import a context from a file |
| `agents actor context remove [--yes\|-y] (--all\|-a\|<NAME>)` | Remove one or all saved contexts |
| `agents actor context clear [--yes\|-y] (--all\|-a\|<NAME>)` | Clear context history |

### `agents actor run` Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--output FILE` | `-o` | Write output to a file |
| `--unsafe` | `-u` | Allow unsafe actor configurations |
| `--context NAME` | | Load a named context |
| `--context-dir PATH` | | Load context from a directory |
| `--load-context NAME` | | Load a previously saved context |
| `--temperature TEMP` | `-t` | Override the LLM temperature |
| `--skill SKILL` | | Attach a skill (repeatable) |

### Example

```bash
# Add a custom actor
agents actor add --config examples/actors/my-actor.yaml

# List all actors (built-in and custom)
agents actor list

# Show actor details
agents actor show openai/gpt-4o

# Run an actor with a prompt
agents actor run openai/gpt-4o "Summarize the current project status"

# Set a default actor so --actor is not required
agents actor set-default openai/gpt-4o
```

> **Note:** Built-in actors (`<provider>/<model>`) are immutable.
> Custom actors must be named `local/<id>`.
> Use `--unsafe` when adding/updating configurations marked unsafe.

---

## Plan Commands

Plans are instantiated from Actions and progress through four phases:
**Action → Strategize → Execute → Apply**.

| Command | Description |
|---------|-------------|
| `agents plan use [flags] <ACTION> <PROJECT>...` | Instantiate a plan from an action and bind it to one or more projects |
| `agents plan execute <PLAN_ID>` | Advance a plan through the Strategize and Execute phases |
| `agents plan apply [--yes\|-y] <PLAN_ID>` | Apply the sandbox changeset to real project resources |
| `agents plan status <PLAN_ID>` | Show the current phase, state, and progress of a plan |
| `agents plan list [flags] [REGEX]` | List plans, optionally filtered by phase, state, project, or action |
| `agents plan tree [--show-superseded] <PLAN_ID>` | Display the decision tree for a plan |
| `agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>` | Explain a specific decision in a plan |
| `agents plan correct [flags] <DECISION_ID>` | Correct a decision and recompute affected subtrees |
| `agents plan diff (--correction <ID>\|<PLAN_ID>)` | Show the diff for a plan or correction attempt |
| `agents plan cancel [--reason\|-r REASON] <PLAN_ID>` | Cancel a running plan |
| `agents plan rollback [--yes\|-y] <PLAN_ID> <CHECKPOINT_ID>` | Roll back a plan to a checkpoint |
| `agents plan artifacts <PLAN_ID>` | List artifacts produced by a plan |
| `agents plan prompt <PLAN_ID> <GUIDANCE>` | Send guidance to a running plan |
| `agents plan errors <PLAN_ID>` | Show errors encountered during plan execution |

### `agents plan use` Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--automation-profile PROFILE` | | Automation profile to use (e.g. `review`, `full-auto`) |
| `--invariant TEXT` | | Add a plan-scoped invariant (repeatable) |
| `--strategy-actor ACTOR` | | Override the strategy actor |
| `--execution-actor ACTOR` | | Override the execution actor |
| `--estimation-actor ACTOR` | | Override the estimation actor |
| `--invariant-actor ACTOR` | | Override the invariant reconciliation actor |
| `--execution-environment RESOURCE` | | Specify the execution environment resource |
| `--execution-env-priority PRIORITY` | | `fallback` or `override` |
| `--arg name=value` | `-a` | Pass a typed argument to the action (repeatable) |

### `agents plan list` Flags

| Flag | Description |
|------|-------------|
| `--phase PHASE` | Filter by phase (`action`, `strategize`, `execute`, `apply`) |
| `--state STATE` | Filter by state (`running`, `applied`, `errored`, `cancelled`, …) |
| `--project PROJECT` | Filter by project name |
| `--action ACTION` | Filter by action name |

### `agents plan correct` Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--mode MODE` | | `revert` (undo the decision) or `append` (add guidance) |
| `--guidance TEXT` | `-g` | Natural-language correction guidance |
| `--dry-run` | | Preview the correction without applying it |
| `--yes` | `-y` | Skip confirmation prompt |

### Example

```bash
# Instantiate a plan from the "refactor" action for the "my-project" project
agents plan use local/refactor my-project --arg target=src/

# Check plan status
agents plan status 01JXYZ...

# Execute the plan (Strategize + Execute phases)
agents plan execute 01JXYZ...

# Review the decision tree before applying
agents plan tree 01JXYZ...

# Apply the sandbox changes to real resources
agents plan apply 01JXYZ...

# Correct a specific decision
agents plan correct --mode revert --guidance "Use a different approach" 01JDEC...

# Show the diff for a plan
agents plan diff 01JXYZ...
```

---

## Project Commands

Projects are named scopes linking resources, context policies, and invariants.

| Command | Description |
|---------|-------------|
| `agents project create [flags] <NAME>` | Create a new project |
| `agents project list [--namespace\|-n NS] [REGEX]` | List projects |
| `agents project show <PROJECT>` | Show project details |
| `agents project delete [--force\|-f] [--yes\|-y] <NAME>` | Delete a project |
| `agents project link-resource [--read-only] <PROJECT> <RESOURCE>` | Link a resource to a project |
| `agents project unlink-resource [--yes\|-y] <PROJECT> <RESOURCE_NAME>` | Unlink a resource from a project |
| `agents project context set [flags] <PROJECT>` | Configure the ACMS context policy for a project |
| `agents project context show [--view VIEW] <PROJECT>` | Show the context policy for a project |
| `agents project context inspect [flags] <PROJECT>` | Inspect the assembled context for a project |
| `agents project context simulate [flags] <PROJECT>` | Simulate context assembly for a project |

### `agents project create` Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--description DESC` | `-d` | Human-readable project description |
| `--resource RESOURCE` | | Link a resource at creation time (repeatable) |
| `--invariant TEXT` | | Add a project-scoped invariant (repeatable) |
| `--invariant-actor ACTOR` | | Override the invariant reconciliation actor |

### `agents project context set` Flags

| Flag | Description |
|------|-------------|
| `--view VIEW` | Context view: `strategize`, `execute`, `apply`, `default` |
| `--include-resource RESOURCE` | Include a resource in context (repeatable) |
| `--exclude-resource RESOURCE` | Exclude a resource from context (repeatable) |
| `--include-path GLOB` | Include paths matching a glob (repeatable) |
| `--exclude-path GLOB` | Exclude paths matching a glob (repeatable) |
| `--hot-max-tokens N` | Maximum tokens in the hot context tier |
| `--warm-max-decisions N` | Maximum decisions in the warm tier |
| `--cold-max-decisions N` | Maximum decisions in the cold tier |
| `--strategy STRATEGY` | Context assembly strategy (repeatable) |
| `--execution-environment RESOURCE` | Preferred execution environment |
| `--execution-env-priority PRIORITY` | `fallback` or `override` |
| `--clear` | Reset the context policy to defaults |

### Example

```bash
# Create a project with a linked resource
agents project create my-project --description "Main application" \
  --resource local/my-repo

# Link an additional resource (read-only)
agents project link-resource my-project local/docs --read-only

# List all projects
agents project list

# Show project details
agents project show my-project

# Configure context policy for the strategize phase
agents project context set my-project --view strategize \
  --hot-max-tokens 8000 --strategy semantic

# Delete a project
agents project delete my-project --yes
```

---

## Resource Commands

Resources are ULID-identified entities registered in the Resource Registry
(git repos, filesystems, databases, containers, etc.).

| Command | Description |
|---------|-------------|
| `agents resource add [flags] <TYPE> <NAME> [type-specific-flags...]` | Register a new resource |
| `agents resource remove [--yes\|-y] <NAME>` | Remove a resource |
| `agents resource list [--all] [--type\|-t TYPE]` | List registered resources |
| `agents resource show <RESOURCE>` | Show resource details |
| `agents resource inspect [--tree] [--file PATH] <RESOURCE>` | Inspect resource contents |
| `agents resource tree [--depth\|-d N] [--type\|-t TYPE] <RESOURCE>` | Show the resource DAG subtree |
| `agents resource link-child <PARENT> <CHILD>` | Add a child link in the resource DAG |
| `agents resource unlink-child [--yes\|-y] <PARENT> <CHILD>` | Remove a child link |
| `agents resource stop <NAME>` | Stop a running resource (e.g. a container) |
| `agents resource rebuild <NAME>` | Rebuild a resource (e.g. rebuild a devcontainer) |
| `agents resource type add --config\|-c <FILE> [--update]` | Register a custom resource type |
| `agents resource type remove [--yes\|-y] <NAME>` | Remove a custom resource type |
| `agents resource type list [REGEX]` | List resource types |
| `agents resource type show <NAME>` | Show resource type details |

### Example

```bash
# Register a git-checkout resource
agents resource add git-checkout local/my-repo --url https://github.com/org/repo.git

# List all resources
agents resource list

# Show resource details
agents resource show local/my-repo

# Inspect the resource tree
agents resource tree local/my-repo --depth 3

# Stop a running devcontainer
agents resource stop local/my-devcontainer
```

---

## Skill Commands

Skills are composable, versioned capability bundles that expose tools to actors.

| Command | Description |
|---------|-------------|
| `agents skill add --config\|-c <FILE> [--update]` | Register or update a skill from a YAML config file |
| `agents skill remove [--yes\|-y] <NAME>` | Remove a skill |
| `agents skill list [--namespace\|-n NS] [--source SOURCE]` | List registered skills |
| `agents skill show <NAME>` | Show skill details |
| `agents skill tools <NAME>` | List the tools exposed by a skill |

### Example

```bash
# Register a skill
agents skill add --config examples/skills/deploy.yaml

# List all skills
agents skill list

# Show skill details
agents skill show local/deploy-to-staging

# List tools in a skill
agents skill tools local/deploy-to-staging
```

---

## Tool Commands

Tools are the atomic unit of execution — namespaced, independently registered callables.

| Command | Description |
|---------|-------------|
| `agents tool add --config\|-c <FILE> [--update]` | Register or update a tool from a YAML config file |
| `agents tool remove [--yes\|-y] <NAME>` | Remove a tool |
| `agents tool list [--namespace\|-n NS] [--source SOURCE] [--type tool\|validation] [REGEX]` | List registered tools |
| `agents tool show <NAME>` | Show tool details |

### Example

```bash
# Register a custom tool
agents tool add --config examples/tools/my-tool.yaml

# List all tools from MCP sources
agents tool list --source mcp

# List only validation tools
agents tool list --type validation

# Show tool details
agents tool show local/my-tool
```

---

## Session Commands

Sessions are persistent conversation threads tied to an actor.

| Command | Description |
|---------|-------------|
| `agents session create [--actor ACTOR]` | Create a new conversation session |
| `agents session list` | List all sessions |
| `agents session show <SESSION_ID>` | Show session details and message history |
| `agents session delete [--yes\|-y] <SESSION_ID>` | Delete a session |
| `agents session export [--output\|-o FILE] [--format json\|md] <SESSION_ID>` | Export a session to JSON or Markdown |
| `agents session import --input\|-i <FILE>` | Import a session from a JSON file |
| `agents session tell --session <SESSION_ID> [--actor ACTOR] [--stream] <PROMPT>` | Send a message to a session |

### Example

```bash
# Create a session with a specific actor
agents session create --actor openai/gpt-4o

# List all sessions
agents session list

# Export as canonical JSON (importable)
agents session export --session-id abc123 --output session.json

# Export as Markdown transcript (human-readable, not importable)
agents session export --session-id abc123 --output session.md --format md

# Import a session
agents session import --input session.json

# Send a message to a session
agents session tell --session abc123 "What is the current plan status?"
```

---

## Invariant Commands

Invariants are natural-language constraints on plan execution, scoped to
global, project, action, or plan level.

| Command | Description |
|---------|-------------|
| `agents invariant add [flags] <INVARIANT_TEXT>` | Add an invariant |
| `agents invariant list [flags] [REGEX]` | List invariants |
| `agents invariant remove [--yes\|-y] <INVARIANT_ID>` | Remove an invariant |

### `agents invariant add` Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--global` | | Add a global invariant |
| `--project PROJECT` | `-p` | Scope to a project |
| `--plan PLAN_ID` | | Scope to a plan (repeatable) |
| `--action ACTION` | | Scope to an action (repeatable) |

### `agents invariant list` Flags

| Flag | Description |
|------|-------------|
| `--global` | Show global invariants |
| `--project PROJECT` | Filter by project |
| `--plan PLAN_ID` | Filter by plan |
| `--action ACTION` | Filter by action |
| `--effective` | Show the merged effective invariant set (plan > action > project > global) |

### Example

```bash
# Add a global invariant
agents invariant add --global "All output files must be UTF-8 encoded"

# Add a project-scoped invariant
agents invariant add --project my-project "Do not modify files in the vendor/ directory"

# List effective invariants for a plan
agents invariant list --plan 01JXYZ... --effective

# Remove an invariant
agents invariant remove 01JINV...
```

---

## Context Commands

The `agents context` group manages actor-level context (distinct from project
context policies managed under `agents project context`).

| Command | Description |
|---------|-------------|
| `agents actor context list [REGEX]` | List saved actor contexts |
| `agents actor context show <NAME>` | Show a saved actor context |
| `agents actor context add` | Add context entries |
| `agents actor context export --output\|-o <FILE> <NAME>` | Export a context to a file |
| `agents actor context import [--update] --input\|-i <FILE> [NAME]` | Import a context from a file |
| `agents actor context remove [--yes\|-y] (--all\|-a\|<NAME>)` | Remove one or all saved contexts |
| `agents actor context clear [--yes\|-y] (--all\|-a\|<NAME>)` | Clear context history |

---

## Server Commands

Server mode connects the CLI to a remote CleverAgents server.

| Command | Description |
|---------|-------------|
| `agents server connect --url <URL> --token <TOKEN>` | Configure a remote CleverAgents server connection |
| `agents server status` | Show the current server connection status |

### Example

```bash
# Connect to a remote server
agents server connect --url https://my-server.example.com --token <TOKEN>

# Check connection status
agents server status
```

---

## LSP Commands

LSP servers provide language intelligence (diagnostics, completions, type info) to actors.

| Command | Description |
|---------|-------------|
| `agents lsp add --config\|-c <FILE> [--update]` | Register an LSP server |
| `agents lsp remove [--yes\|-y] <NAME>` | Remove an LSP server |
| `agents lsp list [--namespace\|-n NS] [--language LANG]` | List registered LSP servers |
| `agents lsp show <NAME>` | Show LSP server details |
| `agents lsp serve [--log-level LEVEL]` | Start the CleverAgents LSP server (for IDE integration) |

---

## Automation Profile Commands

Automation profiles define confidence thresholds that gate which plan operations
proceed automatically versus requiring human approval.

| Command | Description |
|---------|-------------|
| `agents automation-profile add --config\|-c <FILE> [--update]` | Register or update an automation profile |
| `agents automation-profile remove [--yes\|-y] <NAME>` | Remove a custom automation profile |
| `agents automation-profile list [REGEX]` | List automation profiles |
| `agents automation-profile show <NAME>` | Show automation profile details |

Built-in profiles (immutable): `manual`, `review`, `semi-auto`, `full-auto` (and four intermediate levels).

---

## Validation Commands

Validations are tool subtypes with pass/fail semantics, always attached to a resource.

| Command | Description |
|---------|-------------|
| `agents validation add --config\|-c <FILE> [--update]` | Register a validation |
| `agents validation attach [--project PROJECT\|--plan PLAN_ID] <RESOURCE> <VALIDATION> [ARGS...]` | Attach a validation to a resource |
| `agents validation detach [--yes\|-y] <ATTACHMENT_ID>` | Detach a validation |

---

## Config Commands

| Command | Description |
|---------|-------------|
| `agents config set <key> <value>` | Set a configuration key |
| `agents config get <key>` | Get a configuration key |
| `agents config list [--filter-values REGEX] [REGEX]` | List configuration keys |

### Example

```bash
# Set the default output format
agents config set core.format json

# Pin the default provider
agents config set actor.default.provider openai

# List all config keys
agents config list
```

---

## Naming Convention

All entities use the namespaced name format:

```
[[server:]namespace/]name
```

- **Built-in actors** use provider prefixes: `openai/gpt-4o`, `anthropic/claude-4-sonnet`
- **Custom entities** use `local/` prefix: `local/my-actor`, `local/my-skill`
- **Server-scoped** entities: `myserver:myns/my-entity`
- **Built-in resource types** are unnamespaced: `git-checkout`, `fs-mount`

Plans and resources are identified by **ULID** (Universally Unique Lexicographically
Sortable Identifier) when precision is needed, especially in hierarchies.