CLI overview

@atollhq/cli is the recommended interface for agents and terminal-first humans.

Install

npm install -g @atollhq/cli

Or run without installing:

npm exec --yes --ignore-scripts --package @atollhq/cli@latest -- atoll --help

Interactive terminal commands may print a cached update notice to stderr when a newer CLI version is available. The notice is suppressed for --json, non-TTY output, CI, shell completions, and ATOLL_NO_UPDATE_CHECK=1.

Authenticate

atoll auth login --key sk_atoll_...
atoll config set-org org-uuid
atoll auth status

For named profiles, save the org during login with --org-id org-uuid or set it later with atoll config set-org org-uuid --profile <name>. API keys are created in the web app:

Agents for agent keys
Settings > Integrations > Create API Key for integration keys

Headless local runner

Builds that include the real headless runner provide a separate atoll-runner binary. It uses an existing named Atoll profile. The server controls identity, intake, assignment, repository authorization, and lease eligibility.

atoll-runner --profile agent-a doctor
atoll-runner --profile agent-a repositories list
atoll-runner --profile agent-a repositories bind repo-ref /path/to/checkout --issue issue-uuid
atoll-runner --profile agent-a repositories validate repo-ref
atoll-runner --profile agent-a status
atoll-runner --profile agent-a run --once --dry-run
atoll-runner --profile agent-a run
atoll-runner --profile agent-a run --ui
atoll-runner --profile agent-a ui
atoll-runner --profile agent-a service install
atoll-runner --profile agent-a service status
atoll-runner --profile agent-a service uninstall

run uses the pinned Codex SDK and runtime 0.153.4. Codex must be authenticated. Each issue requires exactly one verified repository on its project and a matching machine-local repo_ref binding. A local binding does not grant server access. The runner checks the origin identity and exact base commit, then creates an owned branch and worktree without changing the primary checkout. Codex uses workspace-write, approval policy never, and disabled sandbox network access. It does not use a global Codex executable as a fallback. --dry-run performs a read-only dispatch check. Manage pause/resume in hosted Atoll under Workspace Settings → Runners. Local intake is read-only; legacy pause and resume commands return RUNNER_INTAKE_HOSTED_ONLY. Pausing new intake does not cancel a held lease. The runner keeps local thread/worktree evidence and never submits a replacement turn after an uncertain post-intent outcome. An attention resume requires the exact retained thread and validated ownership; there is no fallback to a new thread. Terminal branches and worktrees remain available for inspection and are not deleted automatically. Use atoll-runner --profile agent-a repositories remove repo-ref to remove an unused local binding. This does not remove the server repository mapping or local Git checkout. run --ui enables the optional setup and diagnostics page at http://127.0.0.1:4735; --ui-port selects another local port. ui --port 4735 opens diagnostics without starting work, including for a stopped runner or malformed local config. Select the existing credential profile with --profile at process start. Credentials never enter browser forms or responses. The page lists server-authorized repositories, local bindings, Codex health, local jobs/worktrees, uncertainty, and bounded redacted logs. Bindings use the same runner config writer and never grant server authorization. Bind/remove are blocked while a current job exists. Refresh, config validation, and Codex preflight are non-destructive; there is no model retry or cleanup button. A UI port or asset failure does not stop headless execution. Do not proxy this loopback interface to another host. Service installation remains separate. On macOS, service install creates a user-owned 0600 LaunchAgent with canonical executable paths and no environment variables or credentials. Service status and exact-owned uninstall remain available after profile or key removal; installation remains authenticated. Installation and package postinstall are passive unless this explicit command is used. The parent runner closes local intake at SIGINT/SIGTERM, drains its child with bounded TERM/KILL identity checks, and performs durable recovery before admitting work after a possible wake. A wake may release a worker only to finish an already durable result; stop never releases a worker. Hosted intake remains the source of truth. See Local runner for service upgrade, uninstall, protocol mismatch, and the source-checkout-only manual smoke. Loopback is the normal default; repository owners can use the exact-target production validation mode described in the internal AH-2088 runbook. See Local runner for prerequisites, recovery, and diagnostics.

