# REPL and Actor Run: Interactive AI Sessions from the Terminal

## Overview

CleverAgents provides two complementary ways to run AI actors interactively
from the command line:

1. **`agents repl`** — A persistent interactive shell where you type commands
   without the `agents` prefix, with history, tab-completion, persona
   management, and multi-session support.
2. **`agents actor run`** — A single-shot command that sends one prompt to a
   named actor and prints the result, ideal for scripting and automation.

This guide walks through both commands with real, verified output.

## Prerequisites

- CleverAgents installed (`pip install cleveragents` or from source with `uv sync`)
- Python 3.13 or higher

## What You'll Learn

- How to start the REPL and use built-in commands (`:help`, `:exit`, `!!`)
- How to run any CLI command inside the REPL without the `agents` prefix
- How to use shell passthrough (`!cmd`) inside the REPL
- How to manage personas and sessions within the REPL
- How to use `@reference` expansion for inline file/actor/skill references
- How to run a single-shot prompt with `agents actor run`
- How to save output to a file, override temperature, and persist context

---

## Part 1: The Interactive REPL (`agents repl`)

### Step 1: Start the REPL

```bash
$ agents repl
```

**Actual Output:**
```
CleverAgents REPL — type :help for commands, :exit to quit.

agents [default:default]>
```

The prompt shows `agents [<session>:<persona>]>`. By default you are in the
`default` session with the `default` persona. If you have a project and plan
active via environment variables, the prompt reflects them:

```bash
$ CLEVERAGENTS_PROJECT=myproject CLEVERAGENTS_PLAN=sprint-1 agents repl
```

**Prompt becomes:**
```
agents (myproject/sprint-1) [default:default]>
```

**Options:**
```
$ agents repl --help

 Usage: agents repl [OPTIONS] COMMAND [ARGS]...

 Start an interactive REPL session

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --no-history                Disable readline history loading and saving.     │
│ --history-path        PATH  Custom path for the history file.                │
│                             [default: /home/user/.cleveragents/history]      │
│ --help                      Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

---

### Step 2: Get Help with `:help`

```
agents [default:default]> :help
```

**Actual Output:**
```
CleverAgents Interactive REPL

Built-in commands
  :help          Show this help message
  :exit / :quit  Exit the REPL
  !!             Repeat the last command

Input modes
  @reference     Inline reference expansion and fuzzy matching
  /command       Slash command mode
  !shell cmd     Shell command passthrough
  Full-screen UI: run agents tui

Slash commands
  /persona
  /persona list
  /persona set
  /persona create
  /persona pick
  /persona delete
  /persona export
  /persona import
  /session list
  /session new
  /session switch

CLI commands
  version
  info
  diagnostics
  init
  project
  context
  plan
  actor
  action
  resource
  skill
  lsp
  cleanup
  config
  session
  tool
  validation
  auto-debug
  automation-profile
  invariant
  tell
  build
  apply
  context-load
  context-add
  tui

Type any CLI command without the leading 'agents' prefix.
Use \ at end of line for multi-line input.
```

**What's Happening:**
The REPL exposes every CleverAgents CLI command without the `agents` prefix.
Type `version` instead of `agents version`, `actor list` instead of
`agents actor list`, and so on.

---

### Step 3: Run CLI Commands Inside the REPL

Any CLI command works inside the REPL — just drop the `agents` prefix:

```
agents [default:default]> version
```

**Actual Output:**
```
╭── CLI Version ───╮
│ CleverAgents CLI │
│ Version: 1.0.0   │
│ Channel: stable  │
│ Python: 3.13.9   │
╰──────────────────╯
╭──────── Build ─────────╮
│ Build Date: 2026-04-07 │
│ Commit: d250e9e5       │
│ Schema: v3             │
│ Platform: linux-x86_64 │
╰────────────────────────╯
╭───── Dependencies ─────╮
│ langgraph: 1.1.6       │
│ langchain-core: 1.2.26 │
│ pydantic: 2.12.5       │
│ typer: 0.23.1          │
╰────────────────────────╯
OK Version reported
```

```
agents [default:default]> actor list
```

**Actual Output:**
```
                                Actors (5 total)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                            ┃ Provider    ┃ Model                                    ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ anthropic/claude-sonnet-4-20250514              │ Anthropic   │ claude-sonnet-4-20250514                 │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ gemini/gemini-2.0-flash                         │ Gemini      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ google/gemini-2.0-flash                         │ Google      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ openai/gpt-4o                                   │ Openai      │ gpt-4o                                   │    ✓    │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ openrouter/anthropic-claude-sonnet-4-20250514   │ Openrouter  │ anthropic/claude-sonnet-4-20250514       │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
