CLI Reference

atomic-agent is the single command-line tool for running the agent, serving it over HTTP, scheduling background work, managing local models and skills, and inspecting what happened after the fact. This page lists every command and every flag.

If you just want to start chatting, run atomic-agent with no arguments — it opens the terminal UI.

Developer Preview

Atomic Agent is a Developer Preview. Command names, flags, and config keys still move between releases. Pin a release if you depend on the exact surface below.

At a glance

atomic-agent [command] [flags]

There are 10 top-level commands. Running atomic-agent with no command opens the TUI.

Command	What it does
run	Interactive chat loop on stdin/stdout
tui	Full terminal UI (default when no command is given)
serve	Start the OpenAI-compatible HTTP server
task	Manage the durable task queue (schedule, list, run)
trace	Inspect, export, and replay recorded sessions
skill	Install, list, and toggle skills
models	Manage local llama.cpp models and GPU devices
config	Read or write config.json
repl	Minimal debug REPL
import	Migrate sessions and tasks from Hermes or OpenClaw

Exit codes: 0 success · 1 runtime or logic error · 2 bad arguments.

flowchart TD
    A["atomic-agent [command]"] --> B{command}
    B -->|none| TUI["tui"]
    B -->|run| RUN["interactive chat loop"]
    B -->|serve| SRV["HTTP server + approval bus"]
    B -->|task| TSK["TaskStore / TaskRunner"]
    B -->|trace| TRC["trace files (NDJSON)"]
    B -->|skill| SK["skill install / toggle"]
    B -->|models| MD["managed llama.cpp daemon"]
    B -->|config| CF["config.json"]
    B -->|import| IM["Hermes / OpenClaw migration"]
    RUN --> RT["runtime.runTurn"]
    SRV --> RT
    TSK --> RT

Commands

Run — interactive chat

Starts the agent in a plain stdin/stdout chat loop. Type a message, press Enter, and the agent runs a turn and prints its reply. Diagnostics go to stderr; the assistant’s reply goes to stdout.

atomic-agent run [--cwd DIR] [--max-steps N] [--no-approval]

Flag	Default	Description
--cwd DIR	current directory	Working directory the agent resolves relative paths against and scopes the session to.
--max-steps N	config.agent.maxSteps (25)	Maximum LLM steps per turn before the loop stops with max_steps.
--no-approval	off	Auto-approve every dangerous tool (shell, file writes, HTTP, etc.). See the caution below.

When approval is required (the default), dangerous tools pause and prompt you over stdin to allow or deny. Approval is serial: a long-running approval blocks later ones in the same turn.

Caution

--no-approval bypasses the approval gate entirely — shell commands, filesystem writes, and HTTP requests run with no confirmation. The onApprovalRequest callback never fires, so you also lose visibility into what the agent did. Use it for trusted automation only.

Note

Assistant replies are collapsed to a single line (newlines become spaces) so line-synced eval harnesses stay aligned. The full multi-line text is preserved in the trace NDJSON — use atomic-agent trace show to read it.

TUI — terminal UI

Launches the full React/Ink terminal interface: chat plus tabs for tasks, skills, memory, MCP, providers, local models, and Telegram. This is what runs when you type atomic-agent with no command.

atomic-agent tui [--cwd DIR] [--max-steps N] [--no-approval] [--skip-llama-setup]

Flag	Default	Description
--cwd / --working-dir DIR	current directory	Working directory for the session.
--max-steps N	config.agent.maxSteps (25)	Max LLM steps per turn.
--no-approval	off	Auto-approve dangerous tools. In the TUI, approvals otherwise appear as a y/n modal.
--skip-llama-setup	off	Skip the first-run model setup wizard. Also settable via ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP=1.

Inside the TUI, slash commands drive everything: /help, /new, /clear, /abort, /quit, /theme, plus panel switches like /tasks, /skills, /memory, /mcp, /llm, /models, /telegram, and /import. Sessions are created lazily on your first message, so opening the TUI just to glance at settings does not litter the session store.

