CLI reference

Every command and flag of the atrium CLI.

The atrium CLI is installed at ~/.atrium/bin/atrium and its path is exported as ATRIUM_CLI_PATH in every pane. Add ~/.atrium/bin to your $PATH to call atrium from outside atrium panes too.

Most commands talk to the running app over an IPC socket. A few (marked headless) work without the app running.

A naming note. The CLI predates the v0.195.0 vocabulary change and keeps the old symbols. Throughout this reference, workspace means what the UI calls a project (the directory-bound unit), collection means what the UI calls a workspace (the switchable group), and tab means room. That applies to command names, --workspace, and $ATRIUM_WORKSPACE_ID alike. See Naming.

Global flags

--json — output JSON instead of human-readable tables.
--channel stable|beta|dev — override the auto-detected channel (based on binary name).

Positional shorthand

Bare paths open in a new editor pane.

atrium path/to/file.ts

pane

Manage terminal, editor, browser, and other pane types.

List every pane with type, adapter, workspace, and room.

atrium pane list [--filter COLUMN=VALUE]

Read a pane's visible scrollback (rendered — what the user sees, not raw escape sequences).

atrium pane read <id> [--lines N] [--offset M]

Write text to the pane's PTY stdin.

atrium pane write <id> --text "pnpm build"

Control a pane.

atrium pane focus  <id>
atrium pane rename <id> --name "build server"
atrium pane resize <id> --width 120 --height 40
atrium pane close  <id>

Create a new pane. Without --split, the pane opens in a new room. With --split <pane-id>, the new pane attaches to the given pane in the position chosen by --direction.

atrium pane create \
    --type terminal|browser|git-changes|notepad \
    [--cwd <dir>] [--url <url>] \
    [--adapter <name>] \
    [--dock left-top|left-bottom|right-top|right-bottom] \
    [--split <pane-id>] [--direction right|left|down|up|subtab] \
    [--focus] [--name <name>]

--type defaults to terminal. git-changes and notepad are sidebar-dockable tool surfaces — pair them with --dock <slot> to open them straight into a resident slot. Other specialized panes (search, tasks, browser subtabs) open via their own commands or shortcuts. --direction defaults to right; subtab joins the target pane's subtab group instead of splitting. horizontal and vertical are accepted as back-compat aliases for right and down. When --adapter is set, the adapter spawns automatically once the shell is ready, applying that adapter's Default launch profile.

Dock a pane into a sidebar slot as a resident, detach it, or toggle its scope (these require the app UI):

atrium pane dock   <id> left-bottom    # slot: left-top|left-bottom|right-top|right-bottom
atrium pane undock <id>                # back into the mosaic
atrium pane pin    <id>                # toggle workspace-scope ↔ global pin

workspace

Manage projects — the directory-bound unit. The CLI keeps the pre-v0.195.0 name; see Naming. For the grouping layer above projects, see collection.

atrium workspace list   [--no-worktrees] [--collection <ref>] [--filter COLUMN=VALUE]
atrium workspace create --name <name> --dir <path> [--focus]
atrium workspace switch <id>
atrium workspace delete <id>

workspace create --focus switches to the new project once it's ready. Without --focus, atrium creates it in the background and you stay where you are — useful for agent-driven setup scripts that should not steal focus.

--collection <ref> scopes the listing to one workspace; <ref> resolves by name, id, or unique id prefix.

collection

Manage workspaces — the switchable groups of projects. Mutations require the app UI to be running.

atrium collection list
atrium collection create <name>
atrium collection rename <ref> <new-name>
atrium collection remove <ref>
atrium collection switch <ref>
atrium collection move-workspace <project> <workspace>

remove never deletes anything — the workspace's projects fall back to the default workspace (default, shown as Main). switch activates the workspace's remembered project, or none when it's empty.

Worktrees inherit their parent project's workspace and cannot be moved independently; move-workspace rejects them. The read path resolves each worktree to its parent's workspace before reporting, so collection list and workspace list always agree on membership.

