CLI Reference
The agentos CLI is the fastest way to configure,
run, inspect, and automate AgentOS.
Run:
agentos --help
agentos <command> --help
Main Commands
| Command | Purpose |
|---|---|
agentos init |
Initialize a workspace. |
agentos doctor |
Diagnose readiness and print recovery steps. |
agentos onboard |
Run or inspect first-run setup. |
agentos configure |
Reconfigure provider, router, channels, search, image generation, or memory embedding. |
agentos gateway |
Run and manage the gateway server. |
agentos chat |
Start interactive terminal chat. |
agentos agent |
Run a single automation-friendly agent turn. |
agentos sessions |
List, inspect, resume, abort, delete, or export sessions. |
agentos skills |
List, search, view, install, update, publish, and inspect skills. |
agentos memory |
Inspect and maintain memory. |
agentos channels |
Configure and inspect messaging channels. |
agentos providers |
Configure and inspect LLM providers. |
agentos search |
Configure and use web search. |
agentos sandbox |
Inspect or change default sandbox posture. |
agentos cron |
Manage scheduled AgentOS runs. |
agentos cost |
Inspect usage and estimated cost. |
agentos diagnostics |
Enable or disable runtime diagnostics logging. |
agentos replay |
Replay a recorded turn from the decision log. |
agentos migrate |
Import state from external agent runtimes. |
agentos models |
Inspect available models. |
agentos agents |
Manage durable agents. |
agentos mcp-server |
Run the AgentOS MCP server bridge. |
agentos dist |
Emit a reproducible workspace-state inventory. |
agentos reset |
Reset a session and flush memory synchronously. |
Run Surfaces
Web UI and gateway:
agentos gateway run
agentos gateway start --json
agentos gateway status
agentos gateway restart
agentos gateway stop
Terminal chat:
agentos chat
agentos chat --model gpt-5.4-mini
agentos chat --session <session-key>
agentos chat --standalone --workspace /path/to/project
One-shot automation:
agentos agent -m "Review the current directory"
agentos agent --json -m "Return a short machine-readable summary"
agentos agent --workspace /path/to/project --workspace-strict -m "Inspect this repo"
agentos agent --timeout 600 --max-iterations 30 -m "Run a bounded investigation"
Useful automation flags:
| Flag | Purpose |
|---|---|
--workspace |
Set the workspace root. |
--workspace-strict |
Restrict read-side file tools to the workspace. |
--workspace-lockdown
|
Contain writes to workspace or scratch directory. |
--scratch-dir |
Place temporary scripts/logs/candidate patches in a known directory. |
--timeout |
Set total agent wall-clock timeout. |
--max-iterations |
Bound the model/tool loop. |
--max-provider-retries
|
Bound transient provider retries. |
--length-capped-continuations
|
Bound automatic continuations after length-limited provider output. |
--thinking |
Override reasoning level. |
--permissions |
Select restricted, bypass, or full permission posture. |
--transcript-path |
Write a JSONL transcript for automation. |
--usage-path |
Write usage JSON. |
--session-db-path |
Persist session replay across invocations. |
Configuration Commands
Provider and router:
agentos onboard
agentos onboard status
agentos configure provider --provider openrouter --api-key-env OPENROUTER_API_KEY
agentos configure router --router recommended
agentos providers list
agentos providers configure openrouter
agentos providers status
Search:
agentos search list
agentos search configure duckduckgo
agentos search query "latest AgentOS release"
agentos configure search --search-provider duckduckgo
Channels:
agentos channels types
agentos channels describe telegram
agentos channels add telegram --name personal
agentos channels list
agentos channels status
agentos channels enable personal
agentos channels disable personal
agentos channels restart personal
agentos channels remove personal
Raw config:
agentos config get llm.provider
agentos config set gateway.port 18791
More detail:
Skills
agentos skills list
agentos skills search pdf
agentos skills view pdf-toolkit
agentos skills install <skill-name>
agentos skills update --all
agentos skills uninstall <skill-name>
Read:
Sessions and History
agentos sessions list
agentos sessions show <session-key>
agentos sessions resume <session-key>
agentos sessions abort <session-key>
agentos sessions export <session-key>
agentos sessions delete <session-key>
Read:
sessions.md
Memory
agentos memory status
agentos memory index
agentos memory list
agentos memory search "preference"
agentos memory show <path>
agentos memory dream
agentos memory flush-session <session-key>
agentos memory repair list
agentos memory raw-fallbacks list
Read:
features/memory.md
Durable Agents and Scheduling
agentos agents list
agentos agents add research --name Research --workspace /path/to/research
agentos agents delete research
agentos cron list
agentos cron add --every 1h --text "Summarize important updates" --name hourly-summary
agentos cron status <job-id>
agentos cron runs <job-id>
Read:
Cost, Diagnostics, and Replay
agentos cost
agentos diagnostics status
agentos diagnostics on
agentos diagnostics off
agentos replay --session <session-key> --turn <turn-id>
Use diagnostics and replay when you need to understand why a turn behaved a certain way.
Read:
MCP Server Bridge
agentos mcp-server run
agentos mcp-server run --gateway ws://localhost:18792/ws
Read:
mcp-server.md