Serve — HTTP server

Starts a Node HTTP server exposing an OpenAI-compatible chat API plus Atomic Agent management endpoints. Listens until SIGINT (Ctrl-C).

atomic-agent serve [--host H] [--port P] [--cwd DIR] [--api-key K] [--no-approval]

Flag	Default	Description
--host H	127.0.0.1	Address to bind.
--port P	8787	Port to listen on.
--cwd DIR	current directory	Working directory for sessions.
--api-key K	ATOMIC_AGENT_API_KEY env var	Bearer token required on authenticated routes. If both are omitted, auth is disabled.
--no-approval	off	Auto-approve dangerous tools for all requests.

Authenticated routes expect an Authorization: Bearer <token> header. Two routes are intentionally public so OpenAI SDKs can probe them before sending a key: GET /health and GET /v1/models.

HTTP endpoints exposed by serve

Method & path	Purpose
POST /v1/chat/completions	OpenAI-compatible chat, streaming or sync.
POST /v1/chat/completions/{id}/cancel	Abort a streaming completion by id.
GET /v1/models	Model catalog (public, single atomic-agent entry).
GET /health	Liveness probe (public).
GET /api/capabilities	Runtime wiring summary.
GET|PATCH /api/config	Read or merge-write user config.
GET /api/skills, GET /api/skills/{name}	List / inspect skills.
POST /api/skills/install, /api/skills/uninstall	Manage skills.
GET /api/sessions, GET|DELETE /api/sessions/{id}	List / fetch / delete sessions.
POST /api/approval/resolve	Resolve a pending approval.
GET /api/events	SSE stream of approval requests (replays pending on connect).
POST|GET /api/tasks, GET|DELETE /api/tasks/{id}	Task CRUD.
POST /api/tasks/{id}/run, POST /api/tasks/drain	Trigger task execution.
POST /api/webhooks/{name}	Webhook ingress, materialized as a task.

Custom headers: X-Atomic-Session-Id (request/response) pins the session; X-Atomic-Completion-Id is returned for streaming; X-Atomic-Extensions opts into named SSE events (e.g. tool_progress) instead of the strict OpenAI subset; X-Webhook-Secret authenticates webhook posts.

Task — durable task queue

Schedule deferred or recurring agent turns. Tasks persist to SQLite and survive restarts. Reads (list, show) use the task store directly; create for recurring schedules and run boot the full runtime.

atomic-agent task list   [--session ID] [--status CSV] [--limit N]
atomic-agent task show   <id>
atomic-agent task create [--session ID] --message TEXT
                         [--at MS | --cron EXPR | --every SEC] [--tz IANA]
                         [--max-attempts N] [--max-steps N]
atomic-agent task cancel <id>
atomic-agent task run    <id> | --all-pending [--session ID]
atomic-agent task tick   [--limit N]

Subcommand	Notes
list	Filter by --session, comma-separated --status, and --limit.
show <id>	Print one task record.
create	--message is required. Pick at most one schedule: --at (epoch ms one-shot), --cron (cron expression), or --every (interval in seconds). --tz sets the IANA timezone for cron.
cancel <id>	Idempotent cancel.
run <id> / --all-pending	Execute now, applying retry backoff between attempts.
tick [--limit N]	One-shot drain of all due tasks, then exit. Good for cron-style ops.

Note

One-shot tasks (--at or no schedule) run through the bare TaskStore and get a session lazily. Recurring tasks (--cron/--every) must boot the full runtime so they can allocate one persistent session reused across every firing.

Caution

task tick is fire-and-forget: it drains what is due right now but does not persist updated scheduled_for values. It is for manual ops, not continuous autonomy — for that, leave tasks.schedulerEnabled on so the long-lived scheduler runs.

Trace — inspect & replay sessions

