pithy token

Mint, list, rotate, revoke and forget the scoped, least-privilege, account-owned Cloudflare API tokens a project needs.

A minted token is a secret like any other, so pithy secrets is where it lands — and a CI pipeline is the main reason to mint one.

Synopsis

pithy token mint <profile> [--env <env>] [--store <store>] [--permission <key>]… [--json]
pithy token list [--env <env>] [--json]
pithy token rotate <profile> [--env <env>] [--store <store>] [--permission <key>]… [--keep-previous] [--json]
pithy token revoke <profile> [--env <env>] [--json]
pithy token forget <profile> [--env <env>] [--force] [--json]

The model behind these five commands — the bootstrap token, the delegation rule, what ci-system and runtime are, and where each store puts a value — is Cloudflare API tokens. This page is the command surface.

Flags

SubcommandFlagMeaning
mint, rotate, revoke, forget<profile> (positional, required)The token profile: ci-system, the CI credential, or runtime, the one token a deployed application holds. revoke also takes a superseded profile, secrets, to remove the manager token runtime replaced
all--env <env>Target environment. Default dev
mint, rotate--store <store>Override where the value is written: secrets-store, dev-vars, ephemeral
mint, rotate--permission <key>Override the permission set. Repeatable — every occurrence is collected
rotate--keep-previousKeep the old token as a grace window instead of deleting it. Default false
forget--forceDrop the local copy without checking whether the token has been used, and without asking. Default false
all--jsonMachine-readable output. Default false

The permission keys --permission accepts are fixed and named in the flag’s own help. An unknown key is refused before anything is minted, so a typo cannot produce a mis-scoped credential.

A --store on the command line wins over the profile’s defaultStore, which wins over the declared backend of the profile’s secret in the registry.

What it does

No subcommand ever prints a token value. Not on stdout, not in --json, not in an audit event, not in an error. That is a property to rely on: the value goes to the store the profile resolves, and the output says only which store and where.

StoreWhat it does
dev-varsWrites to <config>/<project>/tokens.json, mode 0600, keyed by environment. Nothing in the CLI reads a credential out of that file. It is a handoff: you open it, copy the value, and paste it into your CI provider’s secrets. forget and revoke take a value out of it; nothing uses one
secrets-storeWrites to the Cloudflare Secrets Store for a Worker to read through its binding, with no human in the loop
ephemeralWrites nothing at all

mint rolls in place. The token name is a stable (project, env, profile) identity — <project>-<env>-<profile> — so re-minting never orphans a token. A first mint creates the token with the profile’s current permissions. A later mint rolls the value and keeps the token’s policies, so a permission added since — a capability’s ciPermissions or runtimePermissions, or a resource the project now binds — takes effect on the next rotate, never the next mint. The permissions are the ones --env’s own composition contributes: each Worker’s pithy.config.ts is evaluated under that environment’s ENVIRONMENT, so a capability a config composes for production alone widens the production token and no other. It does not reuse a stored value.

list reports this project’s tokens for one environment, identities only. Two gates decide what appears: the <project>-<env>- prefix, because Cloudflare’s account token list is flat and account-wide and includes other projects’ credentials as well as your own; and a reverse lookup from the known profile names, because the naming facade may truncate a long trailing segment, so slicing the prefix off would hand back a string rotate and revoke cannot resolve. A prefixed token no profile claims is therefore not listed. Each row also says whether the token carries every permission its profile names, read from the token’s own policies. A token missing one is named with the rotate that fixes it, because a mint would keep the old policies.

list also names the tokens runtime superseded that are still there, because nothing revokes them for you: the secrets manager’s own token, <project>-global-secrets-manager or <project>-<env>-secrets, from the account’s token list, and the Images and Stream token supplied to pithy media provision (your bootstrap token, unless you passed --api-token), when this environment composes media and its media-storage-credentials still carries it. That one is asked of the environment’s secrets manager, which opens the bundle and answers a bit. A manager that cannot answer costs that line, never the listing. Upgrading to one token has the path.

rotate is the two-step Cloudflare has no single call for: mint a new token under the same name with the profile’s current policies, store the value, then delete the tokens that predate it. --keep-previous leaves the old one standing as a grace window while a Worker consumer picks up the new value — redeploy first.

revoke deletes every account token of the profile’s computed name for that environment. The project scope in that name is what keeps the sweep inside this project. Then it drops the profile’s local copy for that environment from tokens.json, because a deleted token’s value would otherwise sit there looking exactly like a live one. The delete is the operation and the cleanup is reported, never load-bearing: an absent file, an unreadable one, or one holding no such key leaves the revoke a success, and localCopy says which happened.

