atriumatrium

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.

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

--type covers the two pane types you can spawn directly from the CLI today; specialized panes (source control, search, tasks, browser subtabs, notepad, etc.) 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.

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.

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>

task

List tasks in a workspace; show one task.

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

Create a task.

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>] \
                   --source <identity>

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>

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 and message other agent panes. 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>

See Agent messaging for the framing protocol.

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>

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>]

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.