Traces are append-only NDJSON files, one per session, capturing turns, steps, prompts, LLM completions, and tool calls. The trace command reads and replays them.

atomic-agent trace list   [--limit N]
atomic-agent trace show    <sessionId> [--step N] [--raw]
atomic-agent trace export  <sessionId> [--format ndjson|json]
atomic-agent trace replay  <sessionId> [--step N]

Subcommand	Notes
list	Recent trace summaries.
show <sessionId>	Human-readable chronology. --step N isolates one step; --raw prints unformatted lines.
export <sessionId>	Dump as ndjson (default) or json.
replay <sessionId>	Rebuild the stable prefix with current tools/skills/capabilities and compare hashes to detect prompt drift. --step N isolates a step. Exits 0 if no drift, 2 if drift is detected.

Note

Tracing is off by default in production. NDJSON lines are best-effort — malformed lines are silently skipped, so treat traces as diagnostics, not authoritative state. They are also unredacted (prompts and user messages verbatim); treat trace files as confidential.

Skill — manage skills

Skills are folders (a SKILL.md plus optional scripts) that extend the agent with reusable playbooks.

atomic-agent skill install <path> [--force]
atomic-agent skill uninstall <name>
atomic-agent skill list
atomic-agent skill show <name>
atomic-agent skill enable <name>
atomic-agent skill disable <name>

Subcommand	Notes
install <path>	Validate and copy a skill into the global skills root. --force overwrites an existing skill of the same name.
uninstall <name>	Remove a global skill.
list	Show all skills with enabled/disabled state and source.
show <name>	Print the SKILL.md body.
enable / disable <name>	Toggle visibility by mutating skills.disabled in config.json. Disabled skills stay on disk but are invisible to the model.

Tip

Project-local skills in ./.atomic-agent/skills/ shadow global ones of the same name. There is no merge or version comparison — the project version wins.

Models — local llama.cpp models

Manage the managed-mode local inference daemon: download backends and GGUF models, start/stop the server, and pick GPU devices. Most subcommands require config.localModels.mode = "managed".

atomic-agent models list | status | devices
atomic-agent models pull <id> | use <id> | remove <id>
atomic-agent models start | stop | update
atomic-agent models use-device <auto|cpu|Vulkan0>
atomic-agent models list-embeddings
atomic-agent models pull-embedding <id>
atomic-agent models use-embedding <id> | --disable

Group	Subcommands
Chat models	list, pull <id>, use <id>, remove <id>, status, update
Daemon	start, stop
GPU	devices, use-device <auto|cpu|Vulkan0>
Embeddings	list-embeddings, pull-embedding <id>, use-embedding <id> / --disable

Note

The chat daemon is primary — if it fails to start, that is fatal. The embedding daemon is optional: if it fails, chat still runs and memory recall falls back to FTS5-only (no embedding cosine re-rank). models subcommands are unavailable in external mode, where you point at a llama-server you run yourself.

Config — read & write config

Read or merge-write the user config file at <stateDir>/config.json.

atomic-agent config get
atomic-agent config set '<json>'

• get prints the current resolved user config.
• set '<json>' merges a JSON fragment into the file.

Caution

The runtime freezes config at bootstrap. Editing config.json (by hand or via config set) does not affect an already-running process — the in-memory cache is only refreshed by a restart or an explicit reload (the TUI panels and HTTP PATCH /api/config do this for you).

REPL — debug REPL

atomic-agent repl

A minimal scaffold REPL for debugging. Not a substitute for run or tui.

Import — migrate from Hermes / OpenClaw

Migrate conversations and scheduled tasks from a legacy agent into Atomic Agent. Imported sessions are prefixed (hermes: / openclaw:) so they never collide with native ones.

Hermes

atomic-agent import hermes [--source DIR] [--preset default|full]
                           [--include a,b] [--exclude a,b]
                           [--migrate-secrets] [--limit N]
                           [--overwrite] [--dry-run] [--yes]

