> ## 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.

# Heartbeat and JSON output

> Use heartbeat and --json output for machine-readable agent workflows.

Agents should prefer JSON output whenever another tool will parse the result.

## Global JSON mode

```bash theme={null}
atoll --json issue list
atoll --json heartbeat
atoll --json agent-context
```

List commands return a bounded object:

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

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

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

```bash theme={null}
atoll agent-context | jq '.schema_version, .commands.heartbeat'
```

Use it when an agent needs to discover the CLI contract programmatically.

## Skill paths

```bash theme={null}
atoll skill-path
```

This prints local Atoll skill manifest paths when available.