└─────────────────────────────────────────────────┴─────────────┴──────────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘
╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total: 5                                                                     │
│ Built-in: 5                                                                  │
│ Custom: 0                                                                    │
│ Unsafe: 0                                                                    │
│ Providers Used: 5                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK 5 actors listed
```

You can also use output format flags:

```
agents [default:default]> config list --format json
```

This returns the full configuration as a JSON envelope — useful for piping
to `jq` or other tools.

---

### Step 4: Repeat the Last Command with `!!`

```
agents [default:default]> version
[... version output ...]

agents [default:default]> !!
version
[... version output again ...]
```

**What's Happening:**
`!!` echoes the last command in dim text and re-executes it. If there is no
previous command, the REPL prints:

```
agents [default:default]> !!
No previous command.
```

---

### Step 5: Shell Passthrough with `!`

Prefix any line with `!` to run it as a shell command:

```
agents [default:default]> !echo Hello from shell mode
Hello from shell mode

agents [default:default]> !ls -1 examples/actors/
code_review.yaml
estimator.yaml
graph_workflow.yaml
hierarchical_workflow.yaml
llm_with_tools.yaml
simple_graph.yaml
simple_llm.yaml
strategy_with_subplan.yaml
tool_collection.yaml
```

**What's Happening:**
Shell mode runs the command via `subprocess.run` with a 30-second timeout.
Dangerous patterns (e.g. `rm -rf /`) trigger a confirmation prompt before
execution. Shell mode can be disabled entirely by setting
`CLEVERAGENTS_DISABLE_SHELL_MODE=1`.

---

### Step 6: Multi-Line Input with `\`

End a line with `\` to continue on the next line:

```
agents [default:default]> actor list \
... --format json
```

**What's Happening:**
The REPL collects continuation lines (shown with `... ` prompt) and joins
them with a space before dispatching. This is useful for long commands with
many flags.

---

### Step 7: Persona Management with `/persona`

Personas let you give a named identity to an actor configuration. The active
persona is shown in the REPL prompt.

```
agents [default:default]> /persona create dev --actor openai/gpt-4o
Created persona: dev

agents [default:default]> /persona list
Personas
 * default -> local/mock-default
   dev -> openai/gpt-4o

agents [default:default]> /persona set dev
Active persona: dev

agents [default:dev]> /persona list
Personas
   default -> local/mock-default
 * dev -> openai/gpt-4o
```

**Actual Output (verified):**
```
Created persona: dev
Personas
 * default -> local/mock-default
   dev -> openai/gpt-4o
Active persona: dev
Personas
   default -> local/mock-default
 * dev -> openai/gpt-4o
```

**What's Happening:**
- `/persona create <name> --actor <actor-name>` registers a new persona
- `/persona list` shows all personas; `*` marks the active one
- `/persona set <name>` switches the active persona (updates the prompt)
- `/persona pick` opens an interactive numbered picker
- `/persona export <name> [path]` exports a persona to YAML
- `/persona import <path>` imports a persona from YAML
- `/persona delete <name>` removes a persona (resets sessions using it to `default`)

---

### Step 8: Session Management with `/session`

The REPL supports multiple named sessions, each with its own active persona:

```
agents [default:dev]> /session list
REPL Sessions
 * default (persona=dev)

agents [default:dev]> /session new work
Created session: work

agents [default:dev]> /session switch work
Switched session: work

agents [work:dev]> /session list
REPL Sessions
   default (persona=dev)
 * work (persona=dev)
```

**Actual Output (verified):**
```
REPL Sessions
 * default (persona=dev)
Created session: work
Switched session: work
REPL Sessions
   default (persona=dev)
 * work (persona=dev)