• --source defaults to ~/.hermes (or HERMES_STATE_DIR).
• --preset selects what to import (default = sessions + cron). --include / --exclude adjust it.
• --migrate-secrets is the only way to copy secrets, and is limited to an allowlist (OPENROUTER_API_KEY, AIMLAPI_API_KEY). Secrets are never part of a preset.

OpenClaw

atomic-agent import openclaw [--source DIR] [--agent NAME]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

• --source defaults to ~/.openclaw (or OPENCLAW_STATE_DIR).
• --agent picks which agent’s sessions to import (default main).

Flag	Description
--limit N	Cap the number of sessions processed (-1 = no limit).
--overwrite	Overwrite a differing destination instead of flagging it as a conflict.
--dry-run	Preview only — reconciliation runs but nothing is written.
--yes	Skip the interactive confirmation.

Tip

Import is idempotent on the source. Conflicts are detected structurally (the full transcript, not just the id), so re-running a non---overwrite import safely skips identical items and reports duplicates rather than corrupting state.

Environment variables

The CLI reads these at bootstrap. They override the config file for operational and bootstrap values (the file wins for user-facing settings like model and log level).

Variable	Purpose
ATOMIC_AGENT_STATE_DIR	Root for state: config.json, traces, tasks.sqlite, memory, skills. Defaults to ~/.atomic-agent.
ATOMIC_AGENT_LLAMA_URL	Connection string for an external llama-server.
ATOMIC_AGENT_LLAMA_API_KEY	Bearer token for llama-server (optional).
ATOMIC_AGENT_LLAMA_MAX_TOKENS	Max new tokens per completion (default 4096, clamped 64–131072).
ATOMIC_AGENT_API_KEY	Bearer token for the serve HTTP API (fallback when --api-key is omitted).
ATOMIC_AGENT_RG_PATH	Override the bundled ripgrep binary path.
ATOMIC_AGENT_BROWSER_CHANNEL	chrome | msedge | chromium (default chrome).
ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH	Explicit Chromium binary path (overrides auto-detect).
ATOMIC_AGENT_BROWSER_HEADLESS	1 for headless mode (default 0).
ATOMIC_AGENT_BROWSER_NO_SANDBOX	1 to pass --no-sandbox (containers/CI only).
ATOMIC_AGENT_BROWSER_CDP_URL	Attach to an existing browser via Chrome DevTools Protocol.
ATOMIC_AGENT_DEBUG_ARGV	1 logs process.argv to stderr.

There are many more ATOMIC_AGENT_* tuning vars for the agent loop, tasks, and memory — see the Configuration reference for the full list.

Common config keys

These live in <stateDir>/config.json and back the flags above. Edit them with atomic-agent config set or the TUI.

Key	Default	Description
localModels.mode	managed	managed runs the daemon; external expects a running llama-server.
localModels.url	—	HTTP URL for the llama-server API.
localModels.managed.modelId	—	Active model id in managed mode.
agent.maxSteps	25	Default max steps per turn (overridden by --max-steps).
agent.tokenBudget	3000	Max prompt tokens per turn.
agent.toolTimeoutMs	60000	Tool execution timeout.
agent.approvalRequired	true	Enable approval prompts (inverse of --no-approval).
tasks.enabled	true	Master switch for the task queue.
tasks.schedulerEnabled	true	Run the long-lived background scheduler.
tasks.maxAttempts	3	Default retry budget per task.
log.level	info	debug | info | warn | error.

Where to go next

Configuration

The full config.json schema, every environment variable, and precedence rules.

HTTP API

Request/response shapes for serve, including streaming chat completions and the approval SSE stream.

Tasks & scheduling

Schedule syntax (--at / --cron / --every), retry behavior, and session binding.

Skills

The SKILL.md format, script allowlisting, and the approval gate for skill.run_script.