CLI reference

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.

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 workspaces (top-level projects).

atrium workspace list   [--no-worktrees] [--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 workspace once it's ready. Without --focus, atrium creates the workspace in the background and you stay where you are — useful for agent-driven setup scripts that should not steal focus.

worktree

Create and manage git worktrees as child workspaces, straight from the shell. A worktree workspace gets its own room, branch checkout, and isolated state; agents launched inside it inherit that context. See Workspaces & rooms 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 workspace and registers it as a child workspace; adopt binds a worktree that already exists on disk. remove runs git worktree remove and forgets the workspace; forget drops only the atrium workspace entry, leaving the on-disk worktree untouched; prune bulk-removes orphaned worktree workspaces.

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

atrium room list [--filter COLUMN=VALUE]
atrium room switch <id>
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 workspace. 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 workspace; 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 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>

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.

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>] \
                    [--cwd <dir>] \
                    [--split <pane-id>] [--direction right|left|down|up|subtab] \
                    [--focus] [--name <name>]

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>

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. Creating and deleting definitions is done from the Settings UI.

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

Inspect and promote 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>] [--filter COLUMN=VALUE]
atrium launch-profile show <slug> [<adapter>]
atrium launch-profile set-default <slug> [<adapter>]   # promote to the adapter's Default

set-default is how you change which profile a bare pane create --adapter <name> launches with. Creating and editing profiles is done from the Launch Profile editor in the app.

adapter

atrium adapter list [--filter COLUMN=VALUE]

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.

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, gemini, …); --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.