# json envelope

Operational commands with `--json` use one envelope. CLI help and shell completions are utility text; human `skill print` returns guidance directly.

| field | type | meaning |
| --- | --- | --- |
| `apiVersion` | string | `antil/v1alpha1` |
| `status` | enum | [status and exit codes](/docs/reference/status/) |
| `operation` | optional object | durable request `id`, `kind`, `state` |
| `data` | optional value | command-specific result |
| `error` | optional object | `code`, `message`, optional `path` |
| `conflicts` | array | permission conflicts; empty when none |
| `blockers` | array | persisted problems; empty when none |
| `next_actions` | array | concrete commands and their preconditions |

## actual shop test result

Unedited output from `antil run test --json --idempotency-key shop-test-a`. IDs, paths, and times vary.

```json
{
  "apiVersion": "antil/v1alpha1",
  "status": "ok",
  "operation": {
    "id": "op_dcd6b4b0cb0b",
    "kind": "run",
    "state": "succeeded"
  },
  "data": {
    "operation_id": "op_dcd6b4b0cb0b",
    "definition": "test",
    "run": {
      "group_gone": true,
      "id": "run_6f6b813ee8b8",
      "state": "succeeded",
      "pid": 59894,
      "log_path": "/private/tmp/antil-docs/shop-home/logs/run_6f6b813ee8b8.log",
      "exit_code": 0
    },
    "config_revision": "cfg_3d2eca261455765f",
    "deadline": "2026-10-31T16:34:00.105105Z"
  },
  "conflicts": [],
  "blockers": [],
  "next_actions": [
    {
      "id": "command-log",
      "argv": [
        "antil",
        "logs",
        "--run",
        "run_6f6b813ee8b8"
      ],
      "effect": "read the exact Run's redacted log"
    }
  ]
}
```

## session data

| field | contents |
| --- | --- |
| `workspace` | immutable `id`, `project_id`, current `root` locator |
| `session` | `id`, `stack`, `state`, `config_revision`, `liveness` |
| `services` | map by Service name; `state`, `port`, `url`, `direct_url`, `run`, optional `observation` |
| `config` | optional pinned vs current config: `pinned`, `current`, `changed`, optional `error` |
| `resources` | optional map; Allocation ID/generation, Binding generation, database, engine, Claim, Outputs, applied schema and seed-baseline evidence |
| `check` | optional last stored Rule report, not a new observation |
| `commands` | optional list of named command Run projections |

A Run contains `id`, `state`, `group_gone`, optional `pid`, `log_path`, `exit_code`. `group_gone` is completion evidence, not an inference from the leader's exit alone. An Observation contains `detail` and `time`.

Liveness contains `last_touched`, `expires_at`, `controller`, and `stale`. Resource Outputs contain a public `value` or `secret_ref`. Credential bytes are not part of these projections.

## other data projections

| command | data |
| --- | --- |
| `config explain` | effective `revision`, `path`, `value`, `origin` (`file`, `line`), optional per-value `values` origins |
| `logs` | `run_id`, `service`, `log_path`, `content` |
| `check` | report ID/time, pinned target/base, observed paths/revision/unknown reason, Rule evaluations, Claim revisions, Conflicts |
| `run`, `operation retry` | Operation ID, definition, Run, config revision, optional deadline, retry source |
| `operation cancel` | exact target Operation ID and Run with stop evidence |
| `claim upgrade` | accepted Claim, resource/generations, current and previous revision, whether changed |
| `prune` | preview revision, exact targets and retained reasons |
| `workspace create`, `workspace adopt` | registered checkout ID, root, branch and pinned commit |
| `init` | generated path, exclusion and review actions |
| `skill print --json` | `content` string |

## blockers and remedies

A Blocker contains `id`, `code`, `detail`, and optional `operation_id` and `run_id`. A Conflict identifies its Rule/cause, Resource, paths, missing permissions and exact generations, with Remedies.

Each `next_actions` entry has `id`, argv array `argv`, optional `preconditions`, `effect`, and `expected_revision`. Treat argv as arguments, not shell source. Inspect preconditions before executing a destructive Remedy. A stored revision ties intent to the evidence observed; changed inputs can reject it.