Output and exit codes

The --json document, error and warning structure, exit codes and flag rules every command follows.

Every command follows the same output rules. They're designed so a script or coding agent can act on the result without guessing: every error names where the problem is, gives a stable code, and says what to do next.

`--json`

Pass --json to any command. It then prints exactly one JSON document on stdout, and nothing else: no banner, no progress, no colour. Progress and diagnostics go to stderr.

npx @elizon/cli validate --json

{
  "command": "validate",
  "valid": false,
  "errors": [
    {
      "path": "workflows.triage-flow.steps[0].invoke",
      "code": "UNRESOLVED_LOCAL_REFERENCE",
      "message": "`workflows.triage-flow` references `teams.clinical-reviewers`, which is not declared in this Package",
      "hint": "Declare `clinical-reviewers` under `teams[]`, or point the reference at one of: teams.clinical-review."
    }
  ],
  "warnings": [],
  "data": {}
}

Field	Type	Meaning
`command`	string	The command that ran, space-separated for groups (`"packages ls"`, `"target add"`).
`valid`	boolean	`false` if and only if `errors` is non-empty. Warnings never make a run invalid.
`errors`	array	Diagnostics that stopped the command.
`warnings`	array	Diagnostics worth reading that didn't stop it.
`data`	object	The command's result, when it has one. Absent when there's nothing to report.

Each diagnostic

Field	Always present	Meaning
`code`	Yes	A stable identifier, e.g. `MANIFEST_MISSING_FIELD`. See Error codes.
`message`	Yes	What's wrong, in a sentence.
`hint`	Yes	What to do next. Every diagnostic has one.
`path`	Usually	Where the problem is: a manifest path (`metadata.name`, `slots[2].boundTo`), a file inside the project or archive, or a Slot id. Absent when the problem is with the command line itself.

Some codes carry extra fields, e.g. CYCLE_DETECTED includes the whole loop.

Codes beginning CLI_ are about the invocation or the connection ("you typed the command wrong", "this machine isn't connected"). Every other code is about the Package. A script can tell the two apart without reading messages.

Human output

Without --json, results go to stdout and each diagnostic is printed as:

✗ [MANIFEST_MISSING_FIELD] metadata.version
  Missing required field `metadata.version`
  Use semver: `1.0.0`. Bump it for every artifact you distribute.

✗ /home/you/my-package/elizon.yaml: 1 error.

The same failure with --json:

{
  "command": "validate",
  "valid": false,
  "errors": [
    {
      "path": "metadata.version",
      "code": "MANIFEST_MISSING_FIELD",
      "message": "Missing required field `metadata.version`",
      "hint": "Use semver: `1.0.0`. Bump it for every artifact you distribute."
    }
  ],
  "warnings": [],
  "data": {
    "manifest": "/home/you/my-package/elizon.yaml",
    "checks": ["manifest-file", "schema", "…"]
  }
}

Exit codes

Code	Meaning
`0`	Success, including a run that produced only warnings.
`1`	Invalid input: a manifest error, an unknown or reserved command, a bad flag, a missing `--yes`, a rejected connection.
`2`	Internal failure: the CLI itself broke. Report it rather than retrying with different input.

The split between 1 and 2 lets a CI job tell a problem to fix in the Package from a broken tool.

Flag rules

Long options only: --json, --yes, --key=value, or a bare --key. There are no short options, and a single-dash token such as -o is refused with CLI_INVALID_USAGE rather than being treated as an argument.
Values attach with =: --target=acme, never --target acme.
Repeated keys with a dot: some commands take a family of flags, e.g. --slot.reasoning=…, --slot.calendar-access=….
Everything after a bare -- is passed through untouched.

Confirming writes: `--yes`

Commands that act on a real Organization (sign, install, packages bind) refuse to run without --yes, failing with CLI_WRITE_NOT_CONFIRMED. They never proceed on an implied yes, including in CI.

Treat --yes as a deliberate decision each time. If a coding agent is running the CLI, the setup files init writes tell it to ask you before any such command. See Author with a coding agent.