```

**What's Happening:**
Sessions are lightweight in-memory contexts. Each session tracks its own
active persona independently. Switching sessions updates the prompt to show
the new session name. Sessions are not persisted between REPL invocations —
they exist only for the lifetime of the current REPL process.

---

### Step 9: `@reference` Expansion

The REPL supports inline `@` tokens that expand to canonical references:

```
agents [default:default]> info @README.md
info @file:README.md
[... info output with README.md context ...]
```

**What's Happening:**
When you type `@README.md`, the REPL:
1. Builds a catalog of files, actors, tools, and skills in the current directory
2. Fuzzy-matches `README.md` against the file catalog
3. Expands the token to `@file:README.md` (shown in dim text)
4. Passes the expanded line to the CLI dispatcher

You can be explicit with category prefixes:
- `@file:src/main.py` — reference a specific file
- `@actor:openai/gpt-4o` — reference an actor
- `@skill:local/file-ops` — reference a skill
- `@tool:files/read_file` — reference a tool

If no match is found, the REPL prints suggestions:
```
Reference suggestions: @file:README.md, @file:pyproject.toml, ...
```

---

### Step 10: Exit the REPL

```
agents [default:default]> :exit
```

Or press **Ctrl+D** (EOF). The REPL saves readline history to
`~/.cleveragents/history` (unless `--no-history` was passed) and exits
with code 0.

---

## Part 2: Single-Shot Actor Run (`agents actor run`)

### Step 1: Explore the Command

```bash
$ agents actor run --help
```

**Actual Output:**
```
 Usage: agents actor run [OPTIONS] NAME PROMPT

 Run the reactive network once with actor-first configs.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    name        TEXT  Actor name to run (resolved from actor registry)      │
│                        [required]                                            │
│ *    prompt      TEXT  Prompt text to send to the actor [required]           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config                  -c      FILE     YAML config paths (overrides      │
│                                            registry-based name resolution)   │
│ --output                  -o      FILE                                       │
│ --verbose                 -v      INTEGER  [default: 0]                      │
│ --unsafe                  -u               Confirm unsafe configs            │
│ --context                         TEXT     Name for saving/reusing context   │
│ --context-dir                     PATH     Directory to store context data   │
│ --load-context                    FILE     Load context from JSON; imports   │
│                                            into named context when provided  │
│ --temperature             -t      FLOAT    Override temperature              │
│ --allow-rxpy-in-run-mode                   Allow RxPy stream routes in run   │
│                                            mode (bypass validation)          │
│ --skill                           NAME     Skill to attach; only augments    │
│                                            tool-bearing agents (repeatable)  │
│ --help                                     Show this message and exit.       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

---

### Step 2: Run a Built-In Actor

The simplest form uses a built-in actor name from the registry:

```bash
$ agents actor run openai/gpt-4o "Say hello"
```

**Actual Output:**
```
Hello! I'm an AI assistant powered by GPT-4o. How can I help you today?
```

**What's Happening:**
1. `openai/gpt-4o` is looked up in the actor registry
2. The actor's YAML configuration is written to a temporary file
3. `ReactiveCleverAgentsApp` runs the actor with the given prompt
4. The result is printed to stdout and the temp file is cleaned up

---

### Step 3: Run with a Custom Config File

For custom actors or when you want to override the registry config:

```bash
$ cat > my-assistant.yaml << 'EOF'
name: local/demo-assistant
type: llm
description: A simple demonstration assistant
version: "1.0"

provider: openai
model: gpt-4o
system_prompt: |
  You are a helpful assistant. Answer questions clearly and concisely.

context_view: executor
memory:
  enabled: true
  max_messages: 20
  max_tokens: 4000
EOF

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml
```

**Actual Output:**
```
The capital of France is Paris. It is a major European city and has been
the capital since the 10th century.
```

**What's Happening:**
When `--config` is provided, it takes precedence over registry-based name
resolution. The `NAME` argument is still required but is used only for
display/logging purposes when `--config` is present.

---

### Step 4: Save Output to a File

```bash
$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml \
    --output answer.txt
```

**Actual Output (stdout):**
```
Output written to /path/to/answer.txt
```

**File contents (`answer.txt`):**
```
Paris is the capital of France.
```

**What's Happening:**
When `--output` is provided, the result is written to the file instead of
stdout. The confirmation message is still printed to stdout. This is ideal
for capturing AI output in scripts.

---

### Step 5: Override Temperature

```bash
$ agents actor run local/demo-assistant "Write a haiku about mountains" \
    --config my-assistant.yaml \
    --temperature 0.9
```

**Actual Output:**
```
A haiku:
Silent mountain peak
Clouds drift through ancient valleys
Echoes fade to peace
```

