pithy secrets

Declare, write, rotate, list and edit a project’s secrets — and stand up the per-environment infrastructure that stores them. This is the command surface; the secrets capability is what reads them at runtime.

Synopsis

pithy secrets create <name> [--env <env>] [--worker <name>] [--json]
pithy secrets update <name> [--env <env>] [--worker <name>] [--json]
pithy secrets rotate <name> [--env <env>] [--worker <name>] [--dry-run] [--json]
pithy secrets rm <name> [--env <env>] [--worker <name>] [--backend <d1|cf-secrets-store>] [--json]
pithy secrets ls [--all] [--json]
pithy secrets tables [--env <env>] [--worker <name>] [--json]
pithy secrets edit [--json]
pithy secrets retire-version <v> --env <env> --past-guard
pithy secrets verify [--env <env>] [--worker <name>] [--no-sweep] [--json]
pithy secrets provision [--json]
pithy secrets deprovision --env <env> [--keys] [--destroy-retained <n>] [--json]

Its Worker deploy is gated. The manager Worker is deployed carrying a stamp naming 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, an unreachable account — deploys. pithy deploy --env <env> ships the same Worker without provisioning anything else, and --kit --force re-uploads it regardless.

Flags

SubcommandFlagMeaning
create, update, rotate, rm<name> (positional, required)The secret’s name — a registry entry
create, update, rotate, rm--env <env>Target environment for an environment-scoped secret. Not dev
create, update, rotate, rm, verify--worker <name>Write or verify through this Worker’s manager. A Worker that lists SECRETS in ownBindings has a vault and a manager of its own, <project>-<env>-<worker>---secrets; any other Worker reads the shared vault, and naming it changes nothing. Without the flag, the shared manager. See a vault a Worker owns
rm--backend <d1|cf-secrets-store>Remove the value from this store instead of the one the registry names — for a value a secret left behind when its declaration moved. Needs --env
rotate--dry-runShow the plan and write nothing. Resolves the declaration and says what would happen; calls no issuer. Still needs the Cloudflare credentials, and the Secrets Store id for a cf-secrets-store secret, so a dry run refuses where the real run would
ls--allAlso list the secrets this configuration will never read, each with the reason
tables--env <env>The environment whose vault to read: dev, staging, prod, or one declared in pithy.config.ts. Default dev
tables--worker <name>Read one Worker’s declarations instead of every Worker’s under apps/
retire-version<v> (positional, required)The field-key version to retire, as the guard lists it. Never the current one
retire-version--env <env>Required. The environment whose field key it is
retire-version--past-guardRequired, and irreversible. Retire the version although the guard is not clean. Every ciphertext still under it becomes unopenable
verify--env <env>Verify one environment instead of every declared one
verify--no-sweepSkip the Secrets Store listing and verify the stores alone. Sweeping is the default
deprovision--env <env>Required. The one environment to tear down. There is no default and no “all”
deprovision--keysAlso delete that environment’s master key. Irreversible: every stored secret becomes undecryptable
deprovision--destroy-retained <n>Destructive. Delete a vault that still holds rows. <n> must equal the count the refusal printed
all but retire-version--jsonMachine-readable output. Default false. retire-version declares it only to refuse it

--env here is the managed set — every environment the root pithy.config.ts declares — not the three --env takes elsewhere. dev is local-only, so it is refused with a sentence pointing at pithy dev, and an environment the project does not declare is refused by name with the ones that are.

--env on a global secret is refused, not ignored. A global secret is defined by holding one value everywhere, so naming an environment asks for something the scope does not permit.

payments-provider-credentials is global. It holds one value across every environment, so --env cannot narrow it.
Run it again without --env to set it in every environment.

The re-run is the confirmation, so there is no prompt and no --yes. It could have printed that sentence and proceeded — but an operator who typed --env staging would then have had prod rewritten by a command they did not intend, with a notice printed after the fact as cover. One extra command is cheaper than that, every time. rm gets the same refusal, and it matters more there.

--env on tables is the ordinary set, dev included, because a declared table’s local rows are as real as a deployed environment’s.

Every subcommand reads the project’s registry: each Worker’s, merged by secret name. --worker on create, update, rotate, rm and verify decides which vault the value goes to, not which declarations are read.

A vault a Worker owns

A Worker that lists SECRETS in its pithy.worker.jsonc ownBindings keeps its secrets in a database of its own, and reads nothing from the shared vault. It gets a manager of its own, <project>-<env>-<worker>---secrets, and every write it reads goes through that manager’s Workflow, <project>-<env>-<worker>---secrets-write. So pithy secrets create STRIPE_KEY --env staging --worker two is how two gets a value; without --worker, the value goes to the shared vault, which two never reads.

--worker naming a Worker that does not exist is refused with No worker named "<worker>". and the project’s Worker names; naming one that does not compose secrets is refused with <worker> does not compose secrets. Naming a Worker that shares the vault writes through the shared manager, exactly as leaving the flag off does.

Both vaults are sealed under the environment’s one master key. The shared manager rotates that key, the field key and every cf-secrets-store secret, and its at-rest rotation re-seals every owned vault beside its own before it retires a version. A Worker’s own manager rotates only the d1 values in its own vault, and holds no Cloudflare API token. So pithy deploy redeploys the shared manager whenever it deploys an owner’s, even when every Worker composing secrets owns its vault, which keeps the vaults it binds current; with no shared manager on the account it fails, naming pithy secrets provision.

What it does

The registry is the definition. pithy secrets never invents a name — a secret must be declared by a capability the Worker composes, and an undeclared one is refused before anything is sent. Every capability’s declarations count, not just the secrets capability’s own: auth’s session secret, OAuth credentials and Play Integrity service account, email’s link-signing key and payments’ provider credentials are all declared by the capability that reads them, and all of them are yours to create here.

A value never comes from a flag. create and update read the value from stdin when it is piped, and from a masked prompt when one can be drawn — and refuse when neither is available, rather than reading your terminal in silence. A flag would leave a live credential in shell history and in every process list on the machine. Nothing here prints a value back, on any subcommand, in either output mode.

A json secret is asked for one field at a time. On a terminal, create and update walk the entry’s schema and ask per field, using that field’s own description as the question. Every field is masked, with no exceptions: these values arrive by paste, so masking costs nothing an operator was going to use, and a field wrongly treated as public is a credential in a screen share. An empty answer is not a value — it is left out, and a field the schema requires is then named on the problem line by the same validation that checks a piped document, so you know which of six questions to answer again. The name only, never the value.

Only the blocks this project configured are offered. payments-provider-credentials holds one block per payment rail, and the schema knows five are possible where only pithy.config.ts knows which are on. One configured rail is named and asked for; several become a checkbox of those rails and nothing else. A rail that is off is never offered and never written, and a block you do not choose is absent from the stored value rather than stored empty.

