CLI · Terminal Reference

Agentao ships with a terminal-first interface — agentao in your shell, with slash commands, plan mode, sub-agents, memory, and replay all built in. This section documents that interface.

Install in 60 seconds

# Clone or install
uv sync                  # installs the project
cp .env.example .env     # paste your OPENAI_API_KEY

# Start the agent
uv run agentao
# or:  ./run.sh

You drop into a chat REPL. Type a normal sentence to talk to the agent. Type / followed by a command to control the session itself.

Coverage

• 1. Getting Started — /help, /clear, /new, /status, /exit · the minimum loop
• 2. Models & Providers — /model, /provider, /temperature, /thinking · switch LLMs, credentials and wire protocol at runtime
• 3. Permissions & Modes — /mode, tool-confirmation UI, /sandbox (macOS) · how the agent asks before doing dangerous things
• 4. Plan Mode — /plan workflow · read-only "think first, then commit" loop
• 5. Skills & Crystallize — /skills, /crystallize · activate skills and distill new ones from a session
• 6. Memory — /memory · what gets remembered, where it lives, how to inspect and clear it
• 7. Context & Status — /context, /compact, /status · token budget, compaction, session size
• 8. MCP / ACP / Plugins — /mcp, /acp, /plugins · attach external tool servers
• 9. Replay & Output — /replay, /copy, /markdown · record sessions, copy answers, render control
• 10. Configuration Reference — every config file the CLI reads, with paths and precedence
• 11. Sessions, Agents & Tasks — /sessions, /agent, /agents, /todos, /tools · restore and parallel workbench
• 12. Non-Interactive Entry Points — agentao init, -p, --resume, --acp, agentao doctor, agentao config validate · scripts, CI checks, and host integration
• 13. Long-Task Goals — /goal · drive one objective across many turns under a time / turn budget

How to read

Your situation	Recommended path
First time using agentao	1. Getting Started → 3. Permissions & Modes
Coming from another agent CLI (Claude Code, codex, gemini, etc.)	4. Plan Mode → 5. Skills & Crystallize
I want to plug in my company's tools	8. MCP / ACP / Plugins → Part 5.3 MCP
The agent ate my budget / context blew up	7. Context & Status → 6. Memory
I want to resume a session / inspect background agents	11. Sessions, Agents & Tasks
I'm shipping the CLI to my team	3. Permissions & Modes → 10. Configuration Reference
I want the agent to keep working on one task for many turns	13. Long-Task Goals → 4. Plan Mode
I want to call Agentao from scripts, CI, or an IDE	12. Non-Interactive Entry Points → Part 3 · ACP Protocol
I want to embed this engine into my own app	Part 1 · Getting Started (different audience — start there)

Mental model

The CLI is a thin REPL on top of the Agentao harness. Slash commands manipulate the session (history, model, mode, plan, memory). Plain messages are sent to the agent (tools, skills, MCP, ACP). Everything you see in the terminal — confirmation prompts, streaming events, tool results, memory recall — is exactly what an embedding host receives through the event stream.

If you understand the CLI, you already understand most of what an embedder builds against.

→ Start with 1. Getting Started →

---

Where this fits

The CLI is one consumer of the Agentao harness. The same harness can be embedded into your own application — see Part 2 · Python In-Process Embed or Part 3 · ACP Protocol. What you learn here about permissions, skills, MCP, memory and replay applies identically when you embed.

Authoritative help

The single source of truth for command syntax is /help inside the CLI, backed by agentao/cli/help_text.py. The pages here explain the why and how to use; if anything ever disagrees, trust /help.