JSON output and errors

Every COMA command takes --json. Scripts and coding agents can rely on the shape below and on the error codes: they are part of COMA's public interface.

StreamsCopy Anchor Link

With --json, warnings are not printed to stderr; they are collected in the result's warnings array. Colour is off. Logs (--verbose, --debug, --trace) still go to stderr, so stdout always parses as one JSON document.

SuccessCopy Anchor Link

coma machine list --json

{
  "apiVersion": "coma.sh/cli/v1alpha1",
  "kind": "MachineList",
  "requestId": "req_01M437ZZEA4TBZSA8M7XMSGSDR",
  "data": [],
  "warnings": [],
  "meta": {
    "comaVersion": "v0.1.0-rc.4-3-g07087e6"
  }
}

Keys are camelCase. Byte counts are numbers of bytes.

FailureCopy Anchor Link

On failure, stdout is empty and stderr holds one error envelope. The exit code follows the error code (table below).

coma machine inspect nope --json

{
  "apiVersion": "coma.sh/cli/v1alpha1",
  "kind": "Error",
  "requestId": "req_01M437ZZDJC3MGMGBZ3DS9QKJZ",
  "error": {
    "code": "machine_not_found",
    "message": "machine \"nope\" not found",
    "retryable": false,
    "details": {
      "hint": "run `coma machine list`",
      "machine": "nope"
    }
  }
}

Usage errors, such as an unknown command or flag, use the same envelope with invalid_argument when --json appears anywhere before --.

Doctor commandsCopy Anchor Link

Commands that run checks write their report to stdout even when a check fails, then exit with 10 (doctor_failed):

• coma doctor writes only the DoctorReport.
• coma endpoint doctor and coma docker-context verify also write a doctor_failed error envelope to stderr. verify reports a context changed outside COMA as docker_context_drifted instead.

PassthroughCopy Anchor Link

coma docker and coma podman run the engine's own CLI on the machine. Their output is that CLI's output, and they exit with its exit status.

Error codesCopy Anchor Link

A code this table does not list maps to exit 1.

Refusals inside Docker errorsCopy Anchor Link

When COMA refuses a container request from the Docker CLI, Compose or an SDK, the refusal comes back through the engine API, so the client shows it in its own error. COMA's message names a code in parentheses, for example:

These are not coma exit codes: the client that made the request decides its own exit status.