# Actor CLI Reference

The `agents actor` command group manages actor configurations for the
CleverAgents v3 actor system.

## Commands

| Command                  | Description                                  |
|--------------------------|----------------------------------------------|
| `agents actor add`       | Add actor from YAML/JSON config file         |
| `agents actor update`    | Update an existing actor                     |
| `agents actor remove`    | Remove a custom actor by namespaced name     |
| `agents actor list`      | List all registered actors                   |
| `agents actor show`      | Show actor details                           |
| `agents actor set-default` | Set the default actor                      |
| `agents actor run`       | Run the reactive network with actor configs  |

## Namespaced Names

Actor names follow the `[[server:]namespace/]name` format. When no
namespace is provided, the name defaults to `local/`. Built-in actors
use `<provider>/<model>` (e.g. `openai/gpt-4`).

## `agents actor add`

Add a new actor from a YAML or JSON configuration file.

### Synopsis

```bash
agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default] [--option key=value] [--format FORMAT]
```

### YAML Configuration File

```yaml
provider: openai
model: gpt-4
temperature: 0.7
max_tokens: 1024
options:
  stream: true
```

### Examples

```bash
# Add an actor from YAML config
agents actor add local/my-actor --config ./actors/my-actor.yaml

# Add or update an existing actor
agents actor add local/my-actor --config ./actors/my-actor.yaml --update

# Add with option overrides
agents actor add local/my-actor --config actor.yaml --option temperature=0.9

# Add with JSON output
agents actor add local/my-actor --config actor.yaml --format json
```

## `agents actor update`

Update an existing actor configuration.

### Synopsis

```bash
agents actor update <NAME> [--config <FILE>] [--unsafe|--safe] [--set-default] [--option key=value] [--format FORMAT]
```

### Examples

```bash
# Update actor with new config
agents actor update local/my-actor --config ./actors/updated.yaml

# Mark actor as safe
agents actor update local/my-actor --safe

# Update with JSON output
agents actor update local/my-actor --format json
```

## `agents actor remove`

Remove a custom actor by its namespaced name.

### Synopsis

```bash
agents actor remove <NAME>
```

### Rich Output Panels

After removal, the `rich` format renders three panels:

- **Actor Removed** — name, provider, and model of the removed actor.
- **Impact** — number of sessions, active plans, and actions that referenced the actor.
- **Cleanup** — config retention status and number of orphaned contexts.

Followed by a `✓ OK Actor removed` success message.

### Examples

```bash
agents actor remove local/my-actor
```

## `agents actor list`

List all registered actors.

### Synopsis

```bash
agents actor list [--format FORMAT]
```

### Output Formats

| Format  | Description                          |
|---------|--------------------------------------|
| `rich`  | Rich table with colours (default)    |
| `json`  | JSON array of actor objects           |
| `yaml`  | YAML list of actor objects            |
| `plain` | Plain text key-value pairs            |
| `table` | ASCII table without Rich styling     |

### Rich Output

The `rich` format renders a table with columns: **Name**, **Provider**, **Model**,
**Default**, **Built-in**, **Unsafe**, and **Updated**. After the table, a **Summary**
panel is shown with:

| Field | Description |
|-------|-------------|
| Total | Total number of actors |
| Built-in | Count of built-in actors |
| Custom | Count of custom actors |
| Unsafe | Count of actors marked unsafe |
| Providers Used | Number of distinct providers |

Followed by a `✓ OK N actors listed` success message.

### Examples

```bash
# Default rich table
agents actor list

# JSON output for scripting
agents actor list --format json

# YAML output
agents actor list --format yaml
```

## `agents actor show`

Show details for a specific actor.

### Synopsis

```bash
agents actor show <NAME> [--format FORMAT]
```

### Examples

```bash
# Rich panel (default)
agents actor show local/my-actor

# JSON output
agents actor show local/my-actor --format json

# YAML output
agents actor show openai/gpt-4 --format yaml
```

## `agents actor set-default`

Set the default actor used when no actor is specified.

### Synopsis

```bash
agents actor set-default <NAME>
```

### Examples

```bash
agents actor set-default openai/gpt-4
```

## Error Handling

| Error                      | Cause                                    |
|----------------------------|------------------------------------------|
| `Config file not found`    | Specified config file doesn't exist      |
| `Config must be a JSON/YAML object` | Config file is not a valid object |
| `Config file is required`  | No `--config` flag provided for `add`    |
| `Actor config is marked unsafe` | Unsafe config without `--unsafe` flag |
| `Actor not found`          | Named actor doesn't exist                |