An update replaces the whole secret, and it says so every time. The value is sealed under a master key the CLI cannot read — the read seam answers whether a name is there, never what is under it — so it cannot merge what you type into what is stored, and it cannot show you what is stored either. Anything you are not asked about is gone: a block for a rail you switched off months ago is not in the prompts, so it is not in the value that gets written. That is stated on every interactive update, including the one-rail project that never sees a checkbox. Pipe the whole document when you need to keep a block you are not editing. A schema this cannot render — a union, a record, a list of objects — falls back to the single prompt for the whole document. Refusing to ask is fine; guessing a shape is not.

A field is asked for on its own line only once somebody has said it fits on one. A masked prompt reads one line, and a longer paste is silently truncated to one: the first line if your terminal sends carriage returns, the last if it sends newlines. The rest is gone, the fragment is a non-empty string, so the bundle passes validation and nothing goes wrong until a signature check does, in production. So every string field of a json secret declares whether its value can span lines, and a field holding a PEM — Apple’s App Store Connect key, Google’s service-account key — says that it can. A secret with such a field among the blocks you configured is asked for as a single JSON document instead, where \n is escaped and nothing splits, and the CLI names the field that is the reason. A field that has declared nothing is treated the same way, because undeclared and safe are not the same thing.

Piped input is unchanged by any of it. A pipe takes one whole JSON document, exactly as it always has. Per-field prompting is the interactive path only, because the non-interactive one is what CI and agents drive. What decides which of the two you get is stdin, and only stdin — a pipe, a heredoc, a file, < /dev/null, anything that is not a terminal. Whether a prompt can be drawn is a separate question with separate inputs: --json off, and a terminal on stdout.

So there is a third case, and it says so rather than guessing. stdin is your terminal, so no document is coming; and the run cannot draw a prompt, because you passed --json, --no-input or PITHY_NONINTERACTIVE=1, or redirected the output to a file. Reading your terminal anyway would be an unmasked, unannounced request for a credential, and waiting on it would be a hang. It refuses instead, and names the way in that works from there. The command it names is your own run again, with every flag you gave it:

$ pithy secrets create STRIPE_SECRET_KEY --env staging > create.log
No value was piped for 'STRIPE_SECRET_KEY', and this run cannot prompt for one — stdout is not a terminal, --json was passed, or prompts are forbidden.
  Pipe the value in: printf '%s' "$VALUE" | pithy secrets create STRIPE_SECRET_KEY --env staging

create, update and rm are audited — secrets/set, secrets/rotated, secrets/removed — recording the secret’s name, its backend, and the environments reached, never its value. A write that fails is audited too, with the environments it reached before it failed.

Which environments a write reaches is the registry’s decision rather than the flag’s: an environment-scoped secret reaches exactly the one you named; a global one in D1 fans out across every managed environment; a global one in the Cloudflare Secrets Store is written once, canonically.

Where a write lands is the registry’s decision too, and the same one. A d1 secret is dispatched through that environment’s manager Workflow, which encrypts it under a master key that never leaves the Worker. A cf-secrets-store secret is written straight into the account’s Secrets Store, at the <project>-<env>-<secret> entry that Worker’s stanza binds — composed by the same code pithy secrets provision looks it up with, so what you write is what gets bound. create refuses a name that is already there and update refuses one that is not, in both stores alike.

And what the entry holds is the registry’s decision as well. Nearly every secret is stored as a versioned envelope and read back through it, which is what makes a value rotation expressible. A bootstrap secret is not: it is read straight off its binding by code that runs before the store that decoder needs is open, so its entry holds the value, with nothing around it. The rule is the one the dev secrets file already states — the destination receives the payload, not a wrapper — and it is why SECRETS_ENCRYPTION_KEYS can be parsed at boot at all.

A global CF-Secrets-Store write reports the entry, not the environment it went through. There is one account-level entry and every environment’s stanza binds it, so the line names what actually changed:

payments-provider-credentials written to one account entry, read by staging, prod.

Under --json that is environments naming every environment that reads it, plus "accountEntry": true. The environment the write was dispatched through is an implementation detail — the canonical one, picked so the same manager always performs it — and reporting it alone understated the change by every environment but one.

create writes the entry; it does not write the stanza. Follow it with pithy secrets provision, which binds on existence — an entry you supplied a moment ago is bound exactly like one it minted itself. pithy doctor and pithy provision both print that pair for a secret whose entry is missing.

rm on a store-backed secret deletes the entry, and says what it leaves behind. The entry is the value the Worker reads, so deleting it is the revocation; the Worker’s wrangler.jsonc still carries a secrets_store_secrets line binding it — under the secret’s name in SCREAMING_SNAKE_CASE, EMAIL_LINK_SIGNING_KEY for email-link-signing-key — and nothing in the kit removes one. Wrangler refuses a config naming an absent entry, so the next deploy of that Worker fails until you delete the binding or supply the value again, which the command tells you on the line under the removal.

SECRETS_ENCRYPTION_KEYS is refused in all three. It is the master key every other secret in that environment is sealed under: replacing it orphans each of them and removing it loses them. pithy secrets provision creates it when it is absent, and that is the only thing that writes it.

A global D1 write is the one fan-out, and it is not a transaction. Each environment is a separate Workflow in a separate Worker; there is no rollback across them, and a compensating write is itself a Workflow that can fail. So the guarantee is narrower than all or nothing, and it is stated rather than implied: no ordinary command can create a split, because a narrowed global write is refused before anything is dispatched. A fault part-way through still can, and when it does the command names the environments it reached before it failed:

partner-webhook-secret written to staging, canary before this failed.

Under --json that is one line with "interrupted": true, environments naming only what landed, the error line on stderr, and a non-zero exit by the failure’s class. Nothing reports success.

Moving a secret off D1

A declaration can change its backend between releases, and the value it held does not move with it. email-link-signing-key did: it was an encrypted row in each environment’s D1 vault, and it is now a Secrets Store entry per environment. The vault is where a rollback, a seed --redo or a teardown reaches once an operator agrees to it, and on one project a staging rollback took the key. A Secrets Store entry lives outside every D1, so none of them can.

pithy doctor reports a project that still holds it, and names the removal. Moving a key that has signed live mail invalidates those links. Every tracking and unsubscribe link already in an inbox was signed with the D1 value. The only way to keep one verifying would be to carry that value into the new entry as a previous version — and it cannot be carried: it is sealed under a master key that never leaves the environment’s manager Worker, so no command reads it back out. Links minted before this release also name no audience, which the verifier now requires, so a carried key would not save them either. Those links answer email/invalid_token from the moment the new entry is deployed. For elective mail that includes the one-click unsubscribe link; an opt-out that arrives another way still belongs in the suppression list. An environment that has sent no tracked or elective mail loses nothing.

The move, for each environment:

  1. pithy secrets provision — creates the Secrets Store entry, <project>-<env>-email-link-signing-key, with a fresh value, and binds it in the app Worker’s wrangler.jsonc. An entry that already exists is never replaced.
  2. pithy email provision — redeploys the email host bound to the same entry, in every declared environment. The host signs; the app Worker verifies. Both must bind it.
  3. pithy deploy --env <env> — ships the app Worker with its new binding. From here, new links sign and verify with the new key.
  4. pithy secrets rm email-link-signing-key --env <env> --backend d1 — removes the row nothing reads. A plain rm routes by the declaration and would delete the live entry instead; --backend names the vault, one environment at a time, and is refused for anything but a removal.

