CLI reference
-- to end option parsing when positional prompt text begins with -, --, or @. Every argument after the terminator is treated as literal message text rather than an option or file argument:
Package Commands
atomic update can update the Atomic CLI installation. To uninstall Atomic itself, see Quickstart. atomic config and project package commands accept --approve/--no-approve to trust or ignore project-local settings for one command. atomic update never prompts for project trust.
See Atomic Packages for package sources and security notes.
Custom update command
If a wrapper or another package manager provides Atomic, setATOMIC_SELF_UPDATE_COMMAND so atomic update runs its update command:
atomic update runs it only when a newer release exists, replacing {packageName}, {version}, and {installSpec} ({packageName}@{version}) with that release. It replaces install-method detection, so it also works for installs Atomic cannot update itself. The value is split on spaces; PI_SELF_UPDATE_COMMAND is accepted as an alias. For arguments with spaces, use the selfUpdateCommand setting in ~/.atomic/agent/settings.json instead, an argv array such as ["nix", "profile", "upgrade", "atomic"]. Project settings are ignored for it.
Afterwards Atomic reports the version it finds installed: the one on disk, or what atomic --version prints on PATH. A wrapper that installs each version into a new directory therefore still reports success, and a command that exits 0 without installing the new version prints a warning instead.
Credential Commands
atomic auth check verifies the effective credential a provider or model would use before a session starts. It requires at least one of --provider or --model, prints ready, not_ready, or invalid to stdout, and exits 0, 1, or 2 for those states. --json adds the resolved provider when one is found, credential kind, and any reason. By default, a check never emits credential material.
--credentials is an explicit export opt-in. It requires --provider or an exact --model target; a fuzzy model match on an otherwise-ready provider is refused as invalid (exit 2) rather than exporting a credential for a provider you did not name. If that provider is not ready, the check remains not_ready (exit 1). On a ready check, plain stdout becomes the resolved credential alone and JSON adds it only in the credentials field. A non-ready raw export leaves stdout empty and reports its status on stderr; a JSON export returns the status object without a credential. Credential writes can also exit 8 (nothing written) or 9 (only a fragment written). Treat the stream like print-api-key or print-bearer-token output.
Checks refresh expired OAuth credentials by default, using Atomic’s normal locked auth.json update path. Pass --no-refresh to read credentials without creating, locking, or mutating auth.json; this is useful when a probe must not change stored auth state. It still reads Atomic’s primary and legacy credential paths and resolves configured API-key values, including !command, through the normal provider configuration. In this read-only mode, malformed auth.json is invalid (exit 2) rather than an unavailable credential. An OAuth credential export requires at least 30 minutes of life: the normal path can refresh it, while --no-refresh refuses a shorter-lived token.
The credential commands print one configured credential for an external client — a proxy, a script, or another tool that needs the same key Atomic already holds. The credential goes to stdout and nothing else; warnings, provider selection, refresh notices, and help all go to stderr, so KEY=$(atomic auth print-api-key --model gpt-5.5) can never capture a diagnostic.
--model is required for the two print-* exports. An exporting auth check needs --provider or an exact --model target. When several configured providers offer a model, pass --provider to choose one. The two print-* subcommands accept only --provider and --model: any other flag — including --export, --session-dir, --print, and --help — is a usage error rather than a flag this path happens to ignore.
atomic auth on its own — and atomic auth help, --help, or -h — prints this usage on stderr and exits 0. atomic auth check --help (or -h) does the same until a -- terminator; after it, the flag is not help. Any other subcommand exits 1 and names all three valid commands. Help never uses stdout, so raw credential export stdout is a credential or empty; a JSON export writes an object that carries a credential only in its credentials field.
print-bearer-token works only on OAuth providers and print-api-key only on API-key providers; asking for the wrong kind is an error rather than a silent fallback. A bearer token with less than --min-expiry remaining (default 30m, accepting ms, s, m, or h) is refreshed first. Both --min-expiry 30m and --min-expiry=30m are accepted. --min-expiry with print-api-key is a usage error — even after a -- terminator — because an API key has no expiry. A failed refresh leaves your stored credential untouched.
Credential-export exits (print-api-key, print-bearer-token, and the --credentials write itself):
Auth-check exits:
Exit
5 is reported only for a refresh that itself failed, which happens before anything is persisted; that is the only exit that promises your stored credential is untouched. Any other OAuth failure exits 7 and makes no such promise.
Raw credential exports leave stdout empty on non-zero exits, except exit 9. That exit means the stream failed after writing part of the credential. Discard the fragment; those bytes cannot be recalled.
Once the complete credential reaches stdout, the command has succeeded. If the stream then fails to drain, for example because a reader closed the pipe, Atomic reports it on stderr and keeps exit code 0.
auth check --credentials --json may instead write a credential-free JSON status object on a non-zero check result. See Security before wiring this into a script.
Storage and Intercom Commands
atomic storage status reports, for sessions, workflow runs, and Intercom, the selected storage, where the selection comes from (an environment variable, project or global settings, or the default) and the outranked selections, whether the adapter loads, and whether the database answers a SELECT 1. It also shows the running Intercom broker: whether it uses the current selection, its multi-node routing state, and the other brokers live in the shared database. It creates and changes nothing, and exits 1 when a selection is invalid, an adapter cannot load, or a database does not answer.
atomic storage join checks the token and the connection with @bastani/atomic-storage-libsql, stores the trimmed token in a new storage-token.<id> file in the agent directory with mode 600, writes only the global storage setting, and lists the environment variables and settings that override it. Previous token files are never overwritten; a settings-write failure removes only the new token. It creates no tables. --token-file is required except for absolute file: URLs; relative file URLs and URLs that contain the token itself (a user name, a password, or an authToken parameter) are refused. When the package is not installed, it prints the install command. See Storage.
atomic intercom restart asks the broker to shut down (an older broker gets SIGTERM), waits for it to exit, and then for a reconnecting session to start a new broker, whose state it prints. Without connected sessions, the next session that uses Intercom starts one.
See Joining a machine to a shared database and Running Intercom across machines.
Modes
Interactive sessions use fullscreen, with a scrolling transcript above the docked editor and status area. Wheel and trackpad input goes to a focused workflow graph or stage chat first, then the transcript when not consumed. Scrolling, scrollbar dragging, and selection remain available outside overlays.
Adjust Fullscreen wheel scroll lines in
/settings, or set fullscreenWheelScrollLines to "auto" or a number from 1 to 100. This also applies to fullscreen tool detail and chat views.
Selection copies automatically unless fullscreenCopyOnSelect is false. Ctrl+X returns tool detail or stage chat to the graph, returns the graph to main chat, or clears a scoped-model selection. It does not copy; /copy copies the last assistant message.
On exit, fullscreenExitOutput: "transcript" prints the final transcript and resume hint. "resume-hint" restores the previous screen and prints only the hint. See Settings and Terminal setup.
In print mode, Atomic also reads piped stdin and merges it into the initial prompt:
@file) starts without stdin. If input arrives after that, Atomic warns that it was ignored. A run with no prompt argument keeps waiting for stdin, and says so on stderr. Set ATOMIC_STDIN_TIMEOUT_MS to change the wait, or to 0 to always wait for the end of piped input.
When a print-mode turn correctly finishes by calling an opt-in terminating structured-output tool created with createStructuredOutputTool (for example from an extension, SDK caller, or workflow item with a schema), Atomic ends after that tool result without an extra follow-up assistant turn. Print-mode stdout contains the terminating structured JSON payload, so atomic -p remains script-friendly while the same value is also available through the SDK capture sink, tool details, a configured file sink, or workflow result.structured. This also works for custom factory names such as final_decision. Non-terminating or unrelated tool results are not printed as the final response.
Model Options
A model named with
--model runs as named. It falls back only to the models --fallback-models names, never to the fallbackModels setting, user or project. In an interactive session this holds for the whole process: after you switch models with /model or Ctrl+P, and in sessions you start with /new or /resume, the session still uses only --fallback-models. Start Atomic without --model to use the setting. Child sessions that run on the main session’s model, such as a subagent that names no model, inherit the same chain. In print mode, a fallback prints Model fallback: <model> failed, continuing on <fallback>: <reason> to stderr. If the run’s answer came from the fallback, it ends with Model: ran on <fallback>, not the requested <model>. A run that fails prints Model <model> failed: <reason>.
Session Options
See Choosing a store for precedence, prefix rules, and conflicts.
Tool Options
Default built-in tools:
read, bash, kill, edit, write, find, search, ask_user_question, todo, plus powershell on native Windows when a PowerShell executable is available. ls remains available but is not a default. defaultTools selects initial coding tools without narrowing extension/custom tools. --tools selects an explicit allowlist; --exclude-tools subtracts from it. --no-builtin-tools suppresses coding defaults when no allowlist is given. The bundled Intercom extension remains loaded with --no-extensions, but its tool follows the allowlist, exclusions, and --no-tools like other extension tools.
To add opt-in codemode or tool search alongside defaults, use atomic --tools +codemode,+tool_search for one invocation, or "defaultTools": ["+codemode", "+tool_search"] in settings. atomic --tools +codemode,-write keeps the other defaults and disables write. Modifier entries take exact names, not * patterns, and cannot be mixed with plain allowlist entries. Use --exclude-tools for pattern exclusions. On /reload, modifiers apply to the reloaded defaultTools setting too, so tools removed with -name stay removed. Modifiers do not narrow extension/custom tools or filter MCP exposure; --no-tools still disables every tool.
MCP tools
--tools read,codemode keeps non-hidden MCP tools with codemode or deferred exposure callable from codemode scripts. MCP tools unmatched by the allowlist are not declared directly, regardless of exposure. Unmatched direct-exposure tools remain registered but inactive. Only an enabled tool_search can load unmatched tools with non-direct exposure.
An entry starting with mcp__ filters MCP tools too. For example, atomic --tools read,codemode,'mcp__docs__*' keeps only tools from the docs server. MCP resource tools also count as MCP tools. Exclusions apply to both server and resource tools. Use --no-mcp to disable built-in MCP connections and resources entirely.
Project Trust Options
Project trust gates
.atomic/legacy .pi project resources, project package settings, project-local context files, and .agents/skills discovered from the project tree. Saved trust decisions can be managed with /trust; see Security.
Resource Options
Combine
--no-* with explicit flags to load exactly what you need, ignoring settings. Example:
Other Options
File Arguments
Prefix files with@ to include them in the message:
Examples
Environment Variables
Every bash execution receives one execution-time snapshot of the active session. Foreground/background observation controls how long the caller waits, not the command’s execution timeout. Omitted
wait uses the owner’s policy, normally yielding after 10 seconds; explicit background observation requires a supported task owner. Without one, foreground execution waits until completion. See Background tasks.
The snapshot is taken when the command executes, not when the tool is created, so resumed sessions, workflow stages, isolated sessions, model changes, and concurrent sessions cannot reuse stale metadata. Atomic preserves all unrelated inherited and caller-supplied environment variables; only the ten names above are cleared and overlaid. Factory-created bash tools expose the same metadata by default and can set
exposeSessionEnvironment: false to omit it.
PI_* aliases are also supported for app-specific ATOMIC_* variables for legacy compatibility. For example, Intercom honors PI_CODING_AGENT_DIR when ATOMIC_CODING_AGENT_DIR is unset and still reads legacy ~/.pi/agent/intercom/config.json when the Atomic config is absent. PI_CACHE_RETENTION is not one of those aliases and has no ATOMIC_* equivalent. Long retention is the default for main chat, workflow stages, and subagents where supported; use PI_CACHE_RETENTION=short atomic to opt back into shorter caching. See Prompt-cache retention for overrides and pricing tradeoffs. Intercom’s default broker starter works across Node-based installs, Bun source checkouts, and standalone Atomic binaries without requiring npx, tsx, or bun to be present on PATH; custom broker commands remain explicit opt-in overrides.