Everything here rests on the kit being agent-drivable by design, and on --json and exit codes being a contract rather than a convenience. When a run goes wrong, diagnose a broken project; when it goes right, CI and CD is the same sequence unattended.
Scaffold
pithy init --name acme --worker api --jsonNothing is prompted under --json, --no-input or PITHY_NONINTERACTIVE=1, or without a TTY. Not the names, not the environments, not the credentials, not the domains, not the alias. A question with a default takes it. One with no default fails input/required, exit 2, naming the flag that answers it.
A CI run scaffolds with the flags it was given, takes the default environments, and writes no cloudflare block.
A block the writer could not place is printed for you to paste, never dropped — guessing at the shape of a file somebody may already have edited is how a scaffold eats an edit.
Add capabilities
pithy add auth --worker api --with-prerequisites --json
pithy migrate --jsonadd touches no Cloudflare account. That is why it works offline, in CI, and without credentials.
Read the result rather than assuming. add reports what it could not finish — a KV namespace id you must paste, a Workflow entry that needs provisioning first, a secret it cannot mint. Under --json, a step the run left required is next: the command to run, whole and runnable as written. No next means nothing is required.
Provision
pithy provision --env staging --dry-run --json
pithy provision --env staging --yes --jsonIdempotent and adopting — a resource of the right name is taken up rather than duplicated.
Every run states the file it wrote and whether that file is committed.
Plan it first. --dry-run names what the run would create or adopt, makes every refusal the real run would, and writes nothing. --yes is what lets the real run create resources at all.
Where to stop and ask
A supplied secret. Provisioning mints what is arbitrary — a signing key, an ingest secret — and stops for anything that has to agree with a third party.
Turning on Email Routing, and a routing zone flag. pithy email provision and pithy support provision create Email Routing rules, and enabling Email Routing for a domain points its whole MX at Cloudflare. Neither command enables it: support routes each environment’s address only on a domain where it is already on, and refuses the rest by name; email’s bounce rule takes its zone, address and Worker as explicit, all-or-nothing flags. Turning it on, and choosing those flags, is a person’s call, because a rule on the wrong domain moves somebody’s real mail.
pithy remove. It rejects --json, --no-input and PITHY_NONINTERACTIVE=1 outright, with exit 5. So does a production confirmation phrase you were not given: exit 5 means stop and ask, not try variations.
A line that says That is a person’s decision, not a fix. A command that deletes something or runs against production is never handed to you as a fix. The line names it, says what it deletes or that it reaches production, and says whose call it is — pithy provision --env prod --yes with its --confirm phrase, pithy secrets provision, which reaches every environment, pithy remove, pithy migrate --rollback. Stop and ask rather than running it.
Diagnose before you deploy
pithy doctor --jsonIt reports what a deploy would fail on — a binding missing from wrangler.jsonc, pending migrations, a declared route nothing serves, a gated route with no entitlement provider. Every finding carries fix: the command that rights it, runnable as written, or null when the remedy is an edit or a person’s.
A step you have not taken yet passes. A project with no domain and nothing provisioned is not an error on day one.
One optional line’s failure never costs another. Doctor discards every read failure it meets — a diagnostic has to work in the environment it diagnoses.
Deploy
pithy deploy --env staging --jsonapps/ is the registry — every directory holding a wrangler.jsonc is one deployable Worker, and deploy ships them all.
It refuses and names the command when a binding has no id, or when a Worker’s config does not bind what the app declares.
offers is not next. A staging or production deploy with no dashboard connection carries offers: [{ command, why }] naming pithy dashboard connect --env <env> --worker <name>. Put it to the person rather than running it: connecting opens a browser sign-in only they can approve, and its address and code have to reach them while the command waits. Ask them what the connection is for, and add their words as --purpose: a --json run without one is refused, and a purpose you wrote yourself is the one nobody gave. Connecting also records who authorized it, from their pithy cloudflare connect session, so a run under an account token is refused too. Say so rather than retrying it.
The commands that are always safe to repeat
pithy worker sync | No account, no deploy. Twice changes nothing |
pithy doctor | Read-only |
pithy migrate | A no-op at the head |
Any provision | Idempotent by construction |
Read the exit code, not the text
Gate on it. The output is for a person; the code and the JSON are for you. A failure exits by its kind — 2 fix the call, 3 run the fix the error line names, 4 retry with backoff, 5 stop and ask a person, 1 read the error — so test for non-zero, not for 1.