pithy doctor is clean for that environment once the entry exists and the row is gone.

What --backend does not do. It removes a value from a store; it never writes one where the declaration does not read it, and it never picks the environments for you. It sees the one name you give it — the vault cannot be listed, so a secret some other declaration moved off D1 is found by its own check or not at all.

rotate

A registry entry says how its secret is replaced, and rotate branches on that declaration and on nothing else — never on a list of names. Rotating one end to end walks a real entry through it.

DeclarationWhat happens
localThe kit produces the value, so it produces another. Minted here, written through the same manager Workflow every other write goes through
providerThe issuer is called and returns the successor. A provider secret with no rotator is refused by name, with both ways out
manualA human, in somebody else’s console. It prints the console, the page, and the pithy secrets update that records the result, and calls nothing. It exits 0 and never prints Done. — nothing was done

A rotation writes wherever the registry says the secret is held — the same routing create and update use — and everything refusable is refused before the issuer is called. That includes the destination’s own refusals, on either backend: a store that cannot be reached, an account with no Secrets Store, a manager Workflow that was never deployed, and an update of a secret that is not there. All of them are knowable in advance, and discovering one at the write is a credential rolled at the issuer whose successor is then lost.

--dry-run resolves the declaration and stops. It reaches no account, needs no credentials, and rolls nothing — which is what makes it the thing to type first at 2am, when the question is is this one rolled at somebody else’s API, or minted here?

There is no --all, and that is a decision. The case that wants one is real: somebody has left, and every credential they could have seen needs rolling today. Two things argue against a flag. The blast radius is the obvious one — the failure below does not average out over ten secrets, it is ten chances to strand a live credential in one invocation, at the hour an operator is least able to read carefully. The second is decisive: the precedent for a fleet-wide rotation is more than one confirmation plus an audit entry naming the operator, and the CLI cannot honor the second half. A CLI audit resolves its actor from the Cloudflare API token, so the one act most certain to be reviewed afterwards would be recorded as somebody with the token. What the case gets instead is pithy secrets ls and a shell loop, which forces you to see the list before you roll it.

The failure this subcommand is built around

A provider roll succeeds and the store write fails. The old credential is dead at the issuer, the new one exists only in the process that received it, and the environment is holding something that no longer works.

Nothing repairs it by trying harder at the roll — a second roll issues a third credential and loses the second, so the retry meant to save it is what destroys it.

So the ordering is the design:

  1. Every refusal happens before anything is called. An undeclared rotation, a provider secret with no rotator, a keyspace, the master key, missing credentials — each is answered with nothing rolled and nothing written. A refusal arriving after a roll would be the worst of both.
  2. The value is produced once, and never again for any reason.
  3. The store is retried against that value — three attempts, the same string every time. There is no path from a failed store back to a fresh roll.

The report is per secret and never in aggregate, and the word rotated is printed only where a value landed. The failure exits 5:

REPLAY_PROVIDER_TOKEN was rolled at cloudflare and its new value was not stored. prod holds a credential cloudflare has retired.
The new value is gone. It existed only in this process, and printing it would leave a live credential in your shell history. Roll it again at cloudflare, then record it with pithy secrets update REPLAY_PROVIDER_TOKEN --env prod.

Exit 5 is its own status: it needs a person. It is the kit-wide code for that, and secrets/rotation_unrecorded is in that class. An ordinary failure — a local mint whose store refused, a refusal, a missing token — exits by its own kind, and the previous credential is still live, so the command can be run again. Exit 5 means it is not, and nothing automated will fix it. A script cannot tell those apart from a message, and the two need opposite reactions.

What happens to the value, said plainly

It is discarded. Not printed, not written to a file, not put in the audit trail, not returned to a caller. The rotation result has no field that could carry one, so this is structural rather than a habit.

That is a real cost, and the alternative is worth stating rather than implying there wasn’t one. Printing it would put a live production credential in shell scrollback, in the CI log, in the terminal-recording buffer, and in whatever ships those elsewhere — permanently, for the most sensitive value this command touches. Writing it to a file is the same leak with a filename. Against that, a rolled-and-unrecorded credential is an outage with a known remedy the declaration can name.

A rotator that throws is reported differently, and the difference is not cosmetic. A rotator that returned and a store that refused means the credential was rolled. A rotator that threw means it may have been — the call reached the issuer and the answer did not. Both exit 5 and both need a human at the issuer, but only one may be described as rolled, and a report that says so of both is wrong half the time about the one fact being acted on. So the second says may have been rolled and its remedy starts with checking rather than with rolling again, because rolling again on an issuer that already rolled produces a second orphan.

Two gaps, named rather than left to be discovered. Nothing here verifies the new value against the issuer before treating it as current. And a crash between the roll returning and the store accepting leaves the same state with no report at all — that window is far smaller than the store’s, and it is not zero.

The rotation is recorded, whichever path ran it

A rotation opens a row in that environment’s history before anything is rolled, and closes it after — so a rotator that never returns still leaves a trace, and a rotation that succeeded advances lastRotatedAt.

A global secret opens one row per environment, and each closes against what that environment actually got: a fan-out that reached staging and stranded prod is a success in one history and an incident in the other. A row records what caused it, so a first write and a replacement stay legible as different events. pithy secrets update is a write, not a rotation, and does not advance the clock.

Bookkeeping never decides whether a credential is replaced. A manager that cannot be reached costs the row and not the rotation.

Unattended rotation

A secret can say how often it rotates: rotateEveryDays on its registry entry. Until now that was an expectation — doctor and the status read called the secret overdue, and nothing replaced it. Now it is also the period. Each environment’s secrets manager checks it every night at 03:00 UTC, and rotates every secret whose period has passed, by itself. The manager never reads pithy.config.ts, so it learns the schedule when it is deployed: pithy secrets provision and pithy deploy stamp it, and a period you add or change takes effect on the next deploy.

What the cron does follows the entry’s rotation, and nothing else.

  • local rotates. The kit minted the value, so it mints another, through the same function pithy secrets rotate calls.
  • provider rotates only with a rotator attached to the entry. A rotator is code, and the manager is a prebuilt Worker that never loads pithy.config.ts, so today a provider secret is reported overdue and left alone.
  • manual never rotates. It is reported overdue, the way it always was. So is an entry that declares no rotation at all: nobody has said how it is replaced.

A secret the cron rotates must be able to survive it. defineSecretRegistry refuses, where the author is: a period on a rotatable: false entry, a keyspace, or the master key; a period with no overlap; an overlap shorter than its declared minimum, or as long as the period; a local secret minted from a structure the cron cannot produce; and a global secret in D1, which is a sealed copy in every vault that one manager cannot reach. An overlap on a rotatable: false entry is refused whether it rotates or not: a secret that keeps one version has nothing to overlap. A global secret in the Secrets Store is one entry, and only the last declared environment’s manager rotates it. Staging’s never does, whatever its clock says.

