Skip to main content

​
Synopsis

operator agent [flags]

​
Description

operator agent starts the agent and connects you to it from your terminal. No gateway, no messaging channel — just direct access to the agent loop. There are two modes:
  • One-shot mode (with -m): send a single message, receive one response, and exit.
  • Interactive mode (without -m): start a persistent readline session. The agent remembers the conversation within the session. Type exit or quit, or press Ctrl+C to end the session.
In interactive mode, Operator uses chzyer/readline for line editing and command history. History is written to a temporary file ($TMPDIR/.operator_history) and is limited to 100 entries. If readline is unavailable, the agent falls back to a simple stdin reader. Session history is keyed by the --session flag. Two invocations with the same session key share the same conversation context.

​
Options

​
--message
string
Send a single message and exit (non-interactive mode). Shorthand: -m.
​
--session
string
default:"cli:default"
Session key used to scope conversation history. Use different session keys to maintain separate conversations. Shorthand: -s.
​
--model
string
Override the model for this invocation. Accepts the model_name short alias as defined in model_list in your config.json (e.g. claude-sonnet-4.6, gpt4). If not set, the model defined in agents.defaults.model_name is used.
​
--debug
boolean
default:"false"
Enable debug-level logging. Shorthand: -d.

​
Examples

Send a one-shot message: 
operator agent -m "What is the current date?"

🕸️ Today is Tuesday, 31 March 2026.
Start an interactive session: 
operator agent

🕸️ Interactive mode (Ctrl+C to exit)

🕸️ You: What files are in my workspace?
🕸️ Your workspace at ~/.operator/workspace contains:
   - AGENTS.md
   - IDENTITY.md
   - SOUL.md
   - USER.md
   - memory/
   - skills/

🕸️ You: Summarise AGENTS.md for me
🕸️ AGENTS.md describes the behavioural guidelines the agent follows...

🕸️ You: exit
Goodbye!
Use a named session to continue a previous conversation: 
operator agent --session work:planning -m "What did we discuss earlier about the project?"
Override the model for a single run: 
operator agent --model claude-sonnet-4.6 -m "Explain monads in one paragraph."
Enable debug logging: 
operator agent --debug -m "List installed tools"

🔍 Debug mode enabled
🕸️ The following tools are loaded: exec, read_file, write_file, web_search, cron, ...
Use with pipes (non-interactive): 
echo "Summarise this: $(cat README.md)" | xargs -I{} operator agent -m "{}"

​
Session keys

Session keys follow a <scope>:<name> convention, though any string is valid. The default is cli:default. Separate conversations can be maintained in parallel by using different keys: 
# Work assistant
operator agent --session work:default -m "Draft a standup update"

# Personal assistant
operator agent --session personal:default -m "What should I cook tonight?"
Session history is held in memory during the process lifetime. It is not persisted to disk between operator agent invocations. For persistent memory across sessions, the agent uses the memory tools to write to the workspace.

Build docs developers (and LLMs) love

Get started for freeTalk to us