The --json contract

--json emits exactly one machine-readable JSON document on stdout with no decoration; progress and diagnostics go to stderr. The one declared exception is a long-lived stream command, which may declare NDJSON (one JSON document per line). Errors go to stderr as { "error": { "code", "message", "status" } }. --json also forces non-interactive mode: a prompt opens only when stdin and stdout are both a terminal AND --json was not passed, so a --json run never prompts and never exits 8 — missing input exits 2 naming the flags to pass. Both halves of the contract are visible in one run:

octolens whoami --json   # exit 0; stderr stays empty on success

which puts exactly one document on stdout — the command’s own validated output example:

{
  "edition": "customer",
  "profile": "acme",
  "workspace": {
    "organizationId": "org_2abcDEFghij345",
    "name": "Acme",
    "plan": "Pro_v3"
  },
  "actingAs": null,
  "transport": "rest",
  "authSource": "profile",
  "scope": [
    "read",
    "write"
  ],
  "baseUrl": "https://app.octolens.com",
  "ignoredEnv": []
}

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

The --json contract