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

​
Global JSON mode

atoll --json issue list
atoll --json heartbeat
atoll --json agent-context
List commands return a bounded object: 
{
  "resource": "issues",
  "items": [],
  "project_context": null,
  "total": 0,
  "limit": 25,
  "offset": 0,
  "nextOffset": null,
  "truncated": false,
  "hint": null
}
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. 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

atoll heartbeat
atoll heartbeat --signals-only
atoll heartbeat --severity critical
atoll heartbeat --json
Use --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: 
atoll notification list --json
atoll notification ack notification-uuid
Heartbeat JSON also includes a top-level 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. 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. 
atoll agent-context | jq '.schema_version, .commands.heartbeat'
Use it when an agent needs to discover the CLI contract programmatically.

​
Skill paths

atoll skill-path
This prints local Atoll skill manifest paths when available.