Ship every Worker the project deploys to Cloudflare — the ones under apps/ and one per composed capability that owns Workflows — then prove the version just shipped is the one answering at the address the project claims. Putting it on the internet is the walkthrough; this page is the command.
Synopsis
pithy deploy [--env <env>] [--apps] [--kit] [--force] [--dry-run] [--json [--events]]Flags
| Flag | Meaning |
|---|---|
--env <env> | Target environment: dev, staging, prod, or one you declared. No default — omitted, each Worker’s top-level wrangler.jsonc stanza ships, which is not an environment at all. dev is that same stanza. Both are refused while any D1 or KV binding in it has no id, and pithy add writes them without one — so for a project composing a capability that binds either, neither ships. The kit’s Workers ship in neither: they are per environment, and in dev they run locally under pithy dev |
--apps | Deploy only the Workers under apps/ |
--kit | Deploy only the kit’s Workers. Needs --env staging or --env prod |
--force | Deploy every Worker whether it changed or not: the ones under apps/ and the kit’s. With --kit it needs --env staging or --env prod, like --kit alone |
--dry-run | Show the plan and upload nothing: the migrations it would leave unapplied, and each Worker it would upload, after building it, running wrangler deploy --dry-run on it and comparing its stamp. Default false |
--json | Machine-readable output. Default false |
--events | With --json, a progress record per line as the deploy goes, closed by the --json document. Refused without --json |
There is no --worker. Deploy ships the whole set. Promoting a change from staging to production is this same command twice, with the environment named.
No selector means both halves. --apps and --kit each narrow it, and naming both is the same as naming neither — pithy deploy --apps --kit is pithy deploy, down to the line it prints when there is no environment for the kit half. They are two named steps rather than one list, which is the shape CI wants: separate exit codes, separate logs, and a failure that says which half broke.
A binding’s target ships first. An upload that binds a script which does not exist yet is refused, so your Workers go in the order their service bindings allow, each after every Worker it binds. When one of them binds a kit Worker, the kit half runs before yours instead of after it. A project with no bindings keeps discovery order. pithy worker bind is how an app declares one.
A kit Worker’s deploy is gated on a stamp. Each one carries the package version and a hash of its resolved configuration, and a run whose stamp matches both ships nothing. Anything the gate cannot establish — no Worker, no stamp, a Worker its last deploy left unfinished, an unreachable account — deploys. Your own Workers are gated too, on a hash of the bundle wrangler would upload (below). --force overrides both.
A Secrets Store entry nothing has written is a skip too. Cloudflare refuses a deploy whose binding names an entry the store does not hold. So with credentials in hand, each kit Worker’s bound entries are asked about first, a read, and a Worker binding one that is absent is skipped, naming the entry and the provision that writes it. The secrets manager is the one an upgrade reaches: it binds the field key, PITHY_FIELD_KEYS, which pithy secrets provision mints.
The secrets manager is stamped with the encrypted columns. Deploy derives them from every Worker’s schemas, the same way pithy secrets provision does, so a field you mark encrypted() joins the nightly rotation on the next deploy with no registration step. Encrypted fields has the rest.
A Worker that owns its database gets its own kit Workers. A Worker that lists a binding in ownBindings that a host binds — DB for email and audit — gets that host to itself, <project>-<env>-<worker>---<capability>, built from that Worker’s own composition: its database, its origin, its email theme and catalogs. Every other Worker shares <project>-<env>-<capability>, whose databases and catalogs come only from the Workers that share it, so an owned database never becomes the shared host’s. Each is its own kit row, and kit[].owner names the Worker an owned row belongs to. Which host each Worker’s Workflow bindings reach is pithy provision’s to write (naming). A Worker that owns SECRETS gets its own secrets manager the same way, and the shared manager binds each owned vault so its at-rest rotation re-seals them. The shared manager is deployed whenever an owner’s is, even when every Worker composing secrets owns its vault and none shares it: it is then bound over its own vault, the D1 pithy secrets provision created under its name, and a run that finds no such database fails, naming pithy secrets provision. Finding that vault needs CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, so a run without them asks nothing and reports the shared manager as a skipped kit row, saying it was not checked and naming both variables.
There is no --if-changed, in any spelling. Gating is behavior, not a mode. Nobody wants to re-upload an identical prebuilt bundle, so a flag for it could only ever be passed — and a flag that can only ever be true is one somebody eventually leaves off believing it does something, which is the exact bug this closes. --force is the escape hatch for a recovery run.
What it does
apps/ is the registry: every apps/<name>/ holding a wrangler.jsonc is one deployable Worker, and deploy ships each one whose bundle or configuration changed. It runs wrangler deploy [--env <env>] --experimental-provision=false in each Worker’s own directory, against that Worker’s own config, and lets wrangler own bundling, upload, bindings and routes. The directory is handed to wrangler as its own --cwd, not left to the package runner: npx starts from the nearest package root, so in an npm workspace wrangler used to start there, find no wrangler.jsonc, and try to set the directory up as a static site. pithy dev starts wrangler dev the same way. Output is captured and summarized rather than streamed.
It says what it is on, while it is on it. Capturing wrangler’s output is the right call and it is not being reversed — but it removed the only evidence the command was alive, and this command used to print nothing whatever until every Worker had finished. So each Worker is named as it is reached, ▸ acme-api..., and its own summary line is printed the moment that Worker settles rather than being held to a block at the end. The per-Worker lines moved; they are not printed twice. The migration warning now comes first, before the first upload, because it is about the schema this deploy is shipping code against.
These are plain lines, printed once and never redrawn — no spinner, no cursor movement — so a redirected stdout and a CI log take them unharmed. The only thing that silences them is --json, which still writes exactly one line. Not a missing TTY: a run in CI is the run whose log most needs to say where it got to.
A Worker that serves a front end is built first, in its own directory, through your package manager, from its manifest’s ui.build. The build carries the deploy’s environment, because the Vite plugin resolves each capability’s client-safe projection for a named environment — a build without it inlines dev values into a production bundle, silently. A failed build fails that Worker and skips its deploy: shipping a Worker whose assets are stale is worse than not shipping it.
One Worker’s failure does not abort the batch. Every Worker is attempted and reported, and the command exits non-zero if any of them failed. --json --events says each step as a record instead, for a program that wants to know where a long deploy got to (see --events).
It proves what it shipped
After a Worker ships to a named environment, deploy probes that Worker’s declared domain — the domains declaration, then a route, then vars.BASE_URL — for /health, and asserts the running version matches the version id wrangler reported.
Not the URL wrangler printed, which under gradual deployments may be a version-scoped preview. And not a liveness check, because the old version answering happily is precisely the failure worth catching.
| Outcome | Means | Fails the command |
|---|---|---|
verified | The version just shipped is the version answering | No |
inconclusive | More than one version is answering (a rollout in progress), or the Worker reported no version id | No |
mismatch | One other version is answering, consistently | Yes |
unreachable | Nothing answered at all — DNS, TLS, a timeout, no route | Yes |
unreachable is a different fact from either of the first two: it is transport-level, and the detail names the address that did not answer rather than guessing at a binding. The probe retries on a doubling schedule — about a minute in all — because a custom domain takes time to route to a new version, and a window of seconds reported correct deploys as mismatch. A verified deploy still costs one request: the probe stops at the first sighting. A Worker that answers 200 without a version has nothing the probe can ever match, so after three such answers it concludes inconclusive rather than waiting out the minute. There is nothing to verify on a bare deploy, on dev, when wrangler printed no version id, or when the Worker declares no address — all four are ordinary.
It refuses an environment whose origins do not line up
With --env, before anything is built or spawned.
Every auth baseURL, OAuth callback, magic-link URL and CSRF allowed-origin is derived from an environment’s origin. When the config states none, each of them invents one — and the dangerous invention is production’s, which is how a staging deploy emails real users magic links into production.
Three shapes are refused, each naming the Worker, the environment and the edit:
- No origin at all — no
domainsdeclaration, noroutespattern, novars.BASE_URLfor that environment. Declaredomains.<env>in the Worker’spithy.config.ts, or setvars.BASE_URLin itsenv.<name>stanza.domainshas keys forstagingandprodonly, so an environment you declared yourself takes the second route. - A declared origin nothing serves —
domains(orvars.BASE_URL) names a host and noroutespattern in that stanza covers it, so the Worker would ship and answer at no address. Runpithy worker syncto write the route from the declaration. workers.devleft open beside a custom domain — the Worker answers on the domain and on<name>.<subdomain>.workers.dev, which nothing decided about. Wrangler’sworkers_devdefaults totrueand declaringroutesdoes not change it. On that originBASE_URLnames the other host and the CSRF same-origin gate refuses exactly the requests that establish who you are. Set"workers_dev": falseinenv.<name>, or"workers_dev": trueto say you meant both — a named origin is the whole requirement, not a particular value.
pithy init and pithy worker add write the route and "workers_dev": false beside every domain they declare, so a project that answered the domain question meets this already. A feature environment is exempt: it is ephemeral, has no declared domain by design, and workers.dev is how it is reached.
A Worker reachable only over a service binding is not refused. "workers_dev": false, "preview_urls": false and no routes entry — each the stanza’s own, or the top level’s that wrangler inherits — close every public address on purpose, so there is no origin to declare. All three are required; "workers_dev": false alone is still refused. It is the shape server-authoritative writes ranks first for a gated write, and with no address declared there is nothing for the probe to verify.
It refuses an environment that does not bind what its Workers declare
With --env, beside the check above and before anything is built.
An app capability’s workflows map is written into wrangler.jsonc by pithy worker sync and by nothing else, so a job declared and never synced ships with no workflows entry and no triggers.crons: the binding fails on the Worker’s first request, and the cron simply never fires — nothing errors, nothing logs, and nothing probes red.
The invariant is one sentence — what the app declares is what the stanza binds — and it is asked as one comparison of the whole table, so a missing binding, a binding nothing declares, a stale cron and a binding carrying another environment’s Workflow name are one refusal with one remedy: run pithy worker sync. An entry and a cron you wrote for a library capability’s job your own Worker hosts are not the app’s, such as @pithy-sh/auth’s purge or @pithy-sh/payments’ usage pass, and they are left out of the comparison. A declaration that cannot be reduced to a stanza at all — a job with no className — is refused separately and sent to pithy.config.ts, because no command can write it.
It refuses a production environment that accepts the test assertion
With --env naming prod, or a name in the root config’s seed.productionEnvironments, and before anything is built.
@pithy-sh/auth’s attestation block is per environment, and test mode accepts a documented test assertion in place of a real app’s attestation. In production that would let any caller through. So each Worker under apps/ is composed for the environment, and one whose auth sets attestation.environments.<env>.mode to test is refused, exit 3, naming the Worker and the file to edit.
The Worker accepts the test assertion only where its ENVIRONMENT is dev, staging or feature, whatever its config says. This refuses the configuration before it ships. pithy doctor reports the same configuration without being asked.
It refuses a declared privacy class with console open
Before anything is built, for the Workers under apps/, whatever the environment. When the root pithy.config.ts declares privacy: { classes: [...] } and a linter config is readable and does not set its rule to error for every Worker source file — Biome’s suspicious/noConsole, or Oxlint’s no-console — nothing ships. With both linters configured, both must close it. The refusal names the file, the rule and the fix. A console.log goes around every gate a privacy class adds, so this is the one hard failure they bring.
The fix follows the cause. Where the rule was never stated, pithy privacy enable writes it. Where you turned it down — warn, off, an override lowering it — the change is yours to make, because enable will not override it.
A config Pithy cannot read deploys, and says so. No biome.json, biome.jsonc or .oxlintrc.json at the root, one that does not parse, both biome.json and biome.jsonc, a nested config in apps/ or inside a Worker, a glob Pithy will not guess its linter’s reading of, or one that extends another config, whose overrides could still turn the rule down: each prints Console gate unverifiable. with the reason before the first upload, and is reported that way. A project that declares no class deploys whatever the rule says.
Every deploy attests its privacy declaration into each Worker under apps/. One --var PITHY_PRIVACY:<json> on wrangler’s argv carries the declared classes, the gate’s verdict and its reason, and when, and the control plane’s manifest reads it back. A project declaring nothing attests exactly that, so its manifest says not declared rather than never attested. A raw wrangler deploy passes no such var, and without keep_vars wrangler uploads only the vars its config names, so a Worker shipped around this command reads as unattested.
Your Workers are gated on their bundle
Before each upload, deploy runs wrangler deploy --dry-run --outdir <tmp> on the deploy’s own argv and hashes what wrangler wrote, together with the configuration that argv makes wrangler read, the selected stanza, the argv itself — a --var is configuration too — and the files of the assets directory the configuration names. The privacy attestation counts less its date: every run dates a fresh one, and the date alone is not a change, so an unchanged Worker keeps the attestation of the deploy that last shipped it. wrangler’s README.md and the source maps are left out, because they carry the time and the output path.
When the live Worker’s stamp matches, nothing is uploaded. The hash is the PITHY_DEPLOY_STAMP var, the one the kit’s Workers carry. A matching Worker is unchanged, and its line says acme-api: unchanged. This bundle and configuration are already deployed. A change to the bundle or to the configuration changes the hash, and it deploys. An unchanged Worker is not probed and not audited, because nothing shipped. --force uploads it anyway, and reads no stamp.
The stamp is recorded only once the deploy has finished. The upload carries PITHY_DEPLOY_STAMP=unfinished, because wrangler sets the workers.dev subdomain, routes, custom domains and crons after the upload, and a deploy that fails there, or whose declared address then fails its check, has its code live all the same. Once wrangler has returned and the check has not failed, deploy sets the var to the hash through the Workers API, every other binding kept as it is. Cloudflare records that as a second version of the same code, so the version id moves twice for one deploy. A deploy that fails records nothing, and the next run deploys that Worker again, with the reason Its last deploy did not record that it finished. The kit’s Workers are stamped the same way.
When in doubt, it deploys: not on the account, no stamp, an unfinished deploy, a stamp that could not be read. A stamp that could not be recorded leaves the row deployed, and its reason says the next deploy uploads it again.
A first deploy is retried once when Cloudflare is slow to show the new Worker. After the upload, wrangler reads the Worker back, and for a Worker created moments before, Cloudflare can answer This Worker does not exist on your account. [code: 10007]. wrangler does not retry that, so the whole wrangler deploy fails after the upload succeeded. When that is the failure, deploy waits five seconds and runs the same deploy once more; re-uploading identical code is safe. A second 10007, and any other failure, fails the row. The kit’s Workers get the same retry.
It never migrates
With --env, deploy takes a best-effort count of unapplied migrations and warns when the schema is behind. A config it cannot load or a database it cannot reach yields no warning rather than a failed deploy. Promote the schema with pithy migrate first, then ship.
Every Worker deploy — success and failure — is audited as deploy/worker_deployed when the project has audit wired, recording the Worker, the version id and the verification outcome. Shipping to prod is recorded at warning severity; everything else is routine.
Credentials are CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, resolved from a session pithy cloudflare connect bound to this directory, or else from the account the root pithy.config.ts names, and passed explicitly to wrangler — so a local deploy authenticates the same way CI does. No wrangler login is involved. The account is resolved before anything else, and a pinned cloudflare.accountId that disagrees with the credentials refuses before wrangler is ever spawned. That refusal is the point: a deploy that authenticates against the wrong tenant succeeds, and says nothing.
It offers the dashboard
A named environment — not dev, not a feature environment — that deployed with no failure and has no dashboard connection is offered one, in one line before Done.:
staging is not connected to a dashboard. Connect it with `pithy dashboard connect --env staging --worker api`.The connection is read from the registry pithy dashboard status reads, and the line names one command per Worker composing the control-plane seam; any one connects the project. A project with no such Worker is offered nothing, and so is a registry that would not read, because an unknown is not an absence. It is an offer, not a step. Connecting opens a browser sign-in only a person can approve, so under --json it is offers, never next.
Seeing it first: --dry-run
--dry-run is Pithy’s plan, then wrangler’s, and it uploads nothing.
- Every gate the deploy refuses on refuses the dry run too, first. A binding with no id, a rate-limit namespace in the feature range, an undeclared origin, an unbound Workflow, a production environment in attestation test mode: each is the deploy’s own refusal, with its exit code and its
fix. Then the migrations the environment has not applied are named in a note beside the command that applies them. - Then each Worker under
apps/is built and handed towrangler deploy --dry-run --outdir, on the deploy’s own argv. wrangler bundles and validates and stops, so a bundle that does not build fails its row here rather than at the deploy. Then its stamp is read and compared exactly as the deploy compares it, so the verdict is the one the deploy reaches: a Worker that would ship is oneplan.resourcesupload, with its reason, and an unchanged one is aworkersrow withoutcome: "unchanged". Nothing is probed and nothing is audited, because nothing shipped. - The build and the bundle happen in a private copy of the project, under the system temporary directory, and the copy is gone before the command exits. The project is byte-identical afterwards.
- The kit half reads each stamp and stops. No temporary config is written and no wrangler runs.
$ pithy deploy --env staging --dry-run
▸ acme-api...
acme-api: would deploy. Its bundle or resolved configuration changed.
Would upload worker acme-api (staging).
1 migration unapplied for staging: 1000_app_0001_things. Deploy does not migrate — run pithy migrate --env staging.
Dry run. Nothing uploaded.It exits the way the deploy would have.
--json
One line on stdout, after every Worker has been attempted — or, under --events, the last line of a stream (below). A failure inside the command — no project, no deployable Workers — is one {"error": …} line on stderr instead, carrying exit, retryable and, where the cause is known, fix. A failed deploy is reported in the payload.
| Key | Type | Meaning |
|---|---|---|
command | string | "deploy" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
env | string or null | The environment deployed, or null for a bare deploy of each Worker’s top-level stanza |
pendingMigrations | number or null | Unapplied migrations for the target environment. null with no --env, and null when the count could not be taken — deploy never fails over it |
workers | object[] | One entry per Worker, in deploy order: discovery order, with each service binding’s target before the Worker that binds it. Every Worker is attempted |
workers[].name | string | The Worker’s name |
workers[].ok | boolean | Whether wrangler deploy succeeded for this Worker; an unchanged Worker is true. Under --dry-run, whether wrangler deploy --dry-run accepted its bundle |
workers[].outcome | string, optional | "deployed" when wrangler uploaded it, "unchanged" when its live stamp matched this bundle and configuration and nothing was uploaded. Under --dry-run, what the deploy would do. Absent on a failure |
workers[].reason | string, optional | Why the outcome is what it is, in one sentence: It was not on the account., It carried no deploy stamp., Its deploy stamp could not be read. with what Cloudflare said, Its bundle or resolved configuration changed., --force was given., Its last deploy did not record that it finished., This bundle and configuration are already deployed. A deployed row whose stamp could not be recorded adds Its deploy stamp could not be recorded, so the next deploy uploads it again. and what Cloudflare said. Absent on a failure |
workers[].versionId | string, optional | The deployed version id, when wrangler’s output carried one |
workers[].url | string, optional | An address wrangler listed under this Worker’s deployed triggers — its workers.dev host, or the host a custom domain or a route answers on. Absent when no trigger is an address: a cron, a queue or a workflow trigger is not one, and neither is a wildcard route |
workers[].built | boolean, optional | Whether this Worker’s UI build ran and succeeded. Absent when the Worker declares no ui block — so false means the build is what failed and the deploy never ran |
workers[].error | string, optional | The failure reason. Present only when ok is false |
workers[].exit | integer, optional | The exit a classified failure carries: 3 when Cloudflare refused the credentials or wrangler would not start after an earlier Worker already had a row. Absent on an ordinary failure |
workers[].verification | string, optional | What probing the declared domain concluded: "verified", "mismatch", "inconclusive" or "unreachable". Absent when there was nothing to check |
workers[].verificationDetail | string, optional | The one-line explanation behind verification |
kit | object[] or null | One entry per composed capability’s Worker, in registry order. null when the kit half did not run — --apps, no --env, or --env dev — which is a different fact from it finding nothing. Under --dry-run, a Worker the deploy would upload is in plan.resources instead, so no row says deployed |
kit[].capability | string | The capability that owns the Worker, e.g. "email" |
kit[].owner | string, optional | The apps/ Worker whose own host this row is, because it owns a binding the host binds. Absent for the shared host. Two rows can share a capability: the shared host and a Worker’s own, told apart by this key and by worker |
kit[].worker | string or null | The deployed script name, e.g. "acme-prod-email". null when the run never got far enough to derive one |
kit[].outcome | string | "deployed", "unchanged", "skipped" or "failed" |
kit[].reason | string | One sentence saying why. Never empty, for every outcome |
kitProblems | string[] or null | What stopped the kit half knowing the set: a Worker whose capabilities could not be read, a composition that would not assemble, a failure that ended the pass. Beside the rows rather than among them, because none of them names a capability. Non-empty exits 1. null exactly when kit is |
dryRun | boolean | Whether this was --dry-run. Nothing was uploaded when it is true |
privacy | object or null | What this deploy attested into each Worker under apps/ as PITHY_PRIVACY. null when that half did not run (--kit) |
privacy.declared | string[] | The classes the root pithy.config.ts declares. Empty when it declares none |
privacy.consoleGate | string | "enforced", "unverifiable" (no linter config Pithy could read — deployed, and reported as unverified), or "not_required" (no class declared). A gate that is off refuses the deploy instead |
privacy.reason | string or null | Why the gate is "unverifiable", in one sentence. null otherwise |
plan | object | Present only under --dry-run: plan.resources holds each Worker it would upload, and plan.notes the migrations it would leave unapplied |
next | object[] | [{ command, why }]: pithy migrate --env <env> when pendingMigrations is above zero and every Worker shipped, because deploy never migrates. Absent otherwise, and never empty |
offers | object[] | [{ command, why }]: pithy dashboard connect --env <env> --worker <name> when a named environment — not dev, not a feature environment — has no dashboard connection and every Worker shipped. One entry per Worker composing the control-plane seam; any one connects the project. A follow-up for the person to choose, not a required step: an agent asks before it runs one. Absent otherwise — on a failed run, under --dry-run, when nothing composes the seam, and when the registry would not read — and never empty |
Exit code. 0 when every Worker’s ok is true and no Worker’s verification is mismatch or unreachable; 3 when a Worker’s row carries exit: 3, because the credentials or wrangler are the next step whatever else failed; 1 otherwise. The line is printed either way, so a CI step can read the payload and still gate on the status. Under --dry-run the code is the one the deploy would have exited with.
--events
--json --events turns the one line into a stream: one compact JSON record per line as each step starts and settles, then the document above as the last line. Every line is compact and uncolored whatever --pretty or PITHY_JSON asked for. The last line has no event key and every record before it has one, which is how a reader tells them apart. Without --json it is refused: --events needs --json., exit 2.
| Key | Type | Meaning |
|---|---|---|
command | string | "deploy", on every record |
schemaVersion | integer | The same version the document carries |
event | string | "start" as a step begins, "settled" as it ends |
what | string | start only: what is being worked on — a Worker’s name, or the build step |
line | string | settled only: the line a person would have read for it, without color |
worker | object, optional | settled only: the row a Worker under apps/ settled as, exactly as workers[] lists it |
kit | object, optional | settled only: the row a kit Worker settled as |
A failure inside the command ends the stream with no document, and the {"error": …} line goes to stderr as it always does.
Errors
No pithy.config.ts here.Run it from a Pithy project.No deployable workers here.Nothing underapps/carries awrangler.jsonc. Runpithy worker add <name>. Exit 3.- A Cloudflare account mismatch. The project pins one account and the resolved credentials belong to another. Refused before wrangler is spawned, naming both ids and which source supplied the wrong one. Exit 3.
- Cloudflare refusing the credentials. wrangler reports an authentication error, or finds no token. The credentials are the same for every Worker, so on the first Worker the run stops and exits 3,
core/precondition_failed, with the actionRun pithy doctor to see whether the token or the account is wrong. When wrangler was handed no token at all, the action names the sign-in instead:Cloudflare credentials are missing, so wrangler had nothing to sign in with. Run pithy cloudflare connect to sign in, or set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN.Once any Worker has a row, a later refusal is that Worker’s row instead, withexit: 3. Could not run wrangler.The program the project runs wrangler with is not onPATH. Exit 3.- An environment whose named and served origins do not line up. Refused before anything is built, naming the Worker, the environment and the one edit that answers it. Exit 3. A declared origin nothing serves carries
pithy worker sync --worker <worker> --env <env>as itsfix. - An environment that does not bind what its Workers declare. Refused before anything is built, naming both sides of the comparison and
pithy worker sync. Exit 3, withpithy worker sync --worker <worker> --env <env>as itsfixon one Worker. <env> sets attestation to test: <workers>.A production environment whose auth accepts the test assertion. Refused before anything is built. It iscore/precondition_failed, exit 3, and its action namesattestation.environments.<env>.modeand the Worker’spithy.config.ts. It carries nofix, because the remedy is an edit.This project declares <classes>, and console is open: <reason>A class is declared in the rootpithy.config.tsand a linter config does not set its rule —suspicious/noConsolein Biome,no-consolein Oxlint — toerror. Refused before anything is built, naming the file and the rule. It iscore/precondition_failed, exit 3, and its action is to set the rule to"error"or runpithy privacy enable. A rule you turned down on purpose is yours to change;pithy privacy enablewill not overwrite it.- A binding with no resource behind it. Refused before anything is built, naming
pithy provision --env <name> --yes. For a named or feature environment it is exit 3 and that command is itsfix— except for a production environment, whose provision takes a--confirmphrase only a person gives, so the line says the run is a person’s decision and carries nofix. For the top-level stanza it is a usage error, exit 2. - A Worker’s build or deploy failing. Reported per Worker on the row rather than thrown. A build failure and a deploy failure read differently, because they have different fixes. wrangler’s exit code and stderr are the
errorstring. --envis validated at the flag when one is given.productionis answered withprod, exit 2. An environment the rootpithy.config.tsdoes not declare is refused before anything is read, exit 2.
Examples
pithy deploy
pithy migrate --env prod --json
pithy deploy --env prod --json
# See what a deploy would do: the plan, then wrangler's own dry run. Nothing is uploaded.
pithy deploy --env prod --dry-run --json
# Ship everything, and say where it got to as it goes: a record per step, then the result.
pithy deploy --env prod --json --events
# Re-upload your Workers whatever their stamp says.
pithy deploy --env prod --apps --force- name: Deploy workers
run: pithy deploy --env prod --json
env:
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}A batch where one Worker shipped and the other’s build failed:
{"command":"deploy","schemaVersion":2,"env":"prod","pendingMigrations":0,"workers":[{"name":"acme-api","ok":true,"versionId":"<version-id>","url":"https://acme-prod-api.example.workers.dev","verification":"verified","verificationDetail":"https://api.example.com is serving the version just deployed."},{"name":"acme-web","ok":false,"built":false,"error":"vite build failed."}],"dryRun":false}The two environment variables in the CI snippet are the names of secrets your provider holds. No value appears there, and no payload from this command can carry one.