**What's Happening:**
`--temperature` overrides the temperature setting in the actor config. Higher
values (0.7–1.0) produce more creative output; lower values (0.0–0.3) produce
more deterministic output.

---

### Step 6: Persist Context Across Calls

Use `--context` to name a conversation context that persists between calls:

```bash
# First call — starts a new context
$ agents actor run local/demo-assistant \
    "I'm working on a Python project" \
    --config my-assistant.yaml \
    --context my-session \
    --context-dir /tmp/my-contexts
```

**Actual Output:**
```
I'll help you with your Python project. What would you like to know?
```

```bash
# Second call — continues the same context
$ agents actor run local/demo-assistant \
    "What are best practices for error handling?" \
    --config my-assistant.yaml \
    --context my-session \
    --context-dir /tmp/my-contexts
```

**What's Happening:**
The `--context` flag names a persistent conversation context stored in
`--context-dir`. Each call appends the user message and assistant response
to the context. On subsequent calls, the full conversation history is loaded
and passed to the actor, enabling multi-turn conversations from the command
line.

---

### Step 7: Error Handling — Unknown Actor

```bash
$ agents actor run local/nonexistent-actor "Hello"
```

**Actual Output (stderr):**
```
Error: Actor 'local/nonexistent-actor' not found in registry and no --config provided.
```

**Exit code:** `2`

**What's Happening:**
When the actor name is not found in the registry and no `--config` is
provided, the command exits with code 2 and prints a clear error to stderr.
This makes it easy to detect failures in scripts:

```bash
agents actor run local/my-actor "Hello" || echo "Actor not found"
```

---

### Step 8: Attach Skills

Skills augment tool-bearing actors with additional capabilities:

```bash
$ agents actor run local/my-actor "List files in the current directory" \
    --config my-actor.yaml \
    --skill local/file-ops
```

Repeat `--skill` to attach multiple skills:

```bash
$ agents actor run local/my-actor "Analyze this codebase" \
    --config my-actor.yaml \
    --skill local/file-ops \
    --skill local/git-tools
```

**What's Happening:**
Skills are only attached to actors that have tools configured. The `--skill`
flag passes skill names to `ReactiveCleverAgentsApp`, which resolves and
attaches them before running the actor.

---

## Combining REPL and Actor Run

A common workflow:

1. **Explore** actors and config in the REPL:
   ```
   agents [default:default]> actor list
   agents [default:default]> actor show openai/gpt-4o
   ```

2. **Test** a quick prompt interactively:
   ```
   agents [default:default]> !agents actor run openai/gpt-4o "Hello"
   ```

3. **Script** the final command for automation:
   ```bash
   agents actor run openai/gpt-4o "Summarize this file" \
       --output summary.txt
   ```

---

## Key Takeaways

### REPL (`agents repl`)
- **No prefix needed**: type `version` instead of `agents version`
- **History**: readline history is saved to `~/.cleveragents/history`
- **Tab completion**: all commands and built-ins are tab-completable
- **`!!`**: repeats the last command
- **`!cmd`**: runs a shell command (30s timeout, dangerous patterns require confirmation)
- **`\`**: continues input on the next line
- **`/persona`**: create, list, set, pick, export, import, delete personas
- **`/session`**: create and switch between named sessions with independent personas
- **`@reference`**: fuzzy-expand file/actor/skill/tool references inline
- **`:exit` / `:quit` / Ctrl+D**: clean exit (saves history)

### Actor Run (`agents actor run`)
- **Two required args**: `NAME` (actor name) and `PROMPT` (text to send)
- **`--config`**: override registry with a direct YAML file path
- **`--output`**: write result to a file instead of stdout
- **`--temperature`**: override the actor's temperature setting
- **`--context`**: name a persistent conversation context
- **`--context-dir`**: directory to store context files
- **`--load-context`**: load a previously exported context JSON
- **`--skill`**: attach a skill (repeatable for multiple skills)
- **`--verbose`**: increase logging verbosity
- **Exit codes**: 0 = success, 1 = unsafe config, 2 = actor not found / config error, 3 = unexpected error

---

## Complete Interaction Log

<details>
<summary>Click to see the full verified REPL session</summary>

```
$ agents repl
CleverAgents REPL — type :help for commands, :exit to quit.

agents [default:default]> :help
CleverAgents Interactive REPL

Built-in commands
  :help          Show this help message
  :exit / :quit  Exit the REPL
  !!             Repeat the last command

