cleveragents-core/docs/reference/actor_cli.md

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

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

YAML Configuration File

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

Examples

# 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

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

Examples

# 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

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

agents actor remove local/my-actor

agents actor list

List all registered actors.

Synopsis

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

# 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

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

Examples

# 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

agents actor set-default <NAME>

Examples

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