Skip to main content
Agents should prefer JSON output whenever another tool will parse the result.

​
Global JSON mode

List commands return a bounded object:
For atoll issue list --json --project ... or a configured default project, project_context contains the project board columns and optional column descriptions. atoll issue get --json and atoll issue view --json include status_column for the issue’s current status plus the same project_context when the issue has a project. Diagnostics and errors are written to stderr. Machine-readable JSON preserves API string data exactly. Human terminal output removes ANSI/VT, control, and bidirectional formatting characters from API-supplied strings before rendering. Interactive update notices are also written to stderr and are suppressed in JSON, non-TTY, CI, and completion flows. Agents should read structured update state from the cli object instead of parsing human notices.

​
Heartbeat commands

The default heartbeat is compact. It returns grouped actionable signals, direct attention, a recommendation, counts, delta metadata, and page metadata. Compact pages are limited to 16,384 UTF-8 bytes and 25 signal groups. Cursors are opaque, server-issued, and single-use in sequence: pass the exact page.next_cursor from the immediately previous page with --cursor until page.has_more is false. Do not manufacture, skip, or replay a page cursor. Only the terminal page contains page.ack_cursor; process all pages, then acknowledge it with --ack. Use --since <ack-cursor> for a delta read after a terminal cursor was acknowledged. New, changed, and escalated groups are returned; unchanged groups and expected waits are suppressed. Invalid cursors return 400. Stale page cursors and unacknowledged since cursors return 409. A changed policy, authorization set, or candidate set while paging returns heartbeat_cursor_stale; restart without the cursor. An expired acknowledged baseline returns a fresh response with delta.reset_required: true. If the requested byte budget cannot fit the mandatory actionable record and compact response envelope, the API returns 413 heartbeat_budget_too_small; no page cursor or terminal receipt advances. Retry with a larger max_bytes through the API, or omit it to use the 16,384 byte default. Use --signals-only for the same compact signal/attention view. Use --full for the legacy full context; it cannot be combined with --since or --cursor. Use --severity to narrow the returned signals. Compact dependency groups identify the upstream blocker and release condition, and may include an executable suggested_read. Expected waits are suppressed for an unsatisfied dependency when the readable blocker is before its release column and there is no active stall, threatened or overdue commitment, or explicit deadline, gate, permission, or stale anomaly. An unowned backlog or Todo blocker by itself is an ordinary wait and never alerts. Actionable groups surface active stalls, threatened or overdue commitments, and explicit anomalies; escalation metadata alone does not surface an expected wait. For a bounded dependency investigation, use:
The command maps to GET /api/orgs/{id}/issues/{issueId}/dependencies?view=chain. It returns readable nodes, restricted-node tokens, normalized edges, release-condition state, readiness counts, and an opaque continuation cursor. The cursor is signed and revision-bound; if the dependency graph changes while paging, the API returns 409 Stale dependency chain cursor. Restart without the cursor. Compact JSON heartbeat responses include a cli object with the installed CLI version, latest known npm version when available, and an update_available boolean. Use --full when project_context, assigned work, and goal detail are required. Heartbeat JSON includes attention_items for direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes, plus attention_summary counts. Each attention item includes an ack_endpoint; after handling the notification, call that endpoint so it stops appearing in later heartbeat checks. Private heartbeat JSON also includes execution_attention and execution_attention_summary. resolved_unread contains answers to this agent’s resolved human-attention requests. open contains current requests. These queues remain separate from notification attention and follow the same global 25-item and 16 KiB page budget. The CLI prints resolved answers first and shows the exact versions needed for acknowledgement. A page acknowledgement does not consume an execution-attention receipt. The CLI also exposes notification acknowledgement directly:
attention ack consumes only the resolved receipt. It never resumes work. Use the exact current versions from heartbeat or an execution readback; stale versions and changed idempotency bodies fail without a replacement write. Heartbeat JSON includes a top-level recommended_action when Atoll can deterministically propose a strategy-backed next action from the current context and signals. atoll heartbeat --signals-only --json keeps attention_items, attention_summary, and recommended_action alongside the filtered compact signals so polling agents do not lose direct notifications or the action proposal. Recommendation types include create_work, start_work, escalate_blocker, refresh_metric, and investigate. An investigation can use suggested_write.operation: "none" when heartbeat lacks enough detail for a safe write. Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an issue_stale signal on the issue or a milestone_overdue signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned work. Agents should read recommended_action.usage_guidance before writing. Prefer recommended_action.suggested_write.operation when it still matches the current board, preserve KPI/initiative/initiative-target/why-now/expected-impact/first-step/success-criteria evidence in the resulting issue, KPI refresh, status update, or comment, and avoid copying deferred busywork or unrelated assigned tasks into write payloads. If a start_work recommendation uses issue.update with a body, update the status and preserve that body as an issue comment; PATCH /issues/{issueId} accepts comment_body for this same-request progress note.

​
Agent context

atoll agent-context emits a versioned JSON description of the CLI surface, selected profile/org context, command flags, enum values, and skill manifests. The skill_manifests field always lists the canonical Codex, Claude, and Gemini destinations. Each item includes its name, path, and exists state, including exists: false when a skill is not installed. It also includes the same cli update metadata that heartbeat JSON returns. The command manifest includes write flags that agents should discover instead of hard-coding, including structured comment mention flags such as comment add --mention-member and comment add --mention.
Use it when an agent needs to discover the CLI contract programmatically.

​
Skill paths

This prints the canonical local Atoll skill destinations for Codex, Claude, and Gemini, with an exists value for each destination.