"partner-webhook-secret": {
  backend: "d1",
  scope: "environment",
  rotatable: true,
  valueType: "text",
  devValue: "random",
  origin: { kind: "minted", recipe: { kind: "random", bytes: 32, encoding: "base64url" } },
  rotation: { kind: "local" },
  rotateEveryDays: 90,
  overlap: { days: 7, minimumDays: 7 },
},

The overlap is how long the previous version keeps verifying. A rotation adds a version beside the current one; it does not replace the envelope, which is what update does. The new version becomes current an hour later, the longest any Worker may cache a secret. By then every isolate holds it as a key it verifies, so nothing signed under it fails on an isolate whose cache is older than the rotation. The previous version stays for overlap.days, so a cookie, a link or a signature issued under it still verifies. Then the rotation retires it. minimumDays is the floor its owner states: the lifetime of the longest-lived thing issued under one version. auth-session-secret declares its session lifetime — seven days by default, and longer when sessionExpiresIn is. email-link-signing-key declares ninety, the default link lifetime.

Some values have no lifetime to wait out. Better Auth seals the JWKS private keys under the session secret, and a key never expires. So an entry names what is sealed under it at rest — overlap.reencrypt: ["auth-jwks"] — and retirement waits for each one. The auth Worker moves its keys under the new version and records that it has, once for each database it keeps them in, in the secrets database’s pithy_secrets_reencryptions. Two auth Workers over two databases are two records, and retirement waits for both. Retirement checks once a day for a week. If a dependent never reports, the previous version is kept, the rotation history gains a failed row with the code not-retired, and doctor says which secret. Keeping a version too long costs an envelope one entry larger. Retiring it too soon costs every key sealed under it.

A session survives it. Better Auth signs its session cookie with the current version alone. So the auth Worker checks a cookie, or a signed bearer token, that fails under the current version against every version it still holds, and re-signs it under the current one. The response hands back the re-signed credential — a Set-Cookie, or set-auth-token for a bearer client. A session in use is carried across on its next request. One not used for the whole overlap has expired anyway. Turn it on with auth({ sessionSecretRotateEveryDays: 90 }); the kit turns nothing on for you. auth() refuses the period beside twoFactor(): its TOTP secrets and backup codes are sealed under the session secret, and nothing moves them before a retirement.

The first tick records a baseline, not a rotation. A secret the schedule has never seen gets a baseline row, and its period starts counting from that night. Adding a period to a secret that has existed for a year does not replace it at 03:00.

Every run is recorded. The rotation opens its row before the roll and closes it after, with trigger cron, so lastRotatedAt moves and the secret stops reporting overdue. The value is minted and written inside the manager, and never journalled. A failure is a row with a code — never the exception — and it appears in the status read as lastFailure, and in pithy doctor under Secret rotations:. The manager composes no audit recorder, so its secrets/rotated and secrets/version_retired events are structured lines in that Worker’s logs, with the code and never a value.

Two crons, two different things. The at-rest rotation, on rotationIntervalDays, re-encrypts every row of the vault under a fresh master key. It changes no secret’s value. Value rotation, on each entry’s rotateEveryDays, replaces one secret’s value and changes no key. Both run from the same nightly trigger, and neither waits for the other: a failure in one never stops the other.

pithy secrets rotate does not keep an overlap. It writes the new value as update writes one, and the previous version is gone when it lands. Use it when the old value must stop working now. Leave the period to the cron when it must not.

ls, edit, provision, deprovision

ls lists the declared names with their routing facts, offline. It reads the registry and nothing else — no credentials, no network.

It lists the secrets your configuration actually uses. A capability declares its secrets whether or not you use them — auth declares five OAuth credentials whichever providers you enabled, and a Play Integrity service account whether or not any environment allows an Android app; support declares its R2 credentials whether or not anything will ever write to the bucket — and the ones your configuration will never read are not listed. This is a checklist of what to go and set, and a project running Google and GitHub has two OAuth credentials to think about, not five.

auth-github-credentials  d1 · environment
auth-google-credentials  d1 · environment
auth-session-secret      d1 · environment · rotatable
presence-ticket-key      d1 · environment · rotatable

5 secrets this configuration will never read are not listed. pithy secrets ls --all shows them, and why.

Hiding is never silent: the count is always there, so nothing applies here can never be mistaken for the CLI stopped showing me things. --all adds them back, each with its reason, drawn from your configuration rather than from prose — so why is apple missing is one flag away, and it answers what you would change to turn one on:

auth-apple-credentials               not applicable — auth() does not enable the apple provider
auth-facebook-credentials            not applicable — auth() does not enable the facebook provider
auth-github-credentials              d1 · environment
auth-google-credentials              d1 · environment
auth-microsoft-credentials           not applicable — auth() does not enable the microsoft provider
auth-play-integrity-service-account  not applicable — auth() allows no Android app to attest in any environment
auth-session-secret                  d1 · environment · rotatable
presence-ticket-key                  d1 · environment · rotatable
support-r2-credentials               not applicable — SUPPORT_BUCKET declined in pithy.config.ts

--all applies to --json too, rather than only the terminal — an agent is asking the same question a person is. Every row carries applies and, when it is false, reason, so nothing has to read the sentence; hidden counts what the flag would add.

A secret is hidden only when no Worker in the project can reach it. One Worker that still reads it is enough to leave the row alone, because the value is one value and that Worker needs it. pithy doctor takes the other branch with the same answer: it is a fault report, so it leaves these out of “No dev value for …” entirely rather than listing something you cannot act on.

A secret is hidden only when no environment can reach it either. A pithy.config.ts is code, and it may read the environment it is being composed for — pithy init scaffolds exactly that. So a project may enable a provider for production alone:

auth({ google: { enabled: compositionEnvironment() === "prod" } })

That credential is unreachable in dev and staging and read on every sign-in in prod, and reporting it as not applicable would hide work you have to do. ls composes each Worker once per environment your root config declares, plus dev, and takes the union: a secret needed in any of them applies. There is no --env on ls or on pithy doctor, and that is the reason — a secret is one value per project, so the answer is the project’s rather than the run’s.

Only a composition has an opinion, so an environment that will not compose has none. Your pithy.config.ts is code, so it can throw — a half-configured prod that refuses with Billing is not configured for this environment is the ordinary case. That environment produced no composition: no capabilities, no registry, no configuration, and so nothing that could need a secret. It is left out of the union, and the marks come from the environments that did compose:

auth-github-credentials  d1 · environment
auth-google-credentials  d1 · environment
auth-session-secret      d1 · environment · rotatable
presence-ticket-key      d1 · environment · rotatable

5 secrets this configuration will never read are not listed. pithy secrets ls --all shows them, and why.
One environment did not compose, so this answer is drawn from the rest.
  prod: Set payments.billing in apps/api/pithy.config.ts, or drop prod from environments.
A secret only those environments need may be among the ones not listed. Run pithy doctor.

