---
title: The JSON envelope
description: One JSON envelope per command on stdout, with logs kept on stderr.
---

## 1. The contract

The machine contract. `apiVersion` lets the envelope evolve without silently
breaking parsers, and `type` is a discriminator an agent reads to know the
shape of `data` before parsing it.

## 2. The two shapes

A command answers with one of two shapes, the success envelope or the failure envelope. Both carry `apiVersion`, which this build sets to `1`.

```json
{
  "apiVersion": "1",
  "type": "cli.manifest",
  "data": {}
}
```

```json
{
  "apiVersion": "1",
  "error": "prose that changes freely as wording improves",
  "code": "ERR_UNKNOWN_COMMAND",
  "suggestions": []
}
```

Branch on `code`. The `error` string is prose for a human and is rewritten whenever the wording improves.

## 3. Exit codes

Exit codes stay stable so a shell caller can branch without parsing output.

| Constant | Value |
| --- | --- |
| `EXIT_OK` | `0` |
| `EXIT_USAGE` | `2` |
| `EXIT_RUNTIME` | `1` |

## 4. The two vocabularies

A success envelope carries one of 41 [response types](/reference/response-types/), and a failure envelope one of 21 [error codes](/reference/error-codes/). Both vocabularies are append-only, so a shipped value keeps its meaning and stays in the list.

## 5. Provenance

A loader generates this page from `apps/cli/src/envelope.ts` while the site builds, so no file in the repository holds it: the envelope, its codes, and its exit codes are declared there. Change the registry and this page changes with it.