A script cannot read a sentence. Everything below is the part of the CLI a pipeline, a Makefile or an agent is allowed to depend on.
The exit code says what to do next
| Exit | Class | Means | What to do |
|---|---|---|---|
0 | — | Done | Continue |
1 | failed | Unclassified failure | Read the error |
2 | usage | Usage or validation | Fix the call |
3 | precondition | Precondition unmet | Run the fix command |
4 | upstream | Upstream or transient | Retry with backoff |
5 | person | Needs a person | Stop and ask |
130 | — | Interrupted | Stop |
141 | — | Output closed early | Read what arrived |
Every failure used to exit 1. A bad flag, a project nobody provisioned, a Cloudflare outage and a step only a person may take looked the same to a script, so it could only stop. Each kind has its own code now.
Test for non-zero, not for 1. if pithy deploy --env staging; then … keeps working; [ $? -eq 1 ] does not, because most failures are no longer 1.
- 2, usage. The call is wrong and a different call fixes it: an undeclared flag, a value a flag does not take, a name that matches nothing, an unknown command,
input/required,validation/invalid_input. - 3, precondition. The call is right and something it depends on is missing: no Cloudflare credentials, an environment with no resources behind its bindings, a capability the project does not compose. This is the class that carries
fixmost often — for a missing capability,pithy add <capability> --worker <worker>, with--with-prerequisiteswhen it brings any that Worker lacks, runnable as written. - 4, upstream. A service Pithy does not control failed or asked for less traffic: the 429s, 502s, 503s and 504s. The one class with
retryable: true. - 5, person. A typed confirmation phrase,
pithy remove, a credential rolled at its issuer that the store never took, a storepithy secrets verifyfound something wrong with, apithy migratethat wrote declared secret-table migrations for a person to review. No retry or variation fixes these, and they never carryfix. - 1, failed. Pithy itself broke, or a code it cannot classify. A run that reports and found something —
doctorwith a finding,deployorupgradewith a failed item,ui sync --checkwith an uncovered route — exits 1 too: its report is the answer. - 130. Ctrl-C at a prompt. A person who answers no to a confirmation exits 1.
- 141. The reader closed the pipe before the output was done —
pithy schema --json | head. Nothing more is printed, because the reader has gone.
Every kit error code has exactly one class, checked by the compiler, so a new code cannot ship unclassified. pithy schema --json publishes the table from the installed binary as exitCodes and errorCodes, each code with its exitClass, exit, retryable and remedy.
pithy --pithiest exits 0. It is a refusal, not an error.
Two streams
stdout carries the answer. Under --json it is exactly one document. A script, a CI job or an agent gets it as one compact line; a person at a terminal gets the same document indented, with restrained color. PITHY_JSON=compact keeps it on one line for a whole session, and --no-pretty for one call. Only pithy dev, pithy dev logs and --json --events write a stream, and every line of a stream is one compact object.
stderr carries everything about the run. Progress arrows, warnings, the update notifier, and the error line. A pipeline that captures stdout and lets stderr through gets clean, parseable output and a readable log at the same time.
The failure line
A failed command writes one object to stderr and exits with its class:
{"error":{"code":"core/precondition_failed","status":412,"message":"No environment is ready — staging and prod have no DB database_id.","action":"Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy email provision --json --worker api` again.","exit":3,"retryable":false,"fix":"pithy provision --env staging --yes"}}code is domain/reason and is stable. message states the problem; action states what to do about it, and it is there because an error that tells you what broke and not what to do costs a search. Both are English, permanently — see Errors for why an error payload does not translate and what a client renders instead.
The line says what to do next. exit is the code the process ends with, and retryable says whether the same call can succeed unchanged — true only for an upstream failure. When the cause is known, fix is one pithy command that rights it, runnable as written. fix is absent, never null or empty, when nothing is known for certain, and a step only a person may take never carries one.
Every command a line names runs as written, whether it is the fix, a command in the action sentence, or a skip reason in a report. It names the Worker by its apps/ directory, carries the --yes, --with-prerequisites or --set the command needs, and, when it names your own run again, the flags you gave it. A command that deletes something or runs against production is never handed over as a fix. The line names it, says what it deletes or that it reaches production, and says That is a person’s decision, not a fix — as the pithy provision --env prod --yes in the line above does.
A question the run could not ask is input/required. Under PITHY_NONINTERACTIVE=1, --no-input or --json, a prompt with no default fails instead of opening, and the line names the flag that answers it and, when the set is known, every value it takes:
{"error":{"code":"input/required","status":400,"flag":"--worker","choices":["api","admin"],"message":"This project has several workers, so which one to wire is ambiguous.","action":"Pass --worker <name>. Known: api, admin.","exit":2,"retryable":false}}A flag the command does not declare is refused before anything runs, on every command, with exit 2 and, under --json, one validation/invalid_input line on stderr and nothing on stdout. It is checked once, ahead of the parser and ahead of --version, so a typo in a flag can never be silently parsed away or printed over. A group takes no flags of its own, so pithy token --json is refused rather than answered with usage.
Without --json the same two strings are the same two lines, the first in red:
No environment is ready — staging and prod have no DB database_id.
Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy email provision --worker api` again.Partial success is reported, not hidden
Some commands touch several things, and there is no transaction across them. Those report what happened on the way rather than collapsing to a single verdict.
pithy deploy attempts every Worker in apps/, even after one fails. Each gets an entry in workers[] with its own ok, and the command exits non-zero if any of them failed. One Worker’s typo does not stop the other four from shipping.
pithy migrate fans out over databases, and a fan-out has no transaction either — the third database throws and the first two are already ahead of it. So the error line still goes to stderr and the exit is still non-zero, and stdout still carries what the run changed on the way. That line adds three keys you will not see on a clean run:
| Key | Means |
|---|---|
interrupted: true | Present on this line alone. It is what says workers is a truncated report rather than a whole one |
failed | The database the run died on, as its binding and database |
unreached | Every database in scope the run never opened, in fan-out order |
An empty unreached means the failure was on the last database — never nothing was scanned.
pithy doctor is the gate
Doctor exits 1 when any Worker fails a check, which is what makes it usable as a CI step. It exits 0, 1 or 2 and nothing else: a missing precondition is something it reports, not something it refuses. Under --json, failures lists every check that failed the exit, each with its fix. What fails it is worth knowing, because the rule is consistent:
A finding fails the exit. A state that has not been reached yet does not.
- A contradiction between the project’s own config and its own wiring fails — a Worker declaring a Workflow its stanza does not bind, a domain nothing routes, a capability composed without its prerequisites.
- A step you have not taken yet passes — a project with no domain, an environment not provisioned, a secret registry never provisioned. Every project is in those states on day one, and turning the report red for everyone on day one would teach people to ignore it.
- A check that could not run gates nothing and says so. Offline, no credentials, an account that did not answer: reported as skipped with the reason, never rendered as a pass and never as a failure. A check nobody ran established nothing.
A declined binding is a configuration rather than a defect, so it prints — with the reason you wrote — and does not fail the exit.
In CI
The three commands a deploy pipeline runs, and nothing around them — the whole GitHub Actions workflow has the token, the caching, and what to run on a pull request.
- run: pithy doctor --json
- run: pithy migrate --env prod --json
- run: pithy deploy --env prod --json
env:
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}Nothing there needs a TTY, and nothing prompts. --json forbids every prompt for its call, --no-input does the same without --json, and PITHY_NONINTERACTIVE=1 forbids them for the whole session — set it once in a CI job. With input forbidden, a question with a default takes it, a question with no default fails input/required naming its flag, and a confirmation phrase fails core/person_required, exit 5. A confirmation defaults to no, so a run that cannot ask is never taken as yes.