worktree

Create and manage git worktrees as child projects, straight from the shell. A worktree project gets its own room, branch checkout, and isolated state; agents launched inside it inherit that context. See Projects → Worktrees for the isolation model.

atrium worktree create --branch <name> \
                       [--from <workspace-id>] [--source new|existing] \
                       [--base <ref>] [--location <path>] [--focus]
atrium worktree list   [--from <workspace-id>] [--orphans] [--filter COLUMN=VALUE]
atrium worktree adopt  <path> [--from <workspace-id>] [--focus]
atrium worktree remove <id-or-path> [--force]
atrium worktree forget <workspace-id>
atrium worktree prune  [--from <workspace-id>] [--force]

create cuts a new worktree (and branch) off the parent project and registers it as a child project; adopt binds a worktree that already exists on disk. remove runs git worktree remove and forgets the project; forget drops only the atrium project entry, leaving the on-disk worktree untouched; prune bulk-removes orphaned worktree projects.

workspace-command

Control workspace background commands — a room's dev server, file watcher, or build, started from the sidebar and kept running across rooms. Scoped to the caller's workspace. start is idempotent: an already-running command reports "already running" instead of launching a second instance (the agent anti-footgun — your agent won't relaunch a server that's already up).

atrium workspace-command list [--include-terminals] [--filter COLUMN=VALUE]
atrium workspace-command status  <name>
atrium workspace-command start    <name>
atrium workspace-command stop     <name>
atrium workspace-command restart  <name>
atrium workspace-command logs     <name> [--tail <n>]
atrium workspace-command clear    <name>          # clear scrollback
atrium workspace-command create   <label> <command> [--id <id>] [--cwd <dir>]
atrium workspace-command edit     <id> [--label <l>] [--command <c>] [--cwd <dir>]
atrium workspace-command delete   <name>

Running commands also surface in the activity sidebar's Runs section with the same stop / restart / clear / open-in-room controls, and atrium tells your agents which commands are already running so they don't double-launch one.

note

Notes live next to the project on disk under ~/.atrium/workspaces/<id>/notes/ and surface in the Notepad pane. Every command resolves the workspace from the calling pane unless you pass --workspace.

List, search, and read.

atrium note list   [--workspace <id>] \
                   [--tag <tag>] [--type markdown|sketch|canvas|html] \
                   [--source user|agent] [--folder <p>] \
                   [--filter COLUMN=VALUE]
atrium note search <query> [--workspace <id>] [--limit N]
atrium note read   <id>   [--workspace <id>] [--svg | --png]

read --svg and --png render a sketch note to bytes on stdout — useful when an agent wants to drop a diagram into a PR description.

Create. --type defaults to markdown. For interactive notes pass the body via --spec (canvas, JSON) or --body (HTML); the value is either an inline string, - to read from stdin, or a file path. --send-framing is an optional template applied to user responses before dispatch back to the agent — variables {payload}, {noteId}, {noteTitle}, {actionId}. --open lands the new note in a notepad pane in the running app's current room.

atrium note new --title <title> \
                [--type markdown|sketch|canvas|html] \
                [--tags tag1,tag2] [--folder <path>] \
                [--source user|agent] [--workspace <id>] \
                [--spec <path|->] [--body <path|->] \
                [--send-framing <template>] \
                [--open]

Write, delete, open, history.

atrium note write   <id> [--content <text> | --from-file <path>] [--source user|agent]
atrium note delete  <id> --confirm
atrium note open    <id>                # requires app UI
atrium note history <id> [--limit N]

note open (and note new --open) dispatch atrium://commands/notepad.open under the hood; the rest of the surface works headlessly against the storage layer.

room

Rooms inside the active project.

atrium room list [--filter COLUMN=VALUE]
atrium room switch <id>
atrium room rename <id> <name>
atrium room close <id>
atrium room move-to-wing <id> <wing>   # wing id or name ("main" = default)

wing