forget drops the profile’s local copy for one environment and leaves the Cloudflare token live. It is for a token that is already where it is going, usually a ci-system value pasted into CI. The file is keyed by variable name, so the profile is resolved to its secret, CF_TOKEN_CI_SYSTEM, the way the mint wrote it.

Cloudflare never returns a token’s value after creation, so dropping the copy of a token nothing has used strands it. forget asks the account first. The token list reports last_used_on, and a null there means nothing has ever authenticated with the token, so forget refuses and drops nothing. When that field cannot be read — no credentials, offline, or a response that does not say — forget asks at a terminal and drops the value when nobody can be asked. A local file operation does not fail for being offline, and pithy token rotate recovers an unwanted drop. --force skips the check, the refusal and the prompt. A token the account no longer holds is dropped without asking: its value opens nothing. With nothing to forget, it asks nobody and calls nothing, so a second run is the same run.

Every mint, rotate and revoke, and every forget that drops a value or is refused, emits an audit event (cloudflare/token_minted, …_rotated, …_revoked, …_forgotten) carrying the token’s id or profile, never its value — and only when the project composes @pithy-sh/audit. A mint, rotate or forget that succeeds also names its store. It is a no-op otherwise; the CLI never hard-depends on audit, and an audit write never breaks the token action it records. A forget with nothing to drop emits nothing, because it took no action. A forget without credentials goes unrecorded too: there is no client to write the event with, and when the project composes audit forget says so on stderr (audit event not recorded) rather than dropping the value in silence.

Credentials come from <config>/cloudflare.json, or <config>/cloudflare.<accountName>.json when the root pithy.config.ts names an account. They are account-scoped rather than per project, and the account is resolved from the project’s own config before the credentials are read — minting into a file the project did not select would create a real token in somebody else’s account. A profile bound here by pithy cloudflare connect outranks the file, and the audit events then name the person who signed in rather than a token. PITHY_OFFLINE refuses ambient credentials, so an offline run fails with “Cloudflare credentials are missing” rather than reaching an account nobody in the session named.

--json

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

mint and rotate

KeyTypeMeaning
commandstring"token mint" or "token rotate"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
profilestringThe profile that was minted
envstringThe environment it was minted for
tokenIdstringCloudflare’s id for the token. An identifier, not a credential
statusstringThe token’s lifecycle status: "active", "disabled" or "expired". Absent when Cloudflare returned none. A mint over a dead token says so here
storestringWhere the value went: "secrets-store", "dev-vars" or "ephemeral"
locationstringA human location for that store: the tokens.json path, "CF Secrets Store", or "(ephemeral — not written)"

The token’s value and its composed Cloudflare name are both on the internal result and both deliberately absent here.

list

KeyTypeMeaning
commandstring"token list"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
envstringThe environment listed
tokensobject[]This project’s tokens for that environment. Empty when there are none
tokens[].profilestringThe profile, recovered by exact-name lookup
tokens[].envstringThe environment — the same one, on every row
tokens[].namestringThe composed Cloudflare token name, <project>-<env>-<profile>
tokens[].tokenIdstringCloudflare’s id for the token
tokens[].statusstring, optionalThe token’s lifecycle status as Cloudflare reports it: "active", "disabled" or "expired". Absent when the account API returned none
tokens[].routeScopestringWhether the token can attach the routes this environment’s declared domains need: "not-required", "scoped", "stale", "overridden", "inactive" or "unknown"
tokens[].grantsstring, optionalWhether the token carries every permission its profile names: "current", "missing" (run pithy token rotate; a mint keeps the old policies), "inactive" or "unknown"
supersededobject[], optionalThe credentials runtime superseded that are still present. Empty when there are none
superseded[].kindstring"account-token", by its name, or "stored", a token inside a secret, by the secret’s name
superseded[].namestringThe account token’s name, or the secret that stores one
superseded[].tokenIdstring, optionalCloudflare’s id, for an account token
superseded[].statusstring, optionalThe account token’s status, when Cloudflare returned one
superseded[].envstring, optionalThe environment whose vault stores it, for a stored token
superseded[].wasstringWhat it was, in the operator’s words
superseded[].supersededBystring"runtime"
supersededAskedboolean, optionalfalse when the environment’s secrets manager could not say whether a supplied media token is still stored

revoke

