Drive the CLI from an agent

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 --json

Nothing 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 --json

add 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 --json

Idempotent 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 --json

It 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 --json

apps/ 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 syncNo account, no deploy. Twice changes nothing
pithy doctorRead-only
pithy migrateA no-op at the head
Any provisionIdempotent 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.

ESC