Manage wings — room groups within the active project. A room belongs to exactly one wing; the tab bar shows only the active wing's rooms. Removing a wing moves its rooms to the default wing rather than closing them. All but list require the app UI.

atrium wing list
atrium wing create <name>
atrium wing rename <wing> <new-name>
atrium wing switch <wing>               # activates the wing's most-recent room
atrium wing remove <wing>

task

List tasks in a project; show one task.

atrium task list [--workspace <id>] [--filter COLUMN=VALUE]
atrium task show <id>

Create a task. Optional --agent / --skill / --profile flags bind a Skills & Agents context to the new card so the next launch ships the agent prompt + selected skills through SessionStart. --skill is repeatable; the value is provenance:name[=mode] (mode defaults to the registered default). --profile is a convenience for a named-profile slug; pass --agent to bind an inline { adapter, prompt } agent instead.

atrium task create --title <title> \
                   [--description <md>] \
                   [--status <status-id>] \
                   [--priority critical|high|medium|low] \
                   [--size xs|s|m|l|xl] \
                   [--workspace <id>] [--assignee <user>] \
                   [--agent <ref>] [--skill <prov:name[=mode]>]... \
                   [--profile <slug>] \
                   --source <identity>

atrium task show <id> includes the agentRef, skillSelection, and profileSlug columns in its output (and JSON when --json is set), so an agent driving the CLI can introspect what context its bound card was launched with.

Update or delete.

atrium task update <id> [--title …] [--description …] [--status …] \
                        [--priority …] [--size …] [--workspace …] [--assignee …]
atrium task delete <id>

Add and list comments.

atrium task comment <id> --body <md> --source <identity> \
                         [--kind discussion|instruction|agent-update]
atrium task comments <id>

Attach or remove labels.

atrium task label-add    <id> --label-id <label-id> --source <identity>
atrium task label-remove <id> --label-id <label-id> --source <identity>

Bind a task to a pane and launch an agent against it. See Task dispatch.

atrium task launch <id> --pane-id <pane-id> \
                        [--adapter <name>] \
                        [--review-status <id>] [--completion-status <id>] \
                        [--merge-target <branch>] \
                        [--execution-mode current_branch] \
                        [--source <identity>]

Transition card state from inside an agent pane. Both default to reading $ATRIUM_TASK_RUN_ID from the environment.

atrium task set-in-review [--run-id <id>]
atrium task set-done      [--run-id <id>] [--source <identity>]

Claim a task from the calling pane — escape hatch for agents that weren't launched against a card explicitly. Creates a minimal run + segment so the pane is bound to the card; rejects when another run is already Active or Interrupted on the same card. Reads $ATRIUM_PANE_ID from the environment when --pane-id is omitted.

atrium task claim <task> [--pane-id <id>] [--source <identity>]

task repeat

Manage a card's repeat schedule.

atrium task repeat set       <card> [...]
atrium task repeat pause     <card>
atrium task repeat resume    <card>
atrium task repeat skip-next <card>
atrium task repeat stop      <card>

atrium task run-now <card>

skip-next skips exactly one fire and clears itself on consumption, so a schedule self-heals after one skip. run-now fires a repeatable card off-cadence, bypassing the overlap gate by intent — it mints a fresh background run through the same path the scheduler uses. The card must already carry a repeat config.

task status

Workspace-scoped statuses.

