pithy provision

Create an environment’s own Cloudflare resources, wire them into every Worker, and migrate. It is the middle step of putting a project on the internet: resources first, then pithy deploy.

Synopsis

pithy provision --env <environment> [--yes] [--confirm <phrase>] [--seed] [--repoint] [--json]
pithy provision --feature [--json]

One job, two spellings. --env provisions an environment the root pithy.config.ts declares; --feature provisions the one this branch gets. Exactly one of them is required, and passing both is refused at the flag, before a config is loaded or a Cloudflare client is built.

--env runs from the project root. --feature runs from inside the feature worktree and takes no name: the branch says which feature it is.

Flags

FlagApplies toDefaultPurpose
--env <environment>——The declared environment to provision. Refused unless the root pithy.config.ts lists it
--feature—falseProvision this branch’s own environment instead. Run from inside the worktree
--yes--envfalseConfirm that this creates real Cloudflare resources. Required for every declared environment
--confirm <phrase>--env—Unlock a production environment non-interactively: yes, i really want to provision <env>
--seed--envfalseAlso load seed fixtures once the schema is up. A prepared set run this way is offered the secrets this run minted
--repoint--envfalsePoint a binding at the resource this run names where its stanza points at the counterpart, because a Worker moved between shared and owned. Without it that run is refused. Refused with --feature, whose stanza is rewritten on every run — see owning a binding
--jsonbothfalseOne line of machine-readable output

Both modes also take two flags that change what the run writes and says:

FlagApplies toDefaultPurpose
--dry-runbothfalseShow the plan and write nothing: the resources it would create or adopt, the config edits, the secrets, the migrations. Needs neither --yes nor --confirm. See Seeing it first
--eventsbothfalseWith --json, a progress record per line as the run goes, closed by the --json document. Refused without --json: --events needs --json.

--yes, --confirm and --seed say nothing a feature environment does not already do. It is created per pull request and destroyed on merge, so there is nothing to confirm — a gate every pipeline has to pass is a gate that has stopped meaning anything — and it is created empty, so it always seeds.

Why one command

Both modes create one Cloudflare resource per binding name across every Worker, and one more for each Worker that owns the binding, write the ids into each Worker’s config, and migrate. Every name they compose is held to the naming rules and their limits, which is why a project name is capped well under Cloudflare’s own ceiling. They differ only in how the target environment is named — declared in pithy.config.ts, or derived from the branch. That is a flag, not a different verb.

The safety is in the scope rather than in the spelling. A ProvisionScope carries the resource naming and the env.<name> stanza the ids are written into, as one value — so a feature-named resource landing in a declared environment’s stanza of a checked-in config is unexpressible rather than merely refused.

The one real difference: what happens to the ids

WritesStatus
--env <name>env.<name> in the Worker’s tracked wrangler.jsoncSource — long-lived ids you review in a pull request
--featureapps/<worker>/.wrangler/pithy/wrangler.feature.jsoncBuild artifact — git-ignored, rebuilt every run, never committed

A single flag that flips whether output is committed will eventually surprise someone, so every run states the file it wrote and what happens to it:

Wrote 3 ids into apps/board/wrangler.jsonc. Commit them.
Wrote 3 ids into apps/board/.wrangler/pithy/wrangler.feature.jsonc. Ignored, and rebuilt on the next run.

--json carries the same answer as configs and committed, so a pipeline reads it rather than inferring it. This is also what keeps the standing rule true: a CI build process never commits back to the repository. A pipeline runs --feature and has nothing to commit; a person runs --env and commits ids in a pull request.

--feature is explicit, never inferred

It is not derived from the branch looks like a feature branch. An implicit mode switch on branch shape is how somebody on feature/… provisions the wrong thing while reading a command line that says nothing about it. The flag is the declaration; the branch is only where a feature’s name comes from once you have made it.

The two modes cannot reach each other’s environment either. --feature writes the feature stanza and nothing else. --env accepts only what the project declares, and feature can never be declared — it is a legal wrangler stanza key and an illegal declaration, because a feature’s config is generated rather than committed and one stanza cannot have two owners.

Why it exists at all

A project scaffolded, wired and migrated by Pithy could not be deployed, and nothing said why.

CommandWhat it does about resources
pithy add <cap>Runs the Worker’s dev migrations, against local D1 through Miniflare. Creates nothing remote
pithy migrate --env prodQueries the target database. Assumes it exists
pithy deployProvisions nothing. Spawns wrangler

