Skip to main content
@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 > Members > Create API Key for integration keys

​
Common commands

atoll heartbeat
atoll issue list
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 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 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

FlagPurpose
--profile <name>Use a saved auth profile
--org-id <id>Override the selected organization
--team <id>Override the default team
--env-modeUse ATOLL_* environment variables as the selected runtime context
--jsonEmit machine-readable JSON

​
Context resolution

The CLI resolves request context with these rules:
SelectionBehavior
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 configOlder 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 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