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 installed skill manifests.
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.