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.
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.
For raw credential exports, stdout is empty on every non-zero exit but one. Once the credential reaches stdout the command has succeeded: if the stream then fails to drain — a reader that closed the pipe, for example — that is reported on stderr and the exit code stays 0, because a non-zero exit here would contradict the bytes the caller already holds. The exception is exit 9, which reports that only part of the credential was written before the stream failed; those bytes cannot be recalled, so stdout is not empty, and the output is a fragment to discard rather than a credential to use. 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.
Modes
Interactive sessions always use fullscreen: the transcript scrolls independently above a sticky dock containing the editor, status line, usage meter, extension widgets, and footer. Wheel and trackpad gestures go first to a focused workflow graph or stage chat overlay; events those overlays do not consume fall through to the alternate-screen viewport. Non-overlay focused components do not block pi-tui’s mouse path, so transcript scrolling, scrollbar interaction, and drag selection still work. Selection copies automatically by default; disable
fullscreenCopyOnSelect to highlight text without copying. Ctrl+X closes workflow tool detail to the graph, clears a scoped-model selection, returns stage chat to its graph, or returns a workflow graph to main chat. It does not copy. /copy always copies the last assistant message. The fullscreenExitOutput setting controls what exiting prints: "transcript" (the default) paints the final transcript plus a session resume hint on the main screen, while "resume-hint" restores the previous screen and prints only the resume hint. See Settings and Terminal setup.
In print mode, Atomic also reads piped stdin and merges it into the initial prompt:
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
Session Options
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. find.paths accepts directories, files, or glob paths such as *.ts and honors timeout; search accepts pattern, optional paths, i, gitignore, and skip for regex content-search pagination. Use --exclude-tools to disable one or more non-mandatory tools while leaving the rest available, for example atomic --exclude-tools ask_user_question. The defaultTools setting selects which built-in tools a session starts with; --tools replaces that default with a strict allowlist over non-mandatory built-in, custom, and extension tools; --no-builtin-tools removes only built-ins; --no-tools removes every tool except ordinary bundled intercom. ls remains available as an SDK compatibility tool but is not enabled by default.
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. Use PI_CACHE_RETENTION=long when configuring prompt-cache retention for providers/upstreams that support long-lived caches. 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.