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, or without a TTY. Not the names, not the environments, not the credentials, not the domains, not the alias.

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

Provision

pithy provision --env staging --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.

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.

Anything with a routing zone flag. pithy email provision and pithy support provision create Email Routing rules, and enabling Email Routing on a zone points its whole MX at Cloudflare. The flags are all-or-nothing and explicit because creating a rule on the wrong zone moves somebody’s real mail.

pithy remove. It rejects --json outright.

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.

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.

The commands that are always safe to repeat

Read the exit code, not the text

Gate on it. The output is for a person; the code and the JSON are for you.