Under --all the last line reads may be marked not applicable above instead, because there the rows it means are on the screen.

The reason is that error’s own action line. The note is there because this carries a risk: a credential only prod reads can be ruled not applicable, and so left out of the list, on the strength of dev and staging. The answer is to fix the config rather than to guess — a prod that does not load does not have requirements, it has a fault, and pithy doctor reports it as one under Environment configs:. Fix it and the marks are decided from all three.

edit is the odd one out, deliberately: it touches nothing but this machine’s dev values at <config>/<project>/secrets.jsonc. It opens a draft beside the real file, validates what comes back, and writes it atomically at 0600. It prints a path and a count, never a name and never a value — ls is what lists names. A draft that will not validate is handed back with the problem printed above it; a draft that is still broken, that the editor abandoned, or that lost a race with another command is kept, and the refusal names its absolute path. Nothing here deletes text it could not write.

provision stands up the per-environment infrastructure for every managed environment in order: each environment’s runtime token first — the one Cloudflare API token the application holds, carrying every composed capability’s runtimePermissions (Cloudflare API tokens) — then per environment a dedicated D1, a minted master key, the migrated schema, and the deployed manager Worker, which reads that token through its RUNTIME_CF_API_TOKEN binding. A runtime token already in the Secrets Store is reused as it is: one minted before a capability widened it is re-scoped by pithy token rotate runtime --env <env>. Every step is idempotent. That holds for a vault that also carries an app’s declared tables: their migrations are the app’s, so provision leaves them applied as they are and runs only its own.

A Worker that owns SECRETS gets its manager here, and its declared secrets. For each such Worker, provision migrates its own vault in every environment, deploys its manager over it, and then mints what that Worker declares into it. The vault is the SECRETS database pithy provision created for that Worker, so a Worker whose stanza names none for an environment is refused before anything is minted into it: <env> has no SECRETS database for <worker>, which owns its vault., naming pithy provision --env <env>. The shared manager deployed by the same run binds each owned vault, so its at-rest rotation re-seals them.

It says where it got to. Each environment’s manager Worker is named as it is about to be uploaded — ▸ acme-staging-secrets... — the same plain line pithy deploy, pithy provision and pithy email provision print, from the one seam they all share. A manager the deploy gate skipped as already current says nothing, because nothing was uploaded for it. --json silences the lot and still writes exactly one line; a missing TTY does not.

It creates every secret the registry says nobody chooses. A registry entry declares whether its value is arbitrary — a session signing key, a link signing key: any random string works, because nothing outside the project validates one. A secret whose value must match something issued elsewhere declares nothing, and stays a question for the person who can answer it.

An existing value is never replaced, on either path. Replacing a session secret signs everyone out, replacing a link key stops verifying links already in inboxes, and replacing a key-encryption key orphans everything sealed under it — so creating a missing secret and replacing a live one are different acts, and only the first happens here.

A global secret has one value in every environment, or the command stops. global is the promise that every environment reads one value, and it is a property of the whole declaration rather than of any one environment — so it is decided across every environment at once, before anything is written. All present, and nothing happens; all absent, and one minted value goes to each. Split — some environments hold it, some do not — and the run fails, naming the secret and both sides.

There is one repair for a split, and it is destructive: remove the secret everywhere with pithy secrets rm <name>, then run this again. The other-sounding option — give the empty environments the value the others hold — cannot be performed by anyone, because a d1 secret is sealed under a master key that never leaves its environment’s manager Worker. So the refusal names that one command as a person’s decision rather than a fix, and says what it costs: everything signed by the value the other environments hold stops verifying.

It also writes your secrets_store_secrets stanza. pithy add secrets cannot: a secret binding needs a store_id and a secret_name that do not exist until an account has been reached. Provisioning is when the store certainly exists and every entry has certainly been written, so it is where the stanza is written or corrected — upserting by binding, never duplicating, and leaving a binding the registry does not declare exactly where you put it.

deprovision reverses it for one environment, named. It used to walk every declared environment, so one run typed to clean up staging deleted production’s vault with it. Now --env is required, and there is no default set for production to be in:

Name the environment to deprovision. Nothing was deleted.
Pass --env with one of: staging, prod.

A vault holding rows is counted before anything goes. The secrets database’s tables are declared retained — a sealed credential exists there and at its issuer, nowhere else — so the rows are counted before the manager is deleted, every table registered in pithy_secrets_tables beside the system table, and the command refuses unless --destroy-retained names the same number. It is the same guard pithy migrate --rollback spends:

Retained 3 rows would be dropped: pithy_secrets_system_secrets on acme-prod-secrets (3 rows). Refused before anything was deleted.
They exist nowhere else. Back them up, or pass --destroy-retained 3 to drop them.

Every Worker’s own vault, <project>-<env>-<worker>---secrets, is counted the same way and deleted with the shared one: it is sealed under the same master key, so a --keys run that left it would leave rows nothing can decrypt. Each owner’s manager and its Workflows go with the shared manager’s. A different number refuses too. The count is taken again at the delete itself, so a row written in between is a row it refuses. Then the manager’s four Workflows (<project>-<env>-secrets-write, -secrets-rotate, -secrets-rotate-value and -secrets-rotate-fields), the manager Worker, the master key when --keys is passed, the database, and the environment’s runtime token go, in that order. The Workflows go first because deleting a Worker leaves the Workflows registered against it. The runtime token is per environment, so prod’s manager keeps rotating whatever staging’s teardown removes. The manager token runtime superseded is never touched: nothing revokes it for you, and pithy doctor names it. deprovision deletes over the API and spawns nothing, so it has nothing to narrate.

Per-owner secrets: declared tables

A secret that belongs to somebody gets an owner Pithy can see. A Stripe key per customer, a webhook signing secret per organization: an app declares a secrets table with defineSecretTable, with typed owner columns beside values sealed exactly as the system table’s are. Declared tables has the declaration, the accessor, and when a table beats a keyspace. pithy migrate writes each table’s migrations.

tables — what each environment holds

$ pithy secrets tables --env prod
customer    userId, organizationId
  STRIPE_KEY   1204 rows  key v4
  WEBHOOK_SIG  1204 rows  key v4

connection  installationId
  SIGNING_KEY  87 rows  key v4

Done.

Each declared table, its keys, its secret names, how many rows hold each, and which master-key version sealed them. These are runtime data an application writes, so no command creates, reads or deletes a row — a customer’s plaintext does not belong on an operator’s screen or in a shell history. Visibility exists for one reason: a rotation that stopped partway across a customer table should be visible to the operator who triggered it, and the key-version spread is what shows it:

  STRIPE_KEY   1204 rows  keys v3 12, v4 1192

12 rows are not on key v4. The last at-rest rotation did not reach them.

The newest version is what the rows say: the CLI cannot read the master key, so a row below the newest version any row in the vault is sealed under is a row a pass did not reach. A table declared and not yet migrated in that environment says so and names pithy migrate --env <env>. It reads through the same driver pithy migrate uses — the local store for dev, the D1 REST API otherwise — and a project declaring no table reads nothing. pithy doctor reports the same read as its Secret tables: block.