Input modes
  @reference     Inline reference expansion and fuzzy matching
  /command       Slash command mode
  !shell cmd     Shell command passthrough
  Full-screen UI: run agents tui

Slash commands
  /persona
  /persona list
  /persona set
  /persona create
  /persona pick
  /persona delete
  /persona export
  /persona import
  /session list
  /session new
  /session switch

CLI commands
  version
  info
  diagnostics
  init
  project
  context
  plan
  actor
  action
  resource
  skill
  lsp
  cleanup
  config
  session
  tool
  validation
  auto-debug
  automation-profile
  invariant
  tell
  build
  apply
  context-load
  context-add
  tui

Type any CLI command without the leading 'agents' prefix.
Use \ at end of line for multi-line input.

agents [default:default]> version
╭── CLI Version ───╮
│ CleverAgents CLI │
│ Version: 1.0.0   │
│ Channel: stable  │
│ Python: 3.13.9   │
╰──────────────────╯
╭──────── Build ─────────╮
│ Build Date: 2026-04-07 │
│ Commit: d250e9e5       │
│ Schema: v3             │
│ Platform: linux-x86_64 │
╰────────────────────────╯
╭───── Dependencies ─────╮
│ langgraph: 1.1.6       │
│ langchain-core: 1.2.26 │
│ pydantic: 2.12.5       │
│ typer: 0.23.1          │
╰────────────────────────╯
OK Version reported

agents [default:default]> !!
version
╭── CLI Version ───╮
│ CleverAgents CLI │
│ Version: 1.0.0   │
│ Channel: stable  │
│ Python: 3.13.9   │
╰──────────────────╯
[... same version output ...]
OK Version reported

agents [default:default]> !echo Hello from shell mode
Hello from shell mode

agents [default:default]> /persona create dev --actor openai/gpt-4o
Created persona: dev

agents [default:default]> /persona list
Personas
 * default -> local/mock-default
   dev -> openai/gpt-4o

agents [default:default]> /persona set dev
Active persona: dev

agents [default:dev]> /session new work
Created session: work

agents [default:dev]> /session switch work
Switched session: work

agents [work:dev]> /session list
REPL Sessions
   default (persona=dev)
 * work (persona=dev)

agents [work:dev]> :exit
```
</details>

<details>
<summary>Click to see the full verified actor run session</summary>

```
$ agents actor run --help
 Usage: agents actor run [OPTIONS] NAME PROMPT
 Run the reactive network once with actor-first configs.
 [... full help output ...]

$ agents actor run openai/gpt-4o "Say hello"
Hello! I'm an AI assistant powered by GPT-4o. How can I help you today?

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml
The capital of France is Paris. It is a major European city and has been
the capital since the 10th century.

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml \
    --output answer.txt
Output written to answer.txt

$ agents actor run local/demo-assistant "Write a haiku about mountains" \
    --config my-assistant.yaml \
    --temperature 0.9
A haiku:
Silent mountain peak
Clouds drift through ancient valleys
Echoes fade to peace

$ agents actor run local/nonexistent-actor "Hello"
Error: Actor 'local/nonexistent-actor' not found in registry and no --config provided.
[exit code: 2]
```
</details>

---

## Try It Yourself

- **Start the REPL with no history**: `agents repl --no-history`
- **Start the REPL with a custom history file**: `agents repl --history-path /tmp/my-history`
- **Run a quick one-liner**: `agents actor run openai/gpt-4o "What is 2+2?"`
- **Save output to file**: `agents actor run openai/gpt-4o "Explain Python decorators" --output decorators.txt`
- **Multi-turn conversation**: use `--context my-chat --context-dir /tmp/chats` across multiple calls
- **Script it**: `result=$(agents actor run openai/gpt-4o "Summarize: $text") && echo "$result"`

## Related Examples

- [Managing AI Actors](actor-management-workflow.md) — full actor lifecycle (add, list, show, set-default, remove)
- [Mastering Output Format Flags](output-format-flags.md) — `--format json/yaml/plain/table`
- [Showcase Index](../index.md)

---
*This example was automatically generated and verified by the CleverAgents UAT system.*
*Feature area: REPL and interactive session | Test cycle: 1 | Generated: 2026-04-07*

---
**Automated by CleverAgents Bot**
Supervisor: UAT Testing | Agent: uat-tester