forked from HAL9000/cleveragents-core
freemo
0382b2f722
- CHANGELOG: add Fixed entries for PRs #1574, #1570, #1569, #1547, #1548, #1522, #1524, #1525, #1520, #1553 covering rich output panels for session, actor, and plan commands, plus version commit SHA and provider fix - docs/reference/session_cli.md: document new rich output panels for session create (Settings, Actor Details), session list (Name column, Summary panel), session show (Automation field), session delete (Deletion Summary, Cleanup panels); update export to document --format md - docs/reference/actor_cli.md: document new rich output panels for actor remove (Actor Removed, Impact, Cleanup) and actor list (Summary panel) - docs/reference/plan_cli.md: document new rich output for plan list (Elapsed column, Filters panel, Summary panel) - docs/reference/cli_system_commands.md: document commit SHA resolution order (CLEVERAGENTS_COMMIT env var → git rev-parse → 'unknown') ISSUES CLOSED: #1574 #1570 #1569 #1547 #1548 #1522 #1524 #1525 #1520 #1553
207 lines
5.0 KiB
Markdown
207 lines
5.0 KiB
Markdown
# 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 |
|