# JSON envelope

With `--json`, every command prints exactly one JSON object on stdout:

```json
{
  "schemaVersion": 1,
  "command": "reviewer annotate",
  "status": "ok",
  "data": { "annotationId": "annotation:screen:src/pages/Customers.tsx", "revision": 1, "status": "pending" },
  "issues": [],
  "nextAction": "Request an independent review of this revision with shadcn-maestro reviewer review --input <file>"
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `schemaVersion` | `1` | Version of this envelope |
| `command` | string | The command that ran: `help`, `reviewer`, `reviewer annotate` or `reviewer review` |
| `status` | `"ok" \| "pending" \| "error"` | Outcome; it sets the exit code (`0`, `3`, `2`) |
| `data` | object or `null` | The command's result; `null` on most errors |
| `issues` | `{ code, message }[]` | Problems found; see [Issue codes](/cli/issue-codes) |
| `nextAction` | string or `null` | What to do next, as a command or an instruction |

Rules an agent can rely on:

* `status: "ok"` can still carry issues, such as `dependency_check_skipped` or `manager_conflict`.
* On `pending` and `error`, each issue message is also written to stderr, and on `error` the next action is written as `Next: <action>`.
* Without `--json`, stdout carries readable text instead of the envelope, and nothing on `error`.