So apps/<worker>/wrangler.jsonc declared "database_name": "<project>-staging-db" with no database_id, in every environment, and stayed that way — and the first deploy failed inside wrangler, on a field nobody knew they were meant to fill in. The provisioner was never missing; only the command and the naming were.

What it does

  1. Resolves the scope. The naming and the stanza come from one object rather than two arguments: <project>-<env>-<thing> into env.<env> for a declared environment, <project>-f<issue>-<slug>--<thing> into env.feature for a branch’s.
  2. Provisions one resource per binding, shared by default and owned through ownBindings, across the union of every Worker’s capabilities. Two Workers that both declare DB share one database. A Worker that lists DB in its pithy.worker.jsonc ownBindings gets its own, <project>-<env>-<worker>---db (shared by default, owned when a Worker says so). A resource is keyed on its kind, its binding and its owner, and two of one kind under one name are refused before anything is created.
  3. Adopts rather than duplicates. Every resource is matched by name before it is created, so a re-run is a no-op and a database you made by hand under the right name is taken up rather than shadowed by a second one.
  4. Writes the ids into each Worker’s config, under env.<name> — and a Worker receives only the bindings its own config declares, each at its own resource: the shared one, or the one it owns. The D1 entry gets its database_name alongside its database_id, and the name is the one this run composes for that Worker, written over whatever the entry said. A name chosen by hand is not adopted; pithy doctor’s Resource names: block reports one before a run rewrites it. A queue producer names the queue this run created, and a producer moved onto it from another environment’s queue takes that queue’s queues.consumers entry with it, settings and all, so the Worker never sends to one queue while reading another; a stanza that already consumes this run’s queue keeps that consumer. The stanza is created when it is absent, so an environment declared after the project was scaffolded needs no hand-editing. Every var the Worker declares with defineVars is written into the stanza at that environment’s value, or the default, exactly as pithy worker sync writes it: a new stanza starts from the top level’s vars, so without that a production stanza provisioned before any sync would deploy with dev’s value. A feature’s stanza, regenerated on every run, gets its feature value or the default the same way. A valid value already in a tracked stanza stays. Every artifacts entry the top level declares is bound in every stanza, each naming this scope’s own namespace, <project>-<env> or <project>-f<issue>-<slug>--artifacts, so a branch’s repositories never sit beside production’s. Nothing is created for it: Cloudflare makes the namespace on its first repository.
  5. Writes the secrets_store_secrets stanza for every cf-secrets-store secret the Worker’s own registry declares, when a Secrets Store id is in hand. pithy add deliberately could not write it — the entry needs a store_id and a secret_name that do not exist until an account has been reached. A declared secret whose entry has not been created is reported rather than bound: wrangler refuses a config naming an absent entry, so binding it would turn one missing value into a failed deploy of the whole Worker. A feature binds no RUNTIME_CF_API_TOKEN, and is not told it is missing. Nothing mints the application’s one Cloudflare token for a feature, so branch code never holds it, and a line asking for a mint the feature would never bind is a line no run could clear.
  6. Creates the secrets that have no decision in them. A registry entry declares whether its value is arbitrary — a signing key, an ingest secret: any random string works, because nothing outside the project has to agree with it. Provisioning mints those and binds them in the same pass. It still stops for a supplied secret — an OAuth client secret, a payment rail’s key — because a random string there authenticates against nothing. Absence is checked first, always: an existing value is never replaced, and replacing one is rotation, which is a separate and deliberate act. No minted value is printed, logged, or put in an audit event. It is handed to one place: this run’s own seed step, as context.mintedThisRun on a prepared set — --seed here, and always on --feature. The Secrets Store is write-only from the CLI, so that is the only moment a fixture can seal anything under one of these values, and after the run it is unrecoverable by design. A re-run mints nothing and offers an empty channel; a standalone pithy seed mints nothing either.
  7. Retargets service bindings at this environment’s copy of the callee, resolved through each Worker’s real deploy name rather than its apps/<name> directory.
  8. Binds SELF, for a project that administers itself. A Worker cannot fetch its own hostname: the subrequest loops back through the edge into the Worker it came from and hangs until Cloudflare answers 522, on a route that answers in a second and a half from outside. So a project whose root pithy.config.ts says administersItself: true gets one more services entry in every stanza this writes — SELF, pointing at the script that stanza deploys as — and the code calls itself with env.SELF.fetch(request), dispatched inside the runtime with no edge hop. A re-run retargets in place rather than duplicating, and a project that declares nothing gets no entry. The top-level stanza gets none, and that is the rule rather than an omission: the 522 is an edge behavior, and wrangler dev serves a Worker fetching its own address as an ordinary local request.
  9. Migrates, and seeds when asked. A feature also records a manifest — the resources it created and the Worker script names it wrote — so pithy feature destroy deletes exactly what was created and deployed.
  10. Stands up every kit Worker a feature composes. A feature is an environment, and it runs what an environment runs: every host its capabilities own — email’s sender, media’s enrichment, storage’s sweep, payments’ reconcile, support’s classifier, testers’ daily pass, vector’s reprocess, and the secrets manager. Each is deployed through the registry entry, resolver and gated deploy pithy deploy ships a declared environment’s with, handed the feature, so every name it is called or binds is the feature’s, its Workflows named the same way. The app Worker’s workflows bindings into the hosts are written after the deploy, and only for the hosts that deployed, so a host that failed leaves no binding for the next deploy to ship. Any host that does not deploy fails the run; the next run finishes it. An app Worker whose directory would give it a kit host’s name is refused before anything is created.
  11. Shares nothing with any other environment. The Cloudflare account and its one Secrets Store are the only containers a feature cannot have its own of, and everything inside them is split: its databases, namespaces, buckets, queues, Vectorize indexes and Artifacts namespace, its Workers and Workflows, and every store entry — a global secret’s included. Rate limiters are the one exception: features share them with each other, never with staging or production. Cloudflare keys a limiter’s counters by namespace_id across the account, so the top level’s id would have a branch spend production’s per-IP budget. Every ratelimits binding in a feature stanza gets its limiter’s fixed feature namespace: the declared namespace_id plus 1000000000, so 1001 is 1000001001 in every feature of every project. An offset cannot collide, so distinct limiters keep distinct namespaces, and it lands in a range no environment may declare. A limiter that cannot be offset — no namespace_id, one not spelled in decimal digits, or one outside 1 through 999999999 — is refused before anything is created.
  12. Answers on its own workers.dev address and nothing else. A feature stanza states routes: [], so it never inherits the top level’s custom domain, and the run says which routes it gave up rather than dropping them silently.
  13. Refuses a slug that does not fit. Feature names are never truncated, so a branch whose slug does not fit every name the feature composes is refused before anything is created, naming the longest slug the project takes at that issue. The naming rules have the budget worked out per project length.

