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
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.

{
  "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.