---
title: The envelope
description: "The one JSON object every command writes to stdout: its success shape, its error shape, and the conventions around both."
---

## 1. Two shapes, one discriminator

Every command that accepts `--json` writes one envelope object to stdout. It is one of two shapes, and the field `status` says which: `error`, `ok`. Both shapes carry `apiVersion`, which this manifest sets to `1`.

## 2. The success shape

4 fields. `type` names the payload shape and `data` carries it; [Response types](/microvms-agentd/reference/response-types/) lists every value `type` takes.

| Field | Meaning |
| --- | --- |
| `apiVersion` | string |
| `data` | object — keys per responseKeys |
| `status` | ok |
| `type` | string — one of responseType above |

## 3. The error shape

8 fields. Branch on `code`; [Exit codes](/microvms-agentd/reference/exit-codes/) lists every value it takes beside the process status it maps to.

| Field | Meaning |
| --- | --- |
| `apiVersion` | string |
| `code` | string — stable, branch on this |
| `data` | object — partial results, e.g. leaked identifiers, and `kind` naming the daemon status when one produced the failure |
| `error` | string — human readable, may be reworded between releases |
| `exitCode` | integer — matches the process exit code |
| `finding` | string — the docs/PLATFORM.md section, or empty |
| `status` | error |
| `suggestions` | array of string |

## 4. Conventions

The manifest states 6 conventions about the envelope, quoted here as the CLI publishes them:

* exactly one envelope object on stdout per invocation; progress is on stderr
* branch on `code`, never on `error`
* dollar figures are estimates derived from published rates, never an invoice
* an unpriced line item omits `usd` rather than reporting zero
* `data.kind` carries the daemon's own status name when the exit code is coarser than the failure (ERR\_PROTOCOL covers five)
* `exec --stream` is the one exception to the line above: it writes NDJSON — one event object per line — and this envelope as the final line, with the discriminant `microvm.exec.stream` rather than `microvm.exec`. Every other invocation writes exactly one object

## 5. Provenance

This page is generated from `docs/manifest.json`, the output of `microvm manifest`. This page reads `data.envelope` and `data.conventions`. `site/scripts/gen-reference.mjs` writes it into the site's content directory on every `pnpm run sync`, so an edit made here is overwritten by the next run.

To change the page, change the source. Regenerate the source with `mise run manifest` from the repository root; `mise run manifest:check` fails when the committed file no longer matches what the binary emits.