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
| Subcommand | Flag | Meaning |
|---|---|---|
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-previous | Keep the old token as a grace window instead of deleting it. Default false |
forget | --force | Drop the local copy without checking whether the token has been used, and without asking. Default false |
| all | --json | Machine-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.
| Store | What it does |
|---|---|
dev-vars | Writes 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-store | Writes to the Cloudflare Secrets Store for a Worker to read through its binding, with no human in the loop |
ephemeral | Writes 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
| Key | Type | Meaning |
|---|---|---|
command | string | "token mint" or "token rotate" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
profile | string | The profile that was minted |
env | string | The environment it was minted for |
tokenId | string | Cloudflare’s id for the token. An identifier, not a credential |
status | string | The token’s lifecycle status: "active", "disabled" or "expired". Absent when Cloudflare returned none. A mint over a dead token says so here |
store | string | Where the value went: "secrets-store", "dev-vars" or "ephemeral" |
location | string | A 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
| Key | Type | Meaning |
|---|---|---|
command | string | "token list" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
env | string | The environment listed |
tokens | object[] | This project’s tokens for that environment. Empty when there are none |
tokens[].profile | string | The profile, recovered by exact-name lookup |
tokens[].env | string | The environment — the same one, on every row |
tokens[].name | string | The composed Cloudflare token name, <project>-<env>-<profile> |
tokens[].tokenId | string | Cloudflare’s id for the token |
tokens[].status | string, optional | The token’s lifecycle status as Cloudflare reports it: "active", "disabled" or "expired". Absent when the account API returned none |
tokens[].routeScope | string | Whether the token can attach the routes this environment’s declared domains need: "not-required", "scoped", "stale", "overridden", "inactive" or "unknown" |
tokens[].grants | string, optional | Whether the token carries every permission its profile names: "current", "missing" (run pithy token rotate; a mint keeps the old policies), "inactive" or "unknown" |
superseded | object[], optional | The credentials runtime superseded that are still present. Empty when there are none |
superseded[].kind | string | "account-token", by its name, or "stored", a token inside a secret, by the secret’s name |
superseded[].name | string | The account token’s name, or the secret that stores one |
superseded[].tokenId | string, optional | Cloudflare’s id, for an account token |
superseded[].status | string, optional | The account token’s status, when Cloudflare returned one |
superseded[].env | string, optional | The environment whose vault stores it, for a stored token |
superseded[].was | string | What it was, in the operator’s words |
superseded[].supersededBy | string | "runtime" |
supersededAsked | boolean, optional | false when the environment’s secrets manager could not say whether a supplied media token is still stored |
revoke
| Key | Type | Meaning |
|---|---|---|
command | string | "token revoke" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
profile | string | The profile that was revoked |
env | string | The environment it was revoked for |
name | string | The composed Cloudflare token name the sweep matched |
revokedCount | number | How many account tokens of that name were deleted. 0 is an ordinary answer |
localCopy | string | The 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 |
location | string | The tokens.json path the local copy lives in |
localCopyProblem | string, optional | Why 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
| Key | Type | Meaning |
|---|---|---|
command | string | "token forget" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
profile | string | The profile whose copy was forgotten |
env | string | The environment it was forgotten for |
localCopy | string | "forgotten" when a value was dropped, "absent" when there was none |
location | string | The tokens.json path |
usage | string | What 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 withpithy cloudflare connect, or setCLOUDFLARE_ACCOUNT_IDandCLOUDFLARE_API_TOKEN— the bootstrap token — then run it again. No command records a token inside a project:pithy initdoes only as it scaffolds a new one.This project now needs permissions the session for profile <name> was not granted: <scopes>.mintandrotateunder 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. Runpithy 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 aresecrets-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.Runpithy add secrets --worker apito recordSECRETS_STORE_ID, naming the Worker that composessecrets, or mint with--store dev-vars. In a project with several Workers the action names one command per Worker, because a barepithy add secretsis refused there.- No project name. Every token name and Secrets Store entry starts with it, and
revokedeletes 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.forgetreadlast_used_on: nulland 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, throughpithy token rotate <profile> --env <env>.Cannot update <path>: …forgetwill not rewrite atokens.jsonit could not read, parse or make sense of — every other environment’s value is still in it. Fix the file, or move it aside.revokereports the same sentence aslocalCopyProblemand still succeeds.--envis validated at the flag.productionis answered withprod; 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.