atrium task status list   [--filter COLUMN=VALUE]
atrium task status create --name <name> [--color #hex]
atrium task status update <id> [--name <name>] [--color #hex]
atrium task status delete <id>
atrium task status reorder <id> [<id> ...]

task label

Workspace-scoped labels.

atrium task label list   [--filter COLUMN=VALUE]
atrium task label create --name <name> [--color #hex]
atrium task label update <id> [--name <name>] [--color #hex]
atrium task label delete <id>
atrium task label reorder <id> [<id> ...]

run

Task runs (agent execution segments).

List and inspect.

atrium run list [--task <id>] [--workspace <id>] \
                [--state active|interrupted|completed|cancelled] \
                [--filter COLUMN=VALUE]
atrium run show <id>
atrium run segments <id>

Control state.

atrium run cancel   <id> [--source <identity>]
atrium run complete <id> [--source <identity>]
atrium run resume   <id> --pane-id <pane-id> [--source <identity>]

review

Read and act on diff-review comment threads — the same comments authored in the source control pane's diff stack. Every command operates on persisted threads, so you can list and reply from any shell with ATRIUM_CLI_PATH on $PATH.

List threads. Defaults to open threads in the repository at $PWD. Use --state resolved|all to widen the filter; --scope accepts working-tree, branch:<name>, task:<id>, or ad-hoc:<id>. Replies cluster under their parent thread in the rendered output.

atrium review list \
    [--repo <repo-id>] [--workspace <id>] \
    [--task <id>] [--agent <name>] [--author <name>] \
    [--state open|resolved|all] \
    [--scope <scope>] [--since <iso-8601>] \
    [--filter COLUMN=VALUE]

Reply to a thread, change its state, or move an orphaned comment that drifted off its line.

atrium review reply    --comment-id <id> --text <md>
atrium review resolve  --comment-id <id> [--note <text>]
atrium review reopen   --comment-id <id> [--note <text>]
atrium review close    --comment-id <id> [--note <text>]
atrium review re-anchor --comment-id <id> --line <n> \
                        [--hunk-id <sha>] [--context-hash <sha>]

Resolve and close are both terminal states; the difference is semantic and recorded in the body field. Re-anchor transitions a comment from orphaned back to open after attaching it to a new line. The dispatch verb that pushes a batch of comments to an agent is internal — invoked by the Send to agent flow in the source control pane, not advertised to agents themselves.

browser

Drive browser panes. All commands accept the pane ID as a short unambiguous prefix.

Open and navigate.

atrium browser open <url>
atrium browser navigate <id> <url>
atrium browser back    <id>
atrium browser forward <id>
atrium browser reload  <id>

Snapshot the accessibility tree. Interactive elements get short refs (e1, e2, …) for use with click/fill/type.

atrium browser snapshot <id> [--interactive true|false] [--selector <css>]

Interact with elements by ref or CSS selector.

atrium browser click  <id> <ref-or-selector> [--snapshot-after]
atrium browser fill   <id> <ref-or-selector> <text> [--snapshot-after]
atrium browser type   <id> <ref-or-selector> <text>
atrium browser press  <id> <key>
atrium browser select <id> <ref-or-selector> <value>
atrium browser scroll <id> [--dx N] [--dy N] [--selector <css>]

Evaluate JavaScript. Full program syntax (multi-statement, control flow); returns the last expression's value.

atrium browser eval <id> <expr>

Manage page-annotation comments. These operate on the persisted per-URL store, so no live pane is required; an open pane reconciles when the store changes.

atrium browser annotations list
atrium browser annotations resolve <id>
atrium browser annotations delete  <id>

Execute a raw Chrome DevTools Protocol method — the escape hatch for what eval can't reach: network inspection (Network.*), device/media emulation (Emulation.*), the full accessibility tree (Accessibility.getFullAXTree). One-shot request→response only; CDP event streaming is not exposed.

atrium browser cdp <id> <method> [--params <json>] [--timeout <ms>]

# Examples
atrium browser cdp <id> Page.getNavigationHistory
atrium browser cdp <id> Network.getAllCookies
atrium browser cdp <id> Emulation.setDeviceMetricsOverride \
    --params '{"width":390,"height":844,"deviceScaleFactor":3,"mobile":true}'

Wait for a condition. Polls every 100 ms until the condition is met or the timeout is reached.

atrium browser wait <id> [--selector <css>] [--text <text>] \
                         [--url-contains <substring>] \
                         [--load-state loading|interactive|complete] \
                         [--function <expr>] \
                         [--timeout <ms>]

Capture a screenshot.

atrium browser screenshot <id> [--path <file>] [--full-page]

Read DOM state.

atrium browser get <id> url|title|text|html|value|attr [<target>] [<attr>]
atrium browser is  <id> <ref-or-selector> visible|enabled|checked

Read buffered DevTools console messages. The buffer holds the 500 most recent entries per pane and is cleared when the pane closes.

atrium browser console <id> [--limit <n>] [--level verbose|debug|info|warn|error|fatal]

Levels follow Chromium's DevTools Protocol, not the JS call name: console.log and console.info both land as info, console.debug lands as verbose. Use --level verbose for console.debug output. Object arguments are stringified by the renderer before capture (so {foo: 1} lands as [object Object]); use browser eval if you need structured data round-tripped.

Manage cookies.

atrium browser cookies <id> [--domain <host>] [--name <name>] [--delete <name>]

agent

Discover, message, launch, dismiss, and wake agent panes, and manage the agent definitions that ++slug references. agent message routes via atrium://agents/{id}/message, which replaced the older mcp:// namespace.

atrium agent list    [--filter COLUMN=VALUE]
atrium agent message <id-or-prefix> <text> [--no-frame] [--submit-pause-ms <ms>]
atrium agent dismiss <id-or-prefix>
atrium agent wake    <id-or-prefix>

By default agent message wraps the text in a sender frame (see Agent messaging). Pass --no-frame to deliver a plain user-typed prompt with no [Message from … via atrium] envelope — what you want when the message is the user talking, not another agent.

agent dismiss kills the pane's PTY but preserves its session (the activity card shows a resume overlay); agent wake spawns a fresh adapter process from that persisted session.

agent list covers both foreground panes and background runs, de-duplicating panes that have been foregrounded. Prefix resolution spans both sets and errors on a collision rather than guessing.

Launch a new agent pane from a named agent definition. The <slug> is positional; its prompt and enabled skills bind to the new pane via the pane-binding route so SessionStart delivers them on the first turn. --adapter defaults to claude-code.

atrium agent launch <slug> \
                    [--adapter <name>] \
                    [--profile <launch-profile-slug>] \
                    [--model <alias-or-id>] [--effort <level>] \
                    [--launcher-opt KEY=VALUE]... \
                    [--surface chat|terminal] \
                    [--background] \
                    [--cwd <dir>] \
                    [--split <pane-id>] [--direction right|left|down|up|subtab] \
                    [--focus] [--name <name>]

atrium launch <slug> is a shorthand for the common foreground form and also accepts --adapter, --profile, and --surface. The named launch profile fixes the model, effort, permissions, CLI args, and environment used for that launch. --surface picks between an agent chat pane and a terminal pane; --background launches with no room tile at all (and warns that room-placement flags are ignored).

Background agents

atrium agent background <id-or-prefix>   # detach the pane from its room, keep running
atrium agent foreground <id-or-prefix>   # attach to a fresh room and focus
atrium agent resume     <id-or-prefix>   # re-spawn a dismissed background run in place
atrium agent stop       <id-or-prefix>   # kill and mark the run cancelled (terminal)

stop is not dismiss. dismiss is soft: the process dies, the session survives, the card stays and resume brings it back. stop is hard: the run is cancelled and leaves the Background section, not resumable. The distinction is enforced at both the verb and the route.

background / foreground are pure room surgery — neither touches the process. See Activity sidebar → Background agents.

agent definition

Manage the on-disk agent definitions (agent.md files under ~/.atrium/agents/). The def alias is interchangeable (atrium agent def list).

atrium agent definition list     [--filter COLUMN=VALUE]
atrium agent definition show     <slug>
atrium agent definition load     <slug>
atrium agent definition validate <slug>
atrium agent definition edit     <slug>
atrium agent definition path     <slug>

atrium agent definition create <slug> [...]
atrium agent definition delete <slug>

load writes the expanded body — system prompt followed by every enabled skill body — to stdout; it's the fallback that expands a ++slug mention in environments without a UserPromptSubmit hook (Cursor). edit opens the file in $EDITOR; path prints its location.

See Agent messaging for the framing protocol.

skills

Inspect the cross-adapter skills registry. Defaults mirror the Skills sidebar — current-workspace + canonical-path dedup. Opt out with --all or pin a different workspace with --workspace.

atrium skills list [--source <segment>] [--all] [--workspace <id>] [--filter COLUMN=VALUE]

--source accepts the same scope tokens as the sigil form: atrium-user, atrium-project, harness-<adapter>, harness-project-<adapter>, vercel-labs-skills.

Load a skill body (frontmatter stripped) to stdout — used by adapter hooks and Cursor's fallback to expand a +name mention.

atrium skills load <name> [--provenance <segment>]

hook

Emit an adapter hook event. Invoked by adapter-installed shell hooks, rarely by users directly.

atrium hook emit <event> --adapter <name> [--pane-id <id>] [--verbose]

config

Read and write configuration by dot-notation key (for example terminal.fontSize).

atrium config get <key>
atrium config set <key> <value>

set auto-detects the value type (integer, float, boolean, string).

theme

atrium theme list [--filter COLUMN=VALUE]
atrium theme switch <name>

launcher

Drive the in-pane launcher programmatically.

atrium launcher open   --pane-id <id>
atrium launcher select --pane-id <id> --adapter <name>

launch-profile

Create and manage launch profiles — the saved runtime bundles (model, reasoning effort, permission mode, CLI flags, environment, optional agent) the launcher and pane create --adapter apply. A launch profile is the how; an agent definition is the who.

atrium launch-profile list [--adapter <name>] [--filter COLUMN=VALUE]
atrium launch-profile show <slug> [--adapter <name>]
atrium launch-profile create \
    --adapter <name> --name <name> [--slug <slug>] \
    [--model <alias-or-id>] [--effort <level>] \
    [--permission-mode strict|plan|auto|yolo] \
    [--permission KEY=BOOL]... [--cli-arg KEY=VALUE]... [--env KEY=VALUE]... \
    [--default]
atrium launch-profile edit <slug> [--adapter <name>] \
    [--name <name>] [--model <alias-or-id>|--clear-model] \
    [--effort <level>|--clear-effort] \
    [--permission-mode strict|plan|auto|yolo] \
    [--permission KEY=BOOL]... [--remove-permission KEY]... \
    [--cli-arg KEY=VALUE]... [--remove-cli-arg FLAG]... \
    [--env KEY=VALUE]... [--remove-env KEY]...
atrium launch-profile set-default <slug> [--adapter <name>]
atrium launch-profile delete <slug> [--adapter <name>]

The first profile created for an adapter becomes its persisted Default. set-default changes which profile a bare pane create --adapter <name> launches with. --permission-mode atomically replaces the managed terminal flags and chat permission state; mode availability varies by adapter. Use adapter show <name> to discover model aliases and lower-level boolean launcher toggles. A profile also carries the launch surface (chat or terminal) and a launch target (foreground or background).

Apply one directly when creating a pane:

atrium pane create --type terminal --adapter <name> --profile <slug>

adapter

atrium adapter list [--filter COLUMN=VALUE]
atrium adapter show <name>

extension / exec

Run a dynamic command by dot-notation name; exec is an alias for extension run.

atrium extension list
atrium extension run <command> [--params <json>]
atrium exec <command> [--params <json>]

timeline

Query and append to the Timeline — the workspace event feed (agent turns, commits, tasks, notes, syntheses).

atrium timeline list   [--workspace <id>] [--scope <scope>] [--kind <kind>] \
                       [--since <rfc3339>] [--until <rfc3339>] [--tag <ns:value>] [--limit N]
atrium timeline search <query> [--workspace <id>] [--scope <scope>] [--kind <kind>] \
                       [--since <rfc3339>] [--until <rfc3339>] [--tag <ns:value>] [--limit N]
atrium timeline show   <id>
atrium timeline append --workspace <id> --kind <kind> --scope <scope> \
                       [--title <t>] [--body <b>] [--metadata-json <json>] [--tag <ns:value>]

list returns entries newest-first; search runs a full-text query ranked by relevance. --scope takes a canonical scope string (instance, workspace:<uuid>, room:<uuid>/<uuid>, pane:<uuid>/<uuid>); a workspace: scope also matches its descendants. --kind is a single kebab-case kind (e.g. git-commit, update). append writes one entry synchronously.

memory

Search, show, add, and supersede durable memory — facts and committed episodes. Works from a bare terminal as well as from inside an agent pane; --json is stable and camelCase for scripting.

atrium memory search <query> [--kind <kind>] [--scope <scope>] [--agent <slug>] [--limit N]
atrium memory show   <id> [--level l0|l1|l2]
atrium memory add    --kind decision|gotcha|preference|entity [--scope <scope>] <text>
atrium memory supersede <id> <new-text>
atrium memory reindex
atrium memory feedback
atrium memory consolidate

An empty search query lists the most recent facts. show also records the expansion, which is the signal that tunes what gets injected. reindex rebuilds the index from the on-disk fact files — disk is truth. consolidate distills episodes into facts as a visible, cancellable agent task on your own subscription.

Agent self-improvement proposals live under the same namespace:

atrium memory proposals list|show|add|apply|reject|defer|revert [<id>]
atrium memory autonomy <agent> [review|auto]

update

Recover from a bad update. CLI-only by design: the failure it exists for is "the new version will not start", where in-app UI is unreachable.

atrium update rollback

Reinstalls the app generation the last update superseded — kept on disk at ~/.atrium/previous for exactly this. See Install → Updating.

edits

List the past agent sessions that modified a file, newest-first, across every adapter's history. Powered by the same index behind Vault search.

atrium edits <file> [--limit N] [--session <id>] [--adapter <name>] [--since <when>] [--json]

--since accepts an ISO-8601 date (2026-01-01) or a relative span (60m, 24h, 7d, 1y). --adapter restricts to one tool (claude-code, codex, grok, …); --session to a single session id.

capture

Manage QA Capture bundles — screen + mic + input-event recordings, each addressable by a CAP-# id. capture show is the agent's primary resolution path: it returns the bundle's metadata plus absolute paths to video.mov, transcript.jsonl, and events.jsonl so an agent can read or frame-extract without dragging the whole video into context.

atrium capture show <id>                       # CAP-# → meta + absolute file paths
atrium capture list  [--limit <n>] [--since <when>]
atrium capture delete <id> [--yes]

Drive a recording session and pull stills or sub-clips out of a finished bundle:

atrium capture start [--region full|display:<id>] [--no-audio] [--no-mic] [--hide-cursor]
atrium capture stop
atrium capture flag  [--label <chapter>]        # mark a chapter at the current time
atrium capture screenshot <id> --at <seconds> [--out <path>] [--crop X,Y,W,H] [--max-edge <px>]
atrium capture chunk      <id> --start <seconds> --end <seconds> [--out <path>]

chunk copies a time range without re-encoding; screenshot --crop / --max-edge extract and downsample a single frame, handy for pulling one region out of a retina capture.

context

Print the caller's context — workspace, room, adapter, CWD. Reads $ATRIUM_PANE_ID from the environment.

atrium context

commands

Every available command, static and dynamic.

atrium commands [--filter COLUMN=VALUE]

version

atrium version

Prints CLI and app version plus the detected channel.

Transport and exit codes

Most commands require the app to be running. The CLI will cold-start the app if needed; this is the default for interactive use.
run, browser, and task commands work headlessly — they talk to the task/run store and the browser CEF backend without requiring the user-facing UI to be open (but they need atrium running in the background).
Exit code 0 on success, 1 on error. Common error kinds: not_connected, not_found, access_denied, invalid_params, internal.