Exit codes

CLI exit codes per clig.dev (success, error, usage) plus the quality-gate codes.

The first three codes are the CLI-wide contract every command honours. The gate codes (3–5) are used only by the pre-flight surface (IXH-2.6): import preflight / export preflight and the --min-grade / --fail-on flags on the import and export commands. They exist so a CI job can tell "the spec is not good enough" apart from "the network was down" (EXIT_ERROR) or "the credentials were wrong" (EXIT_USAGE, which every 4xx — including 401/403 — maps to), which is the whole point of gating in a pipeline.

Failed import/export jobs reuse codes 1–3 via apiome_cli.taxonomy_exit (IXH-6.4): taxonomy policy → 3, caller-fault categories → 2, transport/internal → 1.

Code	Name	Meaning
0	EXIT_SUCCESS	The command did what was asked.
1	EXIT_ERROR	Transport failure, server error (5xx), or an unexpected client-side failure.
2	EXIT_USAGE	Bad invocation, or a rejected request (any 4xx — including authentication).
3	EXIT_POLICY_BLOCKED	The tenant's import/export quality policy (IXH-2.3) blocks this payload. The report was produced successfully; the answer is "policy refuses this". A waiver that covers the shortfall downgrades the verdict server-side, so a waived payload does not exit with this code — it is reported as waived and passes.
4	EXIT_QUALITY_GATE	A --min-grade or --fail-on threshold supplied on the command line was not met. Distinct from EXIT_POLICY_BLOCKED: the tenant policy allowed the payload and the caller's own, stricter CI threshold rejected it.
5	EXIT_PREFLIGHT_UNUSABLE	The pre-flight completed but its subject is unusable: an import candidate that cannot be parsed at all (ok: false), or an export whose every ranked target is blocked or unavailable. Nothing the caller can grade — there is no artifact to gate.
6	EXIT_SCHEMA_TEST_FAILED	apiome schema test (IXH-5.5) ran its cases and at least one failed: a payload expected to satisfy the schema did not (or vice versa), or a generated mutant did not violate the constraint it was built to violate. Distinct from EXIT_ERROR (transport/5xx) and EXIT_USAGE (auth or an unresolvable schema reference — any 4xx) so CI can tell "the tests failed" apart from "the tests could not run".
7	EXIT_CHECK_FAILED	apiome checks run / checks show (GNC-3.1): the API change check suite failed — a required component judged the change unacceptable. Distinct from EXIT_ERROR (the suite could not be reached) and EXIT_USAGE (a rejected reference or credential) so CI can gate on the verdict itself.
8	EXIT_CHECK_PENDING	apiome checks run / checks show (GNC-3.1): the suite has no verdict yet — a required component is waiting on evidence (a contract run of this draft), or the commit is ahead of the draft the suite judges. Neither a pass nor a failure, so neither 0 nor 7: a pipeline decides whether "not yet" blocks it.