A service binding can name a kit Worker too. Step 7 resolves an apps/ Worker through its real deploy name, and a kit Worker named by its capability (email) at the host this environment deploys for the calling Worker — its own host where it owns a binding that host binds, the shared one otherwise, and in a feature, the feature’s own host. An app declares its own bindings with pithy worker bind, and this run writes them into every stanza it generates, the feature’s included.

Each Worker’s Workflow bindings reach the host that reads its database. Every kit host a Worker composes gets a workflows entry in its stanza. A Worker that owns a binding the host binds, DB for email and audit, reaches its own host, <project>-<env>-<worker>---<capability>; every other Worker reaches the shared one. The report’s kitHosts lists each host and the Workers bound to it, and the plan under --dry-run names the same hosts. In a feature, a Worker that owns a binding a host binds gets its own feature host, <project>-f<issue>-<slug>--<worker>---<capability>, over the feature’s own copy of that binding, and its Workflow bindings reach it (naming).

The feature range is reserved in every environment, and every project. pithy provision --env <any> refuses a Worker that declares a namespace_id from 1000000000 through 1999999999, at the top level or in any stanza, before anything is created, whether or not the project has ever provisioned a feature: every feature of any project in the account binds its limiters in that range, and a declared id there would share counters with a branch. The id is read as the integer it spells, so "01031275746" is refused as 1031275746. pithy deploy refuses the same, and pithy doctor reports it.

A Worker that holds an encrypted field binds the field key, PITHY_FIELD_KEYS, in step 5, whether or not it composes secrets. A Worker that holds none does not bind it.

An encrypted field needs something to rotate its key. pithy provision --env <env> refuses a project where a Worker holds an encrypted() field and no Worker composes secrets, before anything is created, naming the Worker. The secrets manager rotates PITHY_FIELD_KEYS every 30 days, and a key nothing rotates would be minted once and kept forever. The refusal names the pithy add secrets command that composes it.

While it runs

Provisioning creates real resources over a network, one at a time. So it says what it is about to do before it does any of it, then narrates each step as it happens — a run against a slow account and a hung command are not the same thing, and a command that prints nothing until it finishes cannot tell you which one you have.