The field key

Fields marked encrypted() seal under their own key, PITHY_FIELD_KEYS, never the master key. Encrypted fields is the page for marking one. provision mints the key per environment beside the master key, in the same format, under <project>-<env>-pithy-field-keys, and only if it is absent: a fresh key over an existing one would orphan every sealed field. It binds it to every Worker that holds an encrypted field, whether or not that Worker composes secrets, and only those. A feature gets a field key of its own, deleted with it.

The project must compose secrets on some Worker, because the manager is what rotates the key. pithy provision refuses a declared environment where a Worker holds an encrypted field and nothing composes it, before anything is created. pithy deploy skips any kit Worker whose config binds a Secrets Store entry the store does not hold, naming the entry and the command, so a manager upgraded before provision minted its field key is not deployed against nothing.

The manager is stamped with what it re-seals. provision and pithy deploy derive the encrypted columns from every Worker’s schemas — the declared name, the field path, the primary key, the D1 binding, the index column and its normalizer — and write them into the manager’s ENCRYPTED_COLUMNS var, binding the manager to every D1 they live in. A Worker that owns the binding an encrypted table lives in is stamped with its own database, bound as <BINDING>_OF_<WORKER> (DB_OF_TWO), so the rotation re-seals and counts its rows too. An encrypted table with no encryptedTable() declaration is refused, naming it. A Worker whose pithy.config.ts will not load is stamped as a source the guard could not read.

The manager’s nightly cron rotates it every 30 days, on its own Workflow, <project>-<env>-secrets-rotate-fields, independent of the master key’s cadence. A pass adds a version and makes it current. It re-seals and re-indexes only the rows still under the version leaving the window, by compare-and-swap. Then it retires that version once the guard reads clean: no stamped envelope or index column under it, every source read, and no encrypted field outside D1. A dirty guard retires nothing, and the nightly backfill carries on clearing what it can.

A version still live when the next rotation is due is a failure. The pass closes field-key-overdue and raises the secrets/field_key_retirement_blocked audit event naming what held it, and pithy doctor fails on it. While four versions are live no version is added, rather than drift toward the Secrets Store’s 64 KiB ceiling. The pass still re-seals and retires on a clean guard, so the ceiling clears itself once its cause is fixed; on a dirty guard it closes field-key-ceiling. No step of the Workflow returns a key, so its journal holds version numbers and a digest, never key material. A retirement, past the guard or on a clean one, holds the same single-flight lock as a rotation and writes only over the key set it read, so it never runs beside one.

retire-version — past the guard, by a person

pithy secrets retire-version 1 --env prod --past-guard
prod: field-key versions live: 3, 2, 1.
  patients.diagnosis (diagnosis): 4 rows still under version 1.
  Unrotatable, never re-sealed: app:cache.tokens:value.token.
  Not read by the guard: apps/billing.
Retiring version 1 makes every ciphertext still under it unopenable. Nothing brings it back.
◆  Type prod/1 to retire it:

The rotator retires a version itself when the guard is clean, so this exists only for the other case, and it is the most destructive command the kit owns. It asks the manager for the guard first, because the manager holds the stamp of encrypted columns the guard counts: the stale count per column under <v> alone, every unrotatable field and every source it could not read. Then it asks for <env>/<v> to be typed back. Anything else retires nothing. There is no --yes. Off a terminal, under --no-input or PITHY_NONINTERACTIVE, or with --json, it refuses with core/person_required, exit 5, before anything is read, so neither an agent nor a CI script can run it. The current version is refused: it seals every write. The retirement is audited as secrets/field_key_retired with pastGuard: true and the stale count it was retired over.

verify

Does every stored secret still open, and does anything sit in the account’s Secrets Store that nothing accounts for. Two detectors, one command, because a misaddressed write leaves both halves behind at once: the entry a binding reads no longer holds what it should, and the value that should have gone into it sits under a name nothing composes.

It writes nothing and it deletes nothing. An entry this project cannot account for is reported; what to do about it is a decision taken with the account in front of you.

The first half runs inside the manager Worker, because the master key that opens those rows never leaves it. Every row of pithy_secrets_system_secrets is decrypted, and what comes back is counts and key versions — never a secret’s name, never a value, never what a decrypt failure said.

staging: 14 of 14 rows opened. Key versions 3 (14 rows).
prod: 12 of 14 rows opened. Key versions 2 (2 rows), 3 (12 rows).
2 stored rows would not open.
Rows reference key version 2, which SECRETS_ENCRYPTION_KEYS does not hold.
Find out what removed that key version before changing anything. Restoring it is the repair, and it is the one value a wrong edit makes unrecoverable.
Store: 9 accounted, 3 another project's.

The second half lists the store and classifies every entry against the names this project composes, through the same functions provisioning composes them with. An entry with no project segment is the shape the failure this command exists for produces — a bare SECRETS_ENCRYPTION_KEYS beside <project>-<env>-secrets-encryption-keys, holding the key that should have gone into it:

Unscoped entry: SECRETS_ENCRYPTION_KEYS. Something wrote a name it composed itself.
An unscoped name says nothing about which project wrote it. Find out before removing one.

A false orphan is the expensive mistake here, not a missed one, so the classification refuses to guess. An entry outside <project>- belongs to a sibling project in the same account: it is counted and never named. An entry whose scope segment this checkout does not declare is reported as an unrecognized scope rather than as debris — pithy.config.ts differs between branches. An entry named like a master key is never an orphan under any circumstances, because deleting one makes an environment’s whole database permanently undecryptable. And when the answer cannot be completed — a Worker whose registry will not load, token profiles that will not resolve — the orphan verdict is withheld and says so, rather than turning every secret that Worker declared into a finding. The unscoped check still runs: it does not depend on the count being complete, and a project whose provisioning is untidy is exactly the one that may be holding the entry.

The sweep, and --no-sweep

The sweep runs by default. It needs more than the first half does: your Cloudflare credentials and the SECRETS_STORE_ID that pithy add secrets records. It resolves all of them inside itself, so --no-sweep asks for none of them — the run for a machine that holds the manager’s credentials and not the store’s.

--env narrows the first half only. The sweep classifies the whole store against every environment the project declares, because an entry is accounted for by any of them.

A sweep that could not run is not a clean one. When something it needs is missing or refused — no SECRETS_STORE_ID, a store that would not list — the run says Store not swept. with the reason, the verdict is withheld, and it exits 0. Nobody has been shown evidence of anything, so it is neither a finding nor a pass.

--no-sweep asks for no sweep, so it reports none. A run with nothing wrong in its stores is verified, and its --json line carries no sweep key at all. If your gate needs the store checked too, key it on sweep being present, not on verified alone.

Exit codes

