Where it is
What it is for is the concept page; development secrets is the file you will actually edit; pithy doctor reports what it found here; and accepted limits covers what this directory does not defend against.
~/.config/pithy on Linux and macOS, following the platform’s own convention elsewhere.
Created 0700, with 0600 files.
pithy doctor prints every path below, so you never have to remember them.
The files
| Path | Holds | Written by |
|---|---|---|
state.json | The update notifier’s state | pithy doctor, the notifier |
dev-ports.json | The machine-wide port registry | Any command taking a port |
session.<profile>.json | A Cloudflare sign-in, renewed as it is used | pithy cloudflare connect |
cloudflare.<name>.json | A Cloudflare API token, or for a profile, its Secrets Store id and R2 credentials | pithy init, pithy token; for a profile, pithy cloudflare connect and pithy add secrets record the store id |
<project>/secrets.jsonc | Your dev secret values | pithy setup, pithy add, pithy secrets edit |
<project>/dev.json | Machine-local dev vars, and the dev-login opt-in | pithy dev, and you |
<project>/tokens.json | Minted token values, keyed by environment then variable name, for you to copy into CI | pithy token mint and rotate with the dev-vars store; pithy token forget and revoke take a value out |
<project>/logs/dev.<branch>.<worker>.jsonl | One worker’s last pithy dev session, one record per line | pithy dev; read back by pithy dev logs |
Why it is outside every checkout
Nothing to gitignore. Nothing git add -A can reach. Nothing npm pack can carry.
Delete the whole clone and the secrets are still there.
It is also what lets several projects, and several worktrees of each, run at once with no per-checkout setup step.
secrets.jsonc
Keyed by the registry secret name verbatim — <capability>-<what>, kebab — because that name is the join key into the registry, and a mapping table between the file’s keys and the registry’s names would be one more thing to rot.
Nothing in it names a destination. The registry already knows each secret’s backend, so the seeder derives where a value goes and the file and the registry cannot disagree.
Every entry is a full envelope, even a single-version text secret — which is what makes a JSON secret’s own object distinguishable from an envelope without a heuristic.
Unknown keys are refused, not stripped. A stripping parser once accepted the master key’s own value written bare, dropped a field, and left a base64 string where a nested object belongs — surfacing three frames later, naming neither the file nor the secret.
The Worker’s .dev.vars is generated from this file, not the other way round. Generation is idempotent by content, so a run that changes nothing writes no bytes.
dev-ports.json
One registry for the whole machine.
pithy doctor shows this checkout’s blocks first and unqualified — which ports am I on, and on which branch — then the machine-wide view, each block named by the checkout that holds it. Which is what turns 8847, and I don’t know why into because other-app holds 8827–8846.
Ranges, never block indices. A block’s ports are base + index × size, so the index is the whole answer only while every entry is the same width — and a registry written before the width changed keeps its old entries verbatim.
cloudflare.<name>.json
Mode 0600, in a 0700 directory, outside every checkout.
Nothing secret goes into your project. The account is discovered rather than asked for — the token lists the accounts it can see, one is a confirmation and several are a picker, and choosing the account supplies both its id and the nickname for its credentials file.
A narrowly scoped token that cannot list falls back to asking for an account id, and init still completes.
session.<profile>.json
Mode 0600, outside every checkout, written by pithy cloudflare connect and deleted by pithy cloudflare disconnect. It holds a browser sign-in, not a token anybody made, and every command renews it before it runs.
Which directory uses which profile is profiles.json, beside it. It holds directory names and nothing secret. A repository is bound by its main checkout, so its worktrees share the session, and a bound profile’s session outranks any token in a cloudflare.<name>.json and the environment wherever it applies.
A profile reads its own file, cloudflare.<profile>.json, for the rest. Its Secrets Store id and R2 credentials come from there, then from the environment. Under a profile, cloudflare.json is never read. pithy cloudflare connect looks up the account’s store and records its id there, beside the session’s account id, and never overwrites one already recorded. R2 credentials are not discoverable, so you write them in by hand or export them.
<project>/dev.json
Machine-local dev vars no registry declares, and the dev-login opt-in. The user key is the opt-in, not the file: pithy dev writes other values here too, so a dev.json without user mints no dev login. With it, pithy seed mints one for every seeded user and the one it names is offered first. No user key means sign-in stays magic-link only — which is a state, not a fault.
The rule the whole directory is held to
One optional line’s failure must not cost every other line.
pithy doctor discards every read failure it meets — an unreadable config, a file that will not parse, a .dev.vars it cannot open — and it discards the write to its own notifier cache too, since a config directory that will not take a write is exactly the machine somebody runs doctor on.
A diagnostic has to work in the environment it diagnoses.
Overrides
PITHY_NO_UPDATE_NOTIFIER turns the notifier off without touching the state file.