cleveragents-core/docs/reference/repl.md

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

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

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