CodeMeaningWhat to do
0Verified, or withheld. Nothing was foundNothing. Under --json, verdict says which of the two
4Nothing was found, and an environment’s manager did not answer. The error line is the whole answer: under --json nothing is written to stdout, and the line carries retryable: true. A fault that says what it is keeps its own class instead — a refused credential exits by its kindRun it again in a moment. For a credentials fault, fix them first
5A finding: a row that will not open, a key version rows reference and the config does not hold, a pointer the key set does not hold, or an entry nothing accounts forSomebody has to look. Retrying changes nothing
5SECRETS_ENCRYPTION_KEYS will not resolve for an environment. Nothing in that store can be readCheck what the binding resolves to. No retry ever fixes it

Both findings exit 5, the kit-wide code for a step that needs a person. verdict under --json tells them apart: failed for a finding, key-unreadable for the master key. They used to be 4 and 5; 4 now means retry with backoff, which is the one reaction a finding must never get.

A finding outranks a fault. One unreachable environment beside one broken store exits 5, not the unreachable environment’s code — that environment keeps its own line, and the finding decides the status. A retryable code is what a cron retries, and masking a finding behind it is how a broken store gets retried nightly forever.

Credentials come from <config>/cloudflare.json, or <config>/cloudflare.<accountName>.json when the root config names an account. A profile bound here by pithy cloudflare connect outranks the file, and reads SECRETS_STORE_ID from its own <config>/cloudflare.<profile>.json instead. provision and deprovision additionally need SECRETS_STORE_ID, which pithy cloudflare connect and pithy add secrets record.

--json

One line on stdout. A failure is one {"error": …} line on stderr, carrying exit, retryable and, where the cause is known, fix, and the process exits by its class.

verify

$ pithy secrets verify --json
{"command":"secrets verify","schemaVersion":1,"verdict":"failed","verified":false,"exitCode":5,"environments":[{"env":"prod","state":"verified","verification":{"keySet":"resolved","rows":14,"readable":12,"unreadable":2,"keyVersions":[{"keyVersion":2,"rows":2},{"keyVersion":3,"rows":12}],"heldVersions":[3],"currentVersion":3,"currentVersionHeld":true,"missingVersions":[2],"rotationInProgress":false}}],"sweep":{"counts":{"accounted":9,"unscoped":1,"orphan":0,"key-material":0,"unknown-scope":0,"feature":0,"foreign":3},"unscoped":["SECRETS_ENCRYPTION_KEYS"],"orphans":[],"keyMaterial":[],"unknownScope":[],"withheld":null}}
KeyTypeMeaning
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
verdictstring"verified", "withheld", "failed" or "key-unreadable". The field to key a gate on
verifiedbooleantrue only for "verified". A withheld run asserted nothing about the store and must never read as a clean one
exitCodenumberThe status this run exits with — 0 or 5. Stated so a caller reading the line need not also read $?. A run that ends on an unreachable environment writes no document at all
environments[].statestring"verified" when that environment’s manager answered, whatever it said; "unreachable" when it did not
environments[].verificationobjectPresent only when it answered. keySet is "resolved" or "unreadable"; an "unreadable" one carries rows, keyVersions and rotationInProgress alone, because nothing was opened
sweepobjectPresent only when a sweep ran. counts is complete; the name arrays carry only what this project may name
sweep.withheldstring or nullWhy the orphan verdict was not computed. Non-null means orphans, keyMaterial and unknownScope are empty by policy rather than by finding
notSweptstringPresent only when a sweep was asked for and could not run

Nothing on either stream carries a secret’s name, a value, or what a decrypt failure said.

create, update, rm

KeyTypeMeaning
commandstring"secrets create", "secrets update" or "secrets delete" — rm reports the mode it ran, which is delete
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
namestringThe secret name given on the command line
environmentsstring[]The managed environments the write reached. What landed, never what was planned. On an account-entry write, every environment that reads the entry
accountEntrybooleanPresent and true on a global CF-Secrets-Store write, where one account-level entry changed rather than one store per environment. Absent for rm --backend d1, because a vault row is not an account entry
interruptedbooleanPresent and true only on a global fan-out that failed after at least one environment was written. The exit is then non-zero by the failure’s class

rotate

KeyTypeMeaning
commandstring"secrets rotate"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
namestringThe secret name given on the command line
rotationsobject[]One record per secret. Always one today, because there is no --all — the shape is per secret so no aggregate field can ever be added beside it and disagree
rotations[].namestringThe secret’s registry name. Never its value; this payload has no field that could carry one
rotations[].statusstring"rotated", "unchanged", "unrecorded" or "failed". unrecorded is the issuer-rolled-and-not-stored state, and the only one that exits 5
rotations[].rotationstringHow the registry says the secret is replaced: "local", "provider" or "manual"
rotations[].rolledbooleanWhether a third party’s credential was actually changed. true only for a provider rotation that reached its rotator — and true on the failure path too, which is the point of the field
rotations[].rollFailedbooleanPresent and true when the rotator itself failed rather than the store after it. Then rolled is a guess: the call reached the issuer and the answer did not come back
rotations[].recordedstring[]The environments that took the new value, in the order they took it
rotations[].strandedstring[]The environments the new value never reached. On an unrecorded run these are holding a credential the issuer has retired
rotations[].reasonstring"manual" or "dry-run". Present only when status is unchanged

ls

KeyTypeMeaning
commandstring"secrets ls"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
secretsobject[]Every declared name this configuration can reach, sorted. With --all, every declared name
secrets[].namestringThe registry key — a secret name, or a keyspace
secrets[].descriptionstringThe entry’s routing facts: backend (d1 or cf-secrets-store), scope (environment or global), then rotatable when it is, then keyspace when the entry is keyed
secrets[].appliesbooleanWhether any Worker in any composed environment reads it
secrets[].reasonstringPresent only when applies is false: what in your configuration makes it unreachable
hiddennumberHow many rows --all would add
unresolvedobject[]The environments whose pithy.config.ts would not compose. Empty on an ordinary project
unresolved[].environmentstringThe environment that could not be composed
unresolved[].reasonstringThat failure’s action line — what to change to fix it

unresolved is a fact about the answer, not about any one secret, which is why it is its own key rather than a field on a row. Non-empty means every applies on this list was decided from fewer environments than the project declares: the listed ones produced no composition, so they had no say. A consumer acting on applies should treat a non-empty unresolved as decided from part of the project — a row marked applies: false may be one an unloaded environment would have kept.

A keyspace marker is the one entry you must not try to set: its members are written per key, in-Worker, by the application that mints them.

tables

KeyTypeMeaning
commandstring"secrets tables"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
envstringThe environment read
newestKeyVersionnumber | nullThe newest master-key version any row in the vault is sealed under. null for an empty vault
behindnumberRows in declared tables sealed below that version — rows a rotation did not reach
tablesobject[]Every declared table, then any the vault holds that no Worker declares
tables[].tablestringThe table’s name — customer for pithy_secrets_customer_secrets
tables[].workerstring | nullThe Worker that declares it, or null for one only the vault knows
tables[].keysstring[]Its owner key columns
tables[].statestringmigrated, not-migrated (declared, and its migration has not run here) or undeclared (held, and declared by no Worker)
tables[].secretsobject[]Each secret name, with name, rows, and keyVersions — master-key version to the rows it sealed

