CLI Reference

atomic-agent [command] [flags]

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

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

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]

At the default approval level (1), dangerous tools pause and prompt you over stdin. Approval is serial: a long-running approval blocks later ones in the same turn.

The approval prompt

The stdin prompt takes four answers, not two:

s and a only appear when the request is grantable. Writes to the agent’s own trust config (config.json, .env) are never grantable — those requests only ever offer y/N, because a silent write there could raise the ladder for the next boot.

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]

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]

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.

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]
                         [--notify telegram]
                         [--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]

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]

Skill — manage skills

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

atomic-agent skill install <path|owner/repo[/path]|@owner/slug> [--force] [--acknowledge-risk]
atomic-agent skill uninstall <name>
atomic-agent skill list
atomic-agent skill show <name>
atomic-agent skill enable <name>
atomic-agent skill disable <name>
atomic-agent skill browse [--source owner/repo]
atomic-agent skill search <query>
atomic-agent skill tap list | add <owner/repo> | remove <owner/repo>

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

Config — read & write config

Read or replace the user config file at <stateDir>/config.json.

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

• get prints the whole config file as JSON.
• set '<json>' replaces the entire file with the JSON you pass.

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.

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

atomic-agent import openclaw [--source DIR] [--agent NAME]
                             [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

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).

Task queue

The task queue is configured only through environment variables — there is no tasks block in config.json.

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

These live in <stateDir>/config.json and back the flags above. Edit them with atomic-agent config set (which replaces the whole file — see above) or the TUI.

The approval ladder

agent.approvalLevel replaced the old boolean agent.approvalRequired in schema v37. It is a 1–5 ladder and each level is cumulative — it stops asking about everything the level below it stopped asking about.

Hardline shell-guard rules sit outside the ladder and block at every level.