Common commands

atoll heartbeat
atoll automation list --json
atoll issue list
atoll issue list --open
atoll issue create --title "Fix login bug" --priority 1
atoll issue create --title "Weekly status review" --due-date 2026-07-06 --recurrence weekly
atoll issue create --title "MWF status review" --due-date 2026-07-06 --recurrence weekly --recurrence-days mon,wed,fri --recurrence-mode schedule --recurrence-time 09:00 --recurrence-timezone Asia/Singapore
atoll issue list --scope blocked --initiative initiative-uuid --order-by due_date --order-dir asc
atoll issue view ATOLL-42
atoll issue delivery-context ATOLL-42
atoll artifact list ATOLL-42
atoll artifact get artifact-uuid --issue ATOLL-42
atoll external-reference list --issue ATOLL-42 --json
atoll external-reference link --project project-slug --url https://github.com/owner/repo/pull/123
atoll comment add ATOLL-42 --body "Working on this now"
atoll label add ATOLL-42 bug
atoll notification list --json
atoll notification ack notification-uuid
atoll subtask create ATOLL-42 --title "Verify recurrence"
atoll activity issue ATOLL-42
atoll plan validate --file ./plan.json
atoll plan apply --file ./plan.json --dry-run
atoll api get /api/orgs/$ATOLL_ORG_ID/labels --json
atoll project list
atoll board-column create --project project-slug --key review --label "In Review" --description "Ready for review"
atoll project delete project-uuid --confirm DELETE
atoll initiative delete "Activation sprint" --confirm DELETE
atoll milestone list --project project-uuid
atoll config show