edit

KeyTypeMeaning
commandstring"secrets edit"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
pathstringThe absolute path of <config>/<project>/secrets.jsonc
changedbooleanWhether the file was written. false for an edit that changed nothing, which is not a failure
secretsnumberHow many secrets the file holds now. A count — the names are not in this payload

provision

KeyTypeMeaning
commandstring"secrets provision"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentsobject[]One entry per managed environment, in order
environments[].envstringThe environment
environments[].databaseIdstringThe id of that environment’s secrets D1
environments[].storeIdstringThe Secrets Store id that environment’s master key was written to
wiredobject[]One entry per Worker and environment whose secrets_store_secrets stanza this run wrote
wired[].workerstringThe Worker, as pithy worker list shows it
wired[].envstringThe environment whose stanza was written. Never dev
wired[].bindingsstring[]The binding names written into that stanza
wired[].createdstring[]The binding names whose value this run minted. A subset of bindings, and empty on a re-run
generatedobject[]One entry per d1 secret the registry declares mintable
generated[].namestringThe secret’s registry name. Never its value
generated[].environmentsstring[]Where the secret belongs
generated[].workerstringPresent only on an entry minted into a Worker’s own vault: the apps/ Worker that owns SECRETS. Absent for the shared vault, so one secret name can appear twice — once for the shared vault and once for that Worker’s
generated[].createdstring[]The environments this run created it in. Separate from environments, because sent is not made — this is the field that answers did this run generate a production signing key
interruptedbooleanPresent and true only on a run that failed part-way through creating the d1 secrets

deprovision

KeyTypeMeaning
commandstring"secrets deprovision"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
envstringThe one environment torn down — the value of --env
keysDeletedbooleanWhether --keys was passed, and so whether that environment’s master key was deleted with the rest
runtimeTokenDeletedbooleanWhether this run removed the environment’s runtime token and its Secrets Store entry. false when neither was there

Errors

  • No secrets capability. No Worker in the project composes secrets, so there is no registry to read. core/not_found, exit 3. With one Worker, api, its fix is pithy add secrets --worker api, and the action names the same command. With several there is no fix, because nothing says which Worker should compose it, and the action names one command per Worker, each runnable as written. --worker on a pithy secrets subcommand chooses a vault and cannot add the capability; only the pithy add it names does.
  • Secret '<name>' is not declared in the registry. Add it to the registry first.
  • Secret '<name>' is a keyspace, not a secret. A keyspace has no single value; its members belong to the application that mints them.
  • Secret '<name>' does not declare how it rotates. rotate only. Add a rotation to its registry entry, or replace the value with pithy secrets update.
  • Secret '<name>' rotates by calling <issuer>, and this project supplies no rotator for it. The declaration is right and the code is missing.
  • Secret '<name>' is the key every other secret is read through, so nothing replaces it in place. rotate only, for the master key. It rotates on its own axis, inside the manager, on the manager’s own cron.
  • <name> was rolled at <issuer> and its new value was not stored. Exit 5. The one failure this command cannot undo.
  • Secret '<name>' is environment-scoped — choose an environment.
  • Secret '<name>' is global. … Run it again without --env. Nothing was dispatched, so nothing was written.
  • No value was piped for '<name>', and this run cannot prompt for one. stdin is a terminal and no prompt can be drawn. Pipe the value in, to the same command with every flag you gave it.
  • --env dev. Refused, and pointed at pithy dev — this writes to a Cloudflare account, and dev is local.
  • Cloudflare credentials are missing. Raised by every subcommand that reaches Cloudflare — not by ls.
  • Name the environment to deprovision. Nothing was deleted. deprovision only. Pass --env with one of the environments the refusal lists. An undeclared one is refused the same way. --env dev is refused as undeclared and pointed at pithy dev: there is nothing of dev on a Cloudflare account to tear down.
  • @pithy-sh/secrets asked for <call> while tearing down <env>. Refused. deprovision only. The command hands the teardown a deprovisioner that deletes only the named environment’s Workflows, manager, database and runtime token, and its master key only with --keys. A @pithy-sh/secrets older than the CLI that reaches past that is stopped at the reach. Update it to match the CLI.
  • Retained <n> rows would be dropped: … Refused before anything was deleted. deprovision only. The vault holds rows. Back them up, or pass --destroy-retained <n> with the number printed.
  • The CF Secrets Store id is missing. provision and deprovision only.
  • No project name. A guess would open one checkout’s secrets from another’s worktree, or dispatch this project’s values into another project’s manager.
  • Retiring a field-key version past its guard needs a person at a terminal. retire-version only, core/person_required, exit 5. Run it at a terminal, without --json, --no-input or PITHY_NONINTERACTIVE, and type the version back.
  • The rotator retires a version itself once its guard reads clean. retire-version without --past-guard. Nothing to run while the guard is clean.
  • edit conflicts. The file changed while you were editing; the editor exited non-zero on changed text; the text came back invalid twice. In every case your text is kept and named.

Examples

pithy secrets ls --json
pithy secrets ls --all
printf '%s' "$THE_VALUE" | pithy secrets create STRIPE_SECRET_KEY --env prod --json
pithy secrets update STRIPE_SECRET_KEY --env prod

# Create a bundle interactively — one masked prompt per field, for the rails this project runs.
pithy secrets create payments-provider-credentials --env prod

pithy secrets rotate TURNSTILE_SECRET --env prod --dry-run
pithy secrets rotate SESSION_SIGNING_KEY --env prod
pithy secrets rm OLD_WEBHOOK_SECRET --env staging --json
pithy secrets verify --json
pithy secrets edit

# See each declared secret table in prod, and whether every row is on the newest key.
pithy secrets tables --env prod

# Tear staging down. Prod is not touched; its manager keeps prod's runtime token.
pithy secrets deprovision --env staging --json

# Retire a field-key version the guard is holding. At a terminal, typing prod/1 back.
pithy secrets retire-version 1 --env prod --past-guard
{"command":"secrets create","schemaVersion":1,"name":"STRIPE_SECRET_KEY","environments":["prod"]}
{"command":"secrets update","schemaVersion":1,"name":"partner-webhook-secret","environments":["staging","canary"],"interrupted":true}
{"command":"secrets ls","schemaVersion":1,"secrets":[{"name":"auth-session-secret","description":"d1 · environment · rotatable","applies":true}],"hidden":2,"unresolved":[]}
{"command":"secrets rotate","schemaVersion":2,"name":"CLOUDFLARE_API_TOKEN","rotations":[{"name":"CLOUDFLARE_API_TOKEN","status":"unrecorded","rotation":"provider","rolled":true,"recorded":[],"stranded":["prod"]}]}
{"command":"secrets edit","schemaVersion":1,"path":"/home/you/.config/pithy/acme/secrets.jsonc","changed":true,"secrets":4}
{"command":"secrets deprovision","schemaVersion":2,"env":"staging","keysDeleted":false,"runtimeTokenDeleted":true}

No example above contains a value, and none of these payloads can carry one.

ESC