# Interactive REPL

The `agents repl` command starts an interactive read-eval-print loop that
lets you run any CleverAgents CLI command without the leading `agents`
prefix.

## Quick start

```bash
agents repl
```

Once inside the REPL you can type commands directly:

```
agents> plan list
agents> session create --actor openai/gpt-4
agents> config get log_level
```

## Built-in commands

| Command        | Description                        |
|----------------|------------------------------------|
| `:help`        | Show available commands             |
| `:exit`        | Exit the REPL (same as Ctrl+D)     |
| `:quit`        | Alias for `:exit`                  |
| `!!`           | Repeat the last command             |

## Command-line options

| Flag             | Default                          | Description                        |
|------------------|----------------------------------|------------------------------------|
| `--no-history`   | `False`                          | Disable history loading/saving     |
| `--history-path` | `~/.cleveragents/history`        | Custom history file location       |

## Features

### Tab-completion

Press **Tab** to complete top-level command names. All CLI commands and
built-in REPL commands are available as completion candidates.

### Command repetition

Type `!!` and press Enter to repeat the previous command. The repeated
command is printed before execution so you can see what ran.

### Multi-line input

End a line with `\` to continue on the next line. The REPL shows a `...`
continuation prompt. All lines are joined with a space before dispatch.

```
agents> plan create \
...   --name "My Plan" \
...   --project demo
```

### Prompt context

The prompt reflects the active project and plan when the environment
variables `CLEVERAGENTS_PROJECT` and `CLEVERAGENTS_PLAN` are set:

```
agents (myproject/active-plan)> plan status
```

### Signal handling

| Signal   | Behaviour                                 |
|----------|-------------------------------------------|
| Ctrl+C   | Cancels the current input; stays in REPL  |
| Ctrl+D   | Exits the REPL cleanly                    |

## History

By default the REPL persists command history to
`~/.cleveragents/history`. The file is created automatically on first
use. History survives across sessions and is limited to 10 000 entries.

### Privacy considerations

The history file is stored in the user's home directory with default
filesystem permissions. It may contain sensitive information such as
project names, plan names, and configuration values passed on the
command line. If this is a concern:

* Use `--no-history` to disable persistence entirely.
* Periodically delete or truncate `~/.cleveragents/history`.
* Ensure the directory permissions on `~/.cleveragents/` are
  restricted (e.g. `chmod 700`).

## Running the REPL smoke tests

```bash
nox -e unit_tests -- features/repl.feature
nox -e integration_tests  # includes robot/repl_smoke.robot
```