<!-- Source: https://docs.biosimulant.com/references/cli/machine-output -->

# Machine-readable Output and Exit Codes

## JSON result

`--json` emits one schema-v1 result:

```json
{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "schemaVersion": "1",
    "command": "labs.validate",
    "cliVersion": "0.0.22"
  }
}
```

Failures use the same envelope with `ok: false`, `data: null`, and a structured `error`.

## JSONL progress

`--json-stream` emits ordered newline-delimited events. Every event includes:

- `type`
- monotonically increasing `seq`
- timestamp
- command
- stage
- message
- optional percentage

The stream finishes with exactly one terminal result event.

## Exit codes

| Code | Meaning |
|---:|---|
| `0` | Success |
| `1` | Operation or internal failure |
| `2` | Invalid command usage |
| `3` | Authentication or permission failure |
| `4` | Resource not found |
| `5` | Invalid content or validation failure |
| `6` | Conflict, including immutable-version conflicts |
| `7` | Capability unavailable in this environment |
| `130` | Cancellation |

A command remains present across Desktop, Studio, local terminals, and CI even when the current environment cannot provide its capability. In that case it exits with `7`.

## Global flags

Global flags may appear before or after subcommands:

```bash
biosimulant --json labs validate ./lab
biosimulant labs validate ./lab --json
```

Use `--legacy-json` only during migration from an older machine contract.