The plan comes before the confirmation, because that is the moment you are being asked to authorize real Cloudflare resources:

Provisioning staging for dash.

  databases  dash-global-email-suppressions, dash-staging-db
  buckets    dash-staging-media
  workers    board, email
  secrets    dash-staging-secrets-encryption-keys

▸ dash-global-email-suppressions...
dash-global-email-suppressions: created.
▸ dash-staging-db...
dash-staging-db: exists.

Nothing in the plan reaches your account to produce it: the resource set, the Worker set and the store entries are all resolved from your own repository, and they are the run’s own inputs rather than a second calculation of them — so a plan that named something the run then skipped would fail this project’s tests rather than mislead you.

That pairing is also what makes an interrupted run readable. Provisioning is idempotent and safe to re-run, but idempotence only helps if you know where it stopped: the last ▸ line names the resource that was in flight.

The migrations and seeds that close a run narrate the same way, in pithy migrate’s and pithy seed’s own words: ▸ DB (app) for board..., ▸ Applying 0300_auth_0001_init to DB....

Plain lines, printed once, never redrawn — so the history survives in your scrollback and in a CI log, and a non-interactive run gets the same bytes without escape codes. Under --json none of it is printed: that output is exactly one line, as it is for every command.

A manifest it could not read

An installed @pithy-sh/* package whose manifest — its pithy.manifest.json, or a companion such as pithy.mcp.manifest.json — is present and will not parse is named, with the file — above the plan, and again on stderr when the run finishes:

Provisioning staging for dash.

  @pithy-sh/email: malformed pithy.manifest.json. Its resource naming and declines went unread.
    requiredBindings[1].scope: not a known scope

  databases  dash-staging-db, dash-staging-email-suppressions

It sits above the rows because it is what puts them in doubt. The bindings themselves come from the composed capability, so the resources are still created — but two things that decide what they are called and whether they are wanted live in that file. A manifest nobody could read declares no scope, so a project-global suppression database is created per environment; and it resolves a declinedBindings entry as unrecognized, so a binding you removed is created and written back. Neither is a refusal — one broken package must not cost you every other capability’s provisioning — and both are silent without this line.

It is a defect in somebody’s package rather than a fact about your run, so the summary copy goes to stderr and the run’s own lines stay on stdout. --json carries it as manifestFaults. pithy add --list, pithy upgrade and pithy doctor report the same packages.

What it left out

A binding a Worker names in declinedBindings gets no resource created for it, and no entry in that Worker’s stanza.

A decline is the one input to this command that removes work, and removed work leaves no trace of itself: the summary lists what was made, so a decline read correctly and a decline dropped on the floor print the same bytes. So the run states what it left out, and why, one line per entry:

SUPPORT_BUCKET (r2) declined by board. Not created by this run. — Attachments are off, so nothing would ever be written to it.
ASSETS (r2) declined by board. Created anyway for collab. — no R2 for this Worker.
ASSET declined by board. Nothing it composes declares it, so nothing was left out. — no R2 in this account.
DB (d1) declined by board. auth requires it, so nothing was left out. — we use Postgres.
declinedBindings in board's pithy.config.ts cannot be read, so nothing was left out: `declinedBinding` is not a key this Worker's config declares. Did you mean `declinedBindings`?

Your own reason is printed back verbatim — it is required in declinedBindings precisely so a report can hand it back, and it carries the one fact the binding name does not.

Every line but the first says nothing was left out, and none of them is noise:

  • Created anyway for <workers>. A binding no Worker owns is one resource for every Worker that declares it, which is how two Workers share a database. One Worker declining ASSETS while a sibling still declares it leaves the resource in place and the declining Worker’s stanza without it. A line that called this a skip would send you looking for a resource that exists.
  • A decline that names nothing, or that is refused. A one-character slip in the binding name is the likeliest typo in a decline, and it resolves against nothing. So does a decline of a binding a capability requires, or of a Workflow or Durable Object. Each is reported and none is fatal.
  • A declaration that cannot be read. One typo in the block and every declined resource is created. Without this line that run is byte-identical to a project that declines nothing.

Not created by this run is the exact claim, and no larger one. Provisioning adds bindings and never removes them, so declining something an earlier run already provisioned leaves the resource in your account and the binding in the Worker’s stanza. Delete both by hand; pithy doctor names the environments the binding survives in.

Owning a binding, and --repoint

A binding a Worker lists in ownBindings gets that Worker a resource of its own, and every other binding stays shared. The report names both: each row in resources carries the Workers its id was written into, and an owned row carries its owner. An entry naming no D1, KV, R2 or queue binding the Worker composes owns nothing, and the run says so:

api lists DBB in ownBindings. Nothing it composes declares it, so it owns nothing.

A scope: "global" binding cannot be owned. It is one resource for the project by definition, so the entry is refused before anything is created, naming the binding and the capability that declares it global.

Owning a binding a kit host binds gives the Worker that host to itself. apps/two owning DB and composing email and audit has acme-staging-two---email and acme-staging-two---audit planned and bound for it, built from its own composition, origin, theme and catalogs, while every other Worker keeps acme-staging-email and acme-staging-audit. A host that binds nothing the Worker owns stays shared. The report says which Worker each host serves:

acme-staging-two's email jobs run on its own kit Worker, acme-staging-two---email, which reads its database. pithy deploy uploads it.

Audit’s checkpoint bucket and storage’s bucket are keyed to their database’s rows, so a Worker owning the database owns the bucket too, or the run is refused before anything is created: two owns DB but shares AUDIT_CHECKPOINTS., with Add AUDIT_CHECKPOINTS to apps/two/pithy.worker.jsonc ownBindings, or take DB out.

Moving a binding between shared and owned moves no rows. Listing a binding in ownBindings names that Worker a new, empty resource, while its stanza still points at the shared one; taking the entry out does the reverse. A declared environment whose stanza points a binding at that counterpart is refused before anything is created, naming the Worker, the binding, both names, and that the current resource keeps its data:

my-app-other's DB points at my-app-staging-db. This run names my-app-staging-other---db. my-app-staging-db keeps its data.
Move the data yourself if it should follow. Then run pithy provision --env staging --yes --repoint. Or put ownBindings back the way it was.

--repoint performs it, and the run says each binding it moved: my-app-other's DB now points at my-app-staging-other---db. my-app-staging-db keeps its data. Nothing is copied and nothing is deleted. For a production environment the remedy is a person’s decision rather than a command. --dry-run lists every repoint as a note, and says when the run would refuse them. A stanza pointing at anything else, a deleted database or a name chosen by hand, is written over as it always was.

The secrets it cannot create

A d1 secret — the auth session secret — is sealed under a master key that lives inside an environment’s secrets manager Worker. Only that manager can write one, and this command runs before the managers are necessarily deployed. So for a declared environment it creates none of them, and it says which, rather than reporting Provisioned prod. Migrated. for an environment that cannot serve a request.

Who can create them is not the same answer in both modes.

--env names the run that creates them, and says whose decision it is:

auth-session-secret: not created here — they need a deployed manager.
`pithy secrets provision` runs against every environment, production included. That is a person's decision, not a fix.

pithy secrets provision deploys every declared environment’s manager, production included, so after a --env staging run it is named as a person’s decision rather than a command to run.

--feature creates them the way pithy secrets provision does, when the account has a Secrets Store. A feature has its own SECRETS database, so it gets its own secrets manager: the run creates the feature’s own master key, only if absent, through the provisioner pithy secrets provision uses, deploys the feature’s manager with its other kit Workers, and then asks that manager to create every d1 secret the registry says may be generated. No token. A feature’s manager binds no Cloudflare API token and rotates nothing, so branch code never holds write access to the account’s Secrets Store. Nothing is pending:

auth-session-secret created in feature.

The feature’s own stores are the only copy, and the manager is the only writer. The CLI never holds a value: the manager probes before anything is minted and writes with create, which never replaces a secret that is there, so a re-run from any machine changes nothing, and a probe that fails fails the run rather than reading as an absence. Nothing depends on which run created the key. The manager seals every row under whatever key the store holds, so a run that fails anywhere after the key exists — a migration, a host deploy, the mint itself — is finished by the next one. Two runs at once leave one value: the manager’s create is a single insert-if-absent, and the loser is told the secret already exists.

Without a Secrets Store there is no key to give a manager, and the shortfall names the run that would create them:

auth-session-secret: not created here — they need a deployed manager.
Run pithy provision --feature with SECRETS_STORE_ID set to create them.

A cf-secrets-store secret the registry calls arbitrary — the email link-signing key — is not on that line in either mode. The account’s Secrets Store answers whether the entry exists, so it is created and bound in the same pass, in the branch’s own scope for a feature.

pithy secrets provisionspans the environments the project declares, deploying a manager into each. A branch is not declared, so that command does nothing for one; pithy provision --feature is what gives a branch its manager. --json carries the distinction as pendingSecretsRemedy — the command that creates them, or the person’s decision it is.

Production

--yes is not enough for production, and never becomes enough. A production environment — the built-in prod and production, plus anything the project declares in seed.productionEnvironments — additionally requires the exact phrase:

pithy provision --env prod --yes --confirm "yes, i really want to provision prod"

The phrase names its environment, so one typed for staging cannot be pasted into a command targeting prod. Interactively the CLI asks for it; under --json it must arrive by flag, so a headless production provision happens only when a person wrote the phrase into the pipeline.

Under --json, --no-input or PITHY_NONINTERACTIVE=1 the phrase must arrive by flag. Without it, or with a wrong one, the run is refused core/person_required, exit 5, and the action names --confirm: the phrase is a person’s to give, so an agent stops and asks rather than trying variations.

Seeing it first: --dry-run

--dry-run runs the provisioning itself — the same declines, names, scoped script names, service targets and stanza writer — against a private copy of the project, and against an account it only reads.

  • Resources. Each is looked up by name, exactly as the run looks it up. One that exists is adopt, with its id; one that does not is create, and nothing is created — the copy’s config gets a placeholder id where the new one would land.
  • Files. Each Worker’s wrangler.jsonc edit, as a diff of the bytes the run writes. For --feature, the generated config under .wrangler/.
  • Secrets. Each cf-secrets-store secret it would bind, and each it would mint, by name and entry. The Secrets Store is asked whether an entry exists and is written nothing.
  • Migrations. A database it would create has applied nothing, so every migration it carries is listed. An adopted one is read for what it has applied.
  • Repoints. Each binding the run would move between shared and owned, as a note naming both resources. Without --repoint a last note says the run refuses them and creates nothing.
  • What it does not run. Seeding, and --feature’s kit Worker deploys, are named in the plan rather than run.

It asks for no confirmation and no production phrase, because nothing it does needs one. Every refusal the run makes before its first write still stands, and comes first. Without CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN there is no plan: the dry run is refused core/precondition_failed, exit 3, exactly as the run would be.

$ pithy provision --env staging --dry-run
Would edit apps/board/wrangler.jsonc.
Would create d1 replay-staging-db (DB, staging).
Would adopt kv replay-staging-cache (CACHE, staging).
Would apply 1000_app_0001_things to app (DB, staging).
Dry run. Nothing written.

Deploy refuses, it does not provision

pithy deploy --env staging checks first, and refuses with the command to run when a binding has no resource behind it:

staging declares bindings with no Cloudflare resource behind them: board.DB (d1).
Run pithy provision --env staging --yes, then deploy.

A deploy that silently created account resources would be hard to review, and these are the resources worth reviewing. pithy doctor reports the same state without being asked.

Teardown

pithy feature destroy reverses a branch’s environment, because a branch’s environment is disposable.

For a declared environment there is none, deliberately. Staging and production are not disposable, and the one-word difference between the two is not a difference a flag should carry. Delete them in Cloudflare, by hand, on purpose.

--json

$ pithy provision --env staging --yes --json
{"command":"provision","env":"staging","resources":[{"kind":"d1","binding":"DB","name":"replay-staging-db","id":"9f0…","created":true,"workers":["replay-board"]}],"workers":[{"worker":"replay-board","name":"replay-staging-board"}],"services":[],"secretBindings":[],"declined":[],"ownership":[],"repoints":[],"manifestFaults":[],"configs":[{"worker":"replay-board","path":"apps/board/wrangler.jsonc","ids":3}],"committed":true,"pendingSecrets":["auth-session-secret"],"pendingSecretsRemedy":"`pithy secrets provision` runs against every environment, production included. That is a person's decision, not a fix."}
KeyTypeMeaning
command"provision"The command that produced the line. The same for both modes
envstringThe environment provisioned — a declared name, or feature
resourcesobject[]Every resource, in provision order
resources[].kind"d1", "kv", "r2" or "queue"The Cloudflare resource type
resources[].bindingstringThe Worker binding this resource backs, e.g. DB
resources[].namestringThe full Cloudflare resource name
resources[].idstringThe Cloudflare-assigned id — a D1 uuid, a KV namespace id, a queue id, or the bucket name for R2
resources[].createdbooleanTrue when this run created it; false when a resource of that name already existed and was adopted
resources[].ownerstringThe apps/<owner> Worker it belongs to, from that Worker’s ownBindings. Absent on a resource every declaring Worker shares
resources[].workersstring[]The Workers whose stanza its id was written into, by deploy name: every Worker sharing it, or the one that owns it
workersobject[]Each Worker and the script name it deploys under in this environment
workers[].workerstringThe Worker’s own deploy name — its wrangler.jsonc name
workers[].namestringThe scoped script name written into env.<name>. A declared environment keeps the name its stanza declares, else <worker>-<env>; a feature composes <project>-f<issue>-<slug>--<app> from the apps/<app> directory, so the project appears once
servicesobject[]Each service binding and the Worker it now targets in this environment
services[].bindingstringThe binding name
services[].servicestringThe script the binding was retargeted at
secretBindingsobject[]Every cf-secrets-store secret this environment declares
secretBindings[].secretstringThe secret’s registry key — the name pithy secrets create takes
secretBindings[].bindingstringThe Worker binding it is read through: the registry key in SCREAMING_SNAKE_CASE, so email-link-signing-key binds as EMAIL_LINK_SIGNING_KEY
secretBindings[].entrystringThe Secrets Store entry it resolves to in this environment
secretBindings[].boundbooleanTrue when the entry exists and the binding was written. False when the secret is declared and its entry has never been created — binding it anyway would make wrangler refuse the whole config
secretBindings[].mintedbooleanTrue when this run created the value, because the registry declared it may be minted. False on a re-run, which leaves an existing value alone
declinedobject[]One entry per Worker whose declinedBindings has something to say. Empty for a project that declines nothing, which is most of them
declined[].state"read" or "invalid"Whether that Worker’s declaration parsed. invalid means it did not, so nothing was left out for that Worker and every declined resource was created
declined[].workerstringThe Worker’s own deploy name
declined[].problemstringinvalid only: what is wrong with the declaration, naming the entry
declined[].declinesobject[]read only: every entry in that Worker’s declaration, resolved
declined[].declines[].state"honored", "required", "undeclinable" or "unrecognized"Only honored left something out. The other three are reported so a decline that changed nothing is not silent — the likeliest typo in a decline is in the binding name, and it lands on unrecognized
declined[].declines[].namestringThe binding name, as you wrote it
declined[].declines[].type"d1", "kv", "r2", …The kind of resource it refers to. Absent on unrecognized, which names no binding to have a kind
declined[].declines[].capabilitystringThe composed capability that declares it. Absent on unrecognized
declined[].declines[].reasonstringYour own reason, verbatim
declined[].declines[].wantedBystring[]honored only: other Workers that declare the same binding and did not decline it. Non-empty means the resource was created anyway — a binding no Worker owns is one resource for every Worker sharing it. Only Workers that share it count: a sibling that owns the binding has its own resource, and a Worker declining a binding it owns declines its own, so nothing is created for it. Only this Worker’s stanza leaves it out
ownershipobject[]One entry per Worker that lists ownBindings. Empty for a project that owns nothing
ownership[].workerstringThe Worker’s own deploy name
ownership[].ownedstring[]The bindings it owns a resource for
ownership[].unrecognizedstring[]Entries naming no D1, KV, R2 or queue binding it composes. They own nothing
repointsobject[]--env --repoint only: each binding whose stanza pointed at its counterpart and now points at the resource this run names. Under --dry-run, every repoint the run would make
repoints[].workerstringThe Worker’s own deploy name
repoints[].bindingstringThe binding
repoints[].kind"d1", "kv", "r2" or "queue"The resource type
repoints[].currentstringThe resource the stanza pointed at, by name. It keeps its data
repoints[].nextstringThe resource it points at now
manifestFaultsobject[]Installed packages shipping a manifest that is present and unusable. Project-wide, not per Worker. Empty on a healthy install
manifestFaults[].packagestringThe package the manifest was read from, as an adopter names it: @pithy-sh/audit
manifestFaults[].filestringThe manifest file within that package: pithy.manifest.json, or a companion such as pithy.mcp.manifest.json
manifestFaults[].reasonstringWhy it could not be used — the schema’s refusal text, or the errno where the file would not open
configsobject[]Where the ids were written, one entry per Worker
configs[].workerstringThe Worker’s own deploy name
configs[].pathstringThe file written, relative to the project root
configs[].idsnumberHow many binding ids landed in it
committedbooleanWhether those files are committed. true for --env, false for --feature — the one field a pipeline reads to know it has nothing to commit
pendingSecretsstring[]The d1 secrets this run declares and did not create. For --env, their values are sealed under a master key inside the environment’s secrets manager, which this command runs before deploying. For --feature, every one the feature’s own manager accounted for is left off. Empty when the project declares none
featureSecretsobject[]--feature with a Secrets Store only: each d1 secret the feature’s shared manager accounted for. Names, never a value
featureSecrets[].namestringThe secret’s registry name
featureSecrets[].createdstring[]["feature"] when this run created it; empty when it was already there
hostsobject[]--feature only: every kit Worker the feature stood up for itself, one row each, as pithy deploy --json reports kit
hosts[].capabilitystringThe capability that owns the kit Worker
hosts[].ownerstring, optionalThe apps/ Worker this is the own host of. Absent for the feature’s shared host
hosts[].workerstring or nullThe deployed script name, null when the run never got far enough to derive one
hosts[].outcomestring"deployed", "unchanged", "skipped" or "failed"
hosts[].reasonstringOne sentence saying why
kitHostsobject[], optional--env only: every kit host this run bound a Worker’s Workflow bindings to, one row per host
kitHosts[].capabilitystringThe capability that owns the host
kitHosts[].ownerstring, optionalThe apps/ Worker whose own host this is, because it owns a binding the host binds. Absent for the shared host
kitHosts[].scriptstringThe host’s script name in this environment, <project>-<env>-<capability> or <project>-<env>-<owner>---<capability>
kitHosts[].workersstring[]The Workers whose Workflow bindings now reach it
routesDroppedobject[]--feature only, and only when there were any: each Worker’s route patterns the feature stanza gave up, as { worker, routes }
pendingSecretsRemedystring or nullWhat does create them. For --env, pithy secrets provision said as a person’s decision — it runs against every environment, production included; "pithy provision --feature with SECRETS_STORE_ID set" for --feature, whose own run creates them once it has a Secrets Store. A pipeline branches on this rather than on the mode

Every line also carries these, beside the keys above:

KeyTypeMeaning
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
dryRunbooleanWhether this was --dry-run. Nothing was created, written or migrated when it is true, and a resource it would create carries its placeholder id
planobjectPresent only under --dry-run: the resources to create or adopt, the config edits with their diffs, the secrets to bind or mint, and the migrations to apply
nextobject[][{ command, why }]: pithy deploy --env <env> — --env feature for --feature — when a Worker this run named in workers has no deployed script on the account. Absent when every one is deployed, when the account could not be asked, and under --dry-run; never empty

--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. The plan the confirmation is hung off is prose, so it is not printed; --dry-run --json is how a program reads a plan.

KeyTypeMeaning
commandstring"provision", on every record
schemaVersionintegerThe same version the document carries
eventstring"start" as a step begins, "settled" as it ends
whatstringstart only: what is being worked on — a resource’s name, a migration, a seed set, a kit Worker
bindingstring, optionalstart of a resource: the binding it backs
kindstring, optionalstart of a resource: "d1", "kv", "r2" or "queue"
linestringsettled only: the line a person would have read for it, without color
resourceobject, optionalsettled of a resource: its row, exactly as resources[] lists it
kitobject, optionalsettled of a feature’s kit Worker: its row, exactly as hosts[] lists it

A failure inside the command ends the stream with no document, and the {"error": …} line goes to stderr as it always does.

$ pithy provision --env staging --yes --json --events
{"command":"provision","schemaVersion":2,"event":"start","what":"replay-staging-db","binding":"DB","kind":"d1"}
{"command":"provision","schemaVersion":2,"event":"settled","line":"replay-staging-db: created.","resource":{"kind":"d1","binding":"DB","name":"replay-staging-db","id":"9f0…","created":true}}
{"command":"provision","schemaVersion":2,"event":"start","what":"Applying 1000_app_0001_things to DB"}
{"command":"provision","schemaVersion":2,"env":"staging","resources":[…],…}

Errors

Exit 0 on success. Non-zero with a problem line and an action for: no mode or both modes, a missing declaration, missing credentials, a branch that is not a feature branch, an unconfirmed production run, an encrypted field in a project that composes no secrets, a scope: "global" binding in ownBindings, a stanza pointing a binding at its counterpart without --repoint, or a service binding naming a Worker this project does not have — each refused before a single resource is created.

Examples

pithy provision --env staging --yes
pithy provision --env prod --yes --confirm "yes, i really want to provision prod"
pithy provision --feature --json
ESC