KeyTypeMeaning
commandstring"token revoke"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
profilestringThe profile that was revoked
envstringThe environment it was revoked for
namestringThe composed Cloudflare token name the sweep matched
revokedCountnumberHow many account tokens of that name were deleted. 0 is an ordinary answer
localCopystringThe profile’s local copy for this environment: "forgotten" (dropped), "absent" (there was none), or "uncleared" (the cleanup could not run, so one may still be there). A word, not a boolean, for the reason revokedCount is a count
locationstringThe tokens.json path the local copy lives in
localCopyProblemstring, optionalWhy the cleanup could not run. Present only with "uncleared". Never a line of the file

It is revokedCount rather than revoked on purpose: a plain revoked reads as was it revoked in one reading and how many in another, and revoked: 0 and revoked: false are not the same claim.

forget

KeyTypeMeaning
commandstring"token forget"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
profilestringThe profile whose copy was forgotten
envstringThe environment it was forgotten for
localCopystring"forgotten" when a value was dropped, "absent" when there was none
locationstringThe tokens.json path
usagestringWhat Cloudflare said about the token’s use, which is why the drop went ahead: "used", "no-live-token", "unreadable", or "skipped" (--force, or nothing to forget). "never-used" is a refusal and never reaches this line

Errors

  • Cloudflare credentials are missing. Sign in with pithy cloudflare connect, or set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN — the bootstrap token — then run it again. No command records a token inside a project: pithy init does only as it scaffolds a new one.
  • This project now needs permissions the session for profile <name> was not granted: <scopes>. mint and rotate under a signed-in session check first that the session holds every permission the project now derives, so Cloudflare’s delegation rule is never met mid-mint. Run pithy cloudflare connect --profile <name> to approve them, then run it again.
  • Unknown token permission key: <key>. The refusal lists every legal key.
  • Unknown token store: <value>. Legal values are secrets-store, dev-vars, ephemeral.
  • Unknown token profile: <name>. The refusal lists the profiles this project actually resolves — the aggregate of its composed capabilities’ declarations and its config overrides.
  • No storage is declared for the token. The profile names no store and its secret is not in the registry. Declare the secret as cf-secrets-store, or mint with --store dev-vars.
  • The secret is declared d1. A token whose value is read outside the Worker cannot live in the encrypted D1 store. Same two fixes.
  • No CF Secrets Store is configured for the secrets-store store. Run pithy add secrets --worker api to record SECRETS_STORE_ID, naming the Worker that composes secrets, or mint with --store dev-vars. In a project with several Workers the action names one command per Worker, because a bare pithy add secrets is refused there.
  • No project name. Every token name and Secrets Store entry starts with it, and revoke deletes every account token of the name it computes — a guess would point that sweep at another project’s credentials.
  • <profile>'s <env> token has never been used, so <path> may hold its only copy. forget read last_used_on: null and dropped nothing. Put the value where it is going and let it authenticate once, or pass --force. A copy dropped by mistake comes back only as a new token, through pithy token rotate <profile> --env <env>.
  • Cannot update <path>: … forget will not rewrite a tokens.json it could not read, parse or make sense of — every other environment’s value is still in it. Fix the file, or move it aside. revoke reports the same sentence as localCopyProblem and still succeeds.
  • --env is validated at the flag. production is answered with prod; anything over seven characters or outside the character set is refused before a single Cloudflare call.

Examples

pithy token mint ci-system --env prod --json
pithy token mint ci-system --env prod --store ephemeral --permission workers:write --permission d1:write
pithy token list --env prod --json
pithy token rotate runtime --env prod --keep-previous --json
pithy token revoke ci-system --env staging --json
pithy token forget ci-system --env prod --json
{"command":"token mint","schemaVersion":1,"profile":"ci-system","env":"prod","tokenId":"<token-id>","store":"dev-vars","location":"/home/you/.config/pithy/acme/tokens.json"}
{"command":"token list","schemaVersion":1,"env":"prod","tokens":[{"profile":"ci-system","env":"prod","name":"acme-prod-ci-system","tokenId":"<token-id>","status":"active"}],"superseded":[],"supersededAsked":true}
{"command":"token revoke","schemaVersion":1,"profile":"ci-system","env":"staging","name":"acme-staging-ci-system","revokedCount":1,"localCopy":"forgotten","location":"/home/you/.config/pithy/acme/tokens.json"}
{"command":"token forget","schemaVersion":1,"profile":"ci-system","env":"prod","localCopy":"forgotten","location":"/home/you/.config/pithy/acme/tokens.json","usage":"used"}

Every value above that looks like an identifier is a placeholder. No payload on this page can carry a token value, whatever is substituted in.

ESC