Exit 0, exit 1, exit 2 — a CLI contract agents can bet on

Written for ED-3 — the in-house supply-chain platform team — the engineer's standing cross-session agent seat, holding this page to survive a cold start.

One thesis: *every transactions.dev verb honors one mechanical contract — exit 0 for success, exit 1 for a negative domain verdict, exit 2 for unusable input or usage error; payload-only stdout; typed {"error":{"code","message","hint"}} objects on stderr — because an invalid document is a result the caller asked for, and an agent must be able to tell verdict from failure without reading prose.*

The three exit classes, and the line between them

The philosophical line first, because every design choice below follows from it. When you run validate on an invalid file, the tool did not fail — it succeeded at determining invalidity. Collapsing "the document is bad" and "the tool broke" into one nonzero exit is the oldest CLI sin, and it is fatal to unattended callers: a retry loop should retry a crashed tool and must never retry a valid verdict. So the classes are:

• exit 0 — the operation completed and the domain answer is affirmative: parsed, valid, agreed, emitted. An ack of a bad document is exit 0: producing the 997 is the system working.
• exit 1 — the operation completed and the domain answer is negative: invalid document, discrepant reconcile, events failing EPCIS validation. Payload on stdout as always — the verdict is the payload.
• exit 2 — the operation could not complete: unreadable input, unknown flag, an envelope too broken to parse. Typed error on stderr, nothing parseable promised on stdout.

Three transcripts, exact bytes

The contract is only real if the bytes are predictable. One fixture per exit class:

$ npx transactions.dev validate 856-clean.edi --json
{"verdict":"VALID","set":"856","version":"004010","grammarPin":"9f31c4"}
$ echo $?
0

$ npx transactions.dev validate 856-missing-ref.edi --json
{"verdict":"INVALID","findings":[{"code":"SEG_REQUIRED_ABSENT",
"segment":"REF","loop":"HL-shipment"}]}
$ echo $?
1

$ npx transactions.dev validate not-edi.pdf --json
$ echo $?
2

with, in the third case, exactly this on stderr:

{"error":{"code":"INPUT_UNPARSEABLE","message":"no ISA or UNB envelope found
in first 128 bytes","hint":"is this an EDI interchange? see parse --help"}}

Note what is not in any transcript: log lines on stdout, progress chatter, warnings interleaved with payload. stdout carries payload only, ever — pipe it to a file or a parser and nothing else arrives. Everything diagnostic is stderr, and everything on stderr that is an error is one typed object: a stable code from a published taxonomy, a human message, and a hint when a next step exists. An agent branches on $? and error.code; a human reads message; nobody greps prose.

--json everywhere, and the token economics of text mode

Every verb takes --json. Without it, output is terse TSV text — designed for shells and for context windows. Measured on the reconcile fixture from the reconcile post: the text-mode verdict line plus findings runs about an eighth of the token cost of the full JSON report. For a standing agent paying for every byte it re-reads across sessions, the rule of thumb: text mode for monitoring loops and gate checks, --json when you are about to act on the structure. Same data, same exit code, two register choices — the register discipline of the family applied to stdout.

This is the family contract, not a local invention: the event door's CLI at epcis.dev honors the same classes, the same typed stderr, the same payload-only stdout, so a script or a seat that learned one door already knows the other. The MCP door re-dispatches these same verbs through the same core — a door, not a second path — with verdicts carried in the tool results instead of $?.

The persist-me block

For the standing seat that returns tomorrow with a cold context, this is the block to write down:

transactions.dev — persist-me (2026-07-31)
entry:    npx transactions.dev <verb> [file] [--json]
verbs:    parse emit validate ack translate join reconcile pins
exits:    0 ok · 1 negative domain verdict (verdict IS the payload)
          2 unusable input/usage (typed error on stderr)
stdout:   payload only. stderr: {"error":{code,message,hint}}
verify:   pins --verify before trusting any verdict chain
docs:     AGENTS.md ships in the npm tarball; machine face at
          https://transactions.dev/llms.txt
records:  join output = EPCIS 2.0, validates against the pinned
          official schema; lands at https://epcis.dev

AGENTS.md in the tarball is the normative copy of this contract — if this post and that file ever disagree, the tarball wins, and the discrepancy is a bug to report. The pins line is there because a seat that resumes work should re-verify the grammar digests before extending yesterday's verdict chain: provenance is cheap to check and expensive to assume.

What to bet on

Bet on the classes, the typed codes, and payload-only stdout: they are the contract, versioned with the package, and a breaking change to any of them is a major version by definition. Do not bet on text-mode column order or message wording — that is register, not contract. The access flow for the principal you work under is at /get-access/; the entry verb above is the one their email unlocks.

---

826 words. The access flow is at /get-access/; the family's event door is epcis.dev.