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 upgrade`	Upgrade AgentOS and restart the managed gateway to match.
`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

agentos gateway status (and --json) reports both the installed CLI version (cliVersion) and the running gateway's version (gatewayVersion); when they differ it sets versionMismatch and prints a diagnostic advising a restart — the normal state right after a package upgrade with --no-restart, or after a manual upgrade.

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.

Upgrade

agentos upgrade is the primary upgrade path. It detects how AgentOS was installed, upgrades it, and — by default — restarts the managed gateway and verifies the running gateway reports the new version before declaring success (a "successful" upgrade that leaves the daemon on old code is the common upgrade regret).

agentos upgrade                 # upgrade, restart the gateway, verify
agentos upgrade --check         # is a newer release available? change nothing
agentos upgrade --dry-run       # print the exact command that would run
agentos upgrade --no-restart    # upgrade only; leave the gateway on OLD code
agentos upgrade --timeout 900   # bound the upgrade subprocess (default 600s)

Flag	Purpose
`--check`	Query PyPI for a newer release (5s timeout); offline prints `could not check (offline)`. Changes nothing.
`--dry-run`	Print the upgrade command that would run and whether the gateway would be restarted; touch nothing.
`--no-restart`	Upgrade the package but do not restart the gateway. Prints an unmissable warning that it still runs the old version; run `agentos gateway restart` yourself.
`--timeout`	Upgrade-subprocess timeout in seconds (default 600). On timeout the tool's process group is killed with recovery guidance — never a half-state.
`--config`	Target a specific config file for the gateway restart.
`--json`	Machine-readable output.

Per install method:

uv tool / pipx — delegated automatically (uv tool upgrade use-agent-os / pipx upgrade use-agent-os), resolving the tool to an absolute path over a hardened PATH.
pip / editable / source checkout — not faked: prints the exact manual command (e.g. python -m pip install --upgrade "use-agent-os") and exits with a distinct code.

Exit codes: 0 success (upgraded + verified, or --check/--dry-run); 3 this install method needs a manual command (printed); 1 the upgrade failed, timed out, or the post-restart version could not be verified.

Config migrations run at gateway start and write a timestamped backup before rewriting any file, so ~/.agentos/ config and data are safe across upgrades.

Version skew

Commands that talk to the gateway compare the CLI and gateway versions once per run:

Gateway older than the CLI (normal right after an upgrade, before a restart) — prints a warning on stderr, never blocks.
Gateway newer than the CLI (you downgraded the CLI, or drive a newer gateway from a stale environment) — refused, because a newer gateway may have written config with a newer schema. Fix by upgrading the CLI or restarting the gateway from this environment; override in an emergency with AGENTOS_ALLOW_VERSION_SKEW=1.

Update notifications

On gateway-connected commands the CLI checks PyPI at most once every 24h and, if a newer release exists, prints a one-line notice on stderr. It is suppressed on non-interactive runs (no TTY) and in CI. Control it with:

updates.notify = false in agentos.toml (or the setup UI's Finish step) — turns the notice off entirely.
AGENTOS_NO_UPDATE_NOTICE=1 — silences it for a single run.

See configuration.md.

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:

features/skills.md

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

CLI Reference

Main Commands#

Run Surfaces#

Upgrade#

Version skew#

Update notifications#

Configuration Commands#

Skills#

Sessions and History#

Memory#

Durable Agents and Scheduling#

Cost, Diagnostics, and Replay#

MCP Server Bridge#

Main Commands

Run Surfaces

Upgrade

Version skew

Update notifications

Configuration Commands

Skills

Sessions and History

Memory

Durable Agents and Scheduling

Cost, Diagnostics, and Replay

MCP Server Bridge