Global JSON mode
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
--signals-only for short polling. It prints the current signals, direct attention items, and the recommended action when one exists. Use --severity to narrow the signal set.
JSON heartbeat responses include a cli object with the installed CLI version, latest known npm version when available, and an update_available boolean.
Heartbeat JSON also 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.
The CLI also exposes notification acknowledgement directly:
recommended_action when Atoll can deterministically propose a strategy-backed next action from the current goals, KPIs, initiatives, linked issues, and signals. atoll heartbeat --signals-only --json keeps attention_items, attention_summary, and recommended_action alongside the filtered 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.
Skill paths
exists value for each destination.