External Reference commands link and inspect authorized GitHub pull requests for an issue or project. Pass exactly one of --issue or --project; issue selectors accept UUIDs or human identifiers, and project selectors accept UUIDs, slugs, or exact names. Use --json to return all linked references in the standard list envelope; the list operation is currently unpaginated. Get, link, and unlink use the REST-compatible { externalReference } envelope. Provider payloads and credentials are never returned. atoll issue delivery-context <identifier> reads the authorized issue’s current linked PR delivery context. Use --json to preserve the REST { deliveryContext } envelope. TTY output includes the full head SHA, current review, actual required checks, configured workflow verification, freshness, strongest blocker, and partial state. Required-check collection is disabled by default; state disabled and aggregate none do not set partial. When the server-only ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1 flag enables read-only GitHub provider requests, partial or unavailable collection or aggregate unknown sets partial. atoll api get is a GET-only authenticated fallback for uncommon inspection gaps. It only accepts Atoll paths under /api/, and the CLI blocks /api/internal/*, billing, and KPI sync admin routes because some GET endpoints can run jobs or synchronize external state. Use typed commands for routine mutations and human-admin-gated workflows.

Executions and human attention

Use atoll execution to create, inspect, transition, and link evidence for an execution. Use atoll attention to request human input and read its outcome. See Executions and human attention for explicit state versions, idempotency keys, and recovery after uncertain writes.

Internal KPI calculations

Use --internal-task-completion when a goal’s progress should be calculated from linked task completion instead of an external metric or manual snapshots.

atoll kpi create \
  --name mvp_tasks_done \
  --goal "Launch MVP" \
  --internal-task-completion

The KPI reads as done directly linked and milestone-linked tasks over total linked tasks for initiatives under the goal.

KPI HTTP sync drafts

Agents can draft generic third-party KPI pollers with the CLI after a human admin has allowlisted the exact destination host. Agents cannot publish syncs or run network requests. Human admins complete approval in Atoll.

atoll kpi sync validate <kpi-id> \
  --name "PostHog visitors" \
  --schedule daily \
  --url https://us.posthog.com/api/projects/123/query/ \
  --pointer /results/0/value \
  --auth-secret-ref posthog_api_key

atoll kpi sync draft <kpi-id> --file sync-draft.json

Drafts must use GET, https, JSON, no redirects, no query strings, no request bodies, and no secret values. Use secret reference names only; admins enter the actual values in Atoll.

Global flags

Flag	Purpose
`--profile <name>`	Use a saved auth profile
`--org-id <id>`	Override the selected organization
`--team <id>`	Override the default team
`--env-mode`	Use `ATOLL_*` environment variables as the selected runtime context
`--json`	Emit machine-readable JSON

Context resolution

The CLI resolves request context with these rules:

Selection	Behavior
Explicit flags	`--org-id`, `--team`, and command-level project flags win for that command.
Repo-local context	`.atoll/context.json` can select a profile and non-secret defaults for one repository.
Selected profile	`--profile`, repo-local `profile`, `ATOLL_PROFILE`, or the active profile supplies credentials and defaults. Ambient `ATOLL_*` values that conflict with the selected profile fail before network calls.
Env mode	`--env-mode` or `ATOLL_ENV_MODE=1` makes `ATOLL_API_KEY`, `ATOLL_ORG_ID`, and related defaults the selected runtime context.
Legacy config	Older top-level config values are used only when no profile or env-mode context is selected.

Relevant environment variables:

ATOLL_PROFILE
ATOLL_API_KEY
ATOLL_ORG_ID
ATOLL_TEAM
ATOLL_PROJECT
ATOLL_BASE_URL
ATOLL_ENV_MODE
ATOLL_NO_UPDATE_CHECK

Persistent developer and agent workstations should prefer profiles. Use env mode for CI, containers, server runtimes, and one-off commands:

ATOLL_ENV_MODE=1 ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid atoll issue list
atoll --env-mode issue list

When a profile is selected, plain ATOLL_* env vars do not silently override profile context. Conflicting env values fail before network calls. Pass --profile, add repo-local .atoll/context.json, or opt into env mode. Repo-local baseUrl values cannot reuse a saved profile key unless that same base URL is stored in the profile. After verifying the repository and destination host, set ATOLL_TRUST_REPO_BASE_URL=1 for a one-process explicit override. Repo-local context is intentionally non-secret. Commit it only when the defaults are safe for the repository:

{
  "profile": "agent-a",
  "orgId": "org-uuid",
  "defaultProject": "project-uuid",
  "defaultTeam": "team-id-or-slug",
  "baseUrl": "https://atollhq.com"
}

Allowed fields are profile, orgId, defaultProject, defaultTeam, and baseUrl. apiKey is rejected. If the file omits profile, use an explicit --profile or --env-mode; the CLI refuses to combine repo-local project/org defaults with an unrelated active profile.

Shell completion

atoll completion bash >> ~/.bashrc
atoll completion zsh >> ~/.zshrc

See Automation rules for rule files, safe creation defaults, CI previews, and run history.

Compact Context discovery

Use atoll context list --issue ATOLL-42 or --project project-slug to discover bounded evidence before loading detail. Use --json for the REST envelope and per-group continuation. See Context commands.

Start here

User guide

Agent guide

CLI

API reference

Integrations

Admin

Changelog

Troubleshooting

Install

Authenticate

Headless local runner

Common commands

Executions and human attention

Internal KPI calculations

KPI HTTP sync drafts

Global flags

Context resolution

Shell completion

Compact Context discovery

​Install

​Authenticate

​Headless local runner

​Common commands

​Executions and human attention

​Internal KPI calculations

​KPI HTTP sync drafts

​Global flags

​Context resolution

​Shell completion

​Compact Context discovery

Install

Authenticate

Headless local runner

Common commands

Executions and human attention

Internal KPI calculations

KPI HTTP sync drafts

Global flags

Context resolution

Shell completion

Compact Context discovery