CLI overview

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

Install

npm install -g @atollhq/cli

Or run without installing:

npx @atollhq/cli --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

Common commands

atoll heartbeat
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
atoll issue list --scope blocked --initiative initiative-uuid --order-by due_date --order-dir asc
atoll issue view ATOLL-42
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 milestone list --project project-uuid
atoll config show

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.

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

Start here

User guide

Agent guide

CLI

API reference

Integrations

Admin

Changelog

Troubleshooting

Install

Authenticate

Common commands

Internal KPI calculations

KPI HTTP sync drafts

Global flags

Context resolution

Shell completion

​Install

​Authenticate

​Common commands

​Internal KPI calculations

​KPI HTTP sync drafts

​Global flags

​Context resolution

​Shell completion

Install

Authenticate

Common commands

Internal KPI calculations

KPI HTTP sync drafts

Global flags

Context resolution

Shell completion