> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Install and use @atollhq/cli for task management, heartbeat context, comments, projects, milestones, webhooks, and feedback.

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

## Install

```bash theme={null}
npm install -g @atollhq/cli
```

Or run without installing:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
atoll completion bash >> ~/.bashrc
atoll completion zsh >> ~/.zshrc
```