pithy doctor

Report toolchain state and update status, plus — inside a project — each Worker’s config, binding and migration health.

This is the first command to run when your model of the project and the project disagree. It writes nothing.

Synopsis

pithy doctor [--worker <name>] [--offline] [--enable-notifier | --disable-notifier] [--json]

Flags

FlagMeaning
--worker <name>Check only this Worker. Default: every Worker under apps/
--offlineUse no ambient credentials and make no network call. PITHY_OFFLINE=1 says the same thing to every command
--disable-notifierTurn off the update notifier, persisted in the state file
--enable-notifierTurn it back on
--jsonMachine-readable output — one line, one object, the same exit code

What it reports

$ pithy doctor

pithy 1.2.0 (installed via bun)
Update available: 1.3.0
Run: bun update -g @pithy-sh/cli

Shell: zsh (~/.zshrc)
Alias: installed (`p.` → `pithy`)

Config dir: ~/.config/pithy
State file: ~/.config/pithy/state.json
Dev login:  ~/.config/pithy/acme/dev.json — none yet; sign-in stays magic-link only
Secrets:    ~/.config/pithy/acme/secrets.jsonc (run `pithy secrets edit`)
Ports:      ~/.config/pithy/dev-ports.json
            8787–8806  main
            8807–8826  feature/12-auth
            8827–8846  ~/code/other-app — main
            8947–8966  ~/code/old-thing — main  ← not on disk
Notifier:   enabled (PITHY_NO_UPDATE_NOTIFIER to disable)

Project: pithy.config.ts found
Project capabilities:
  @pithy-sh/core         1.2.0 ✓
  @pithy-sh/auth         1.1.8 (1.2.0 available — run `pithy upgrade --packages`)

Project health:
  api:
    prereqs      every composed capability has its peers ✓
    config       parses against every capability schema ✓
    bindings     MEDIA_BUCKET (r2) missing from wrangler.jsonc — run `pithy worker sync --worker api --env staging`
                 env: staging, prod
    migrations   2 pending — run: pithy migrate --env dev
    entitlements no gated route without a provider ✓
  collab: healthy ✓

Cloudflare: reachable (token active)

Project name: acme — every resource name matches

OS:      macOS 14.5
Runtime: Bun 1.4.2 (Node 26.3.0 compat)

The Project capabilities list reads the project root’s node_modules and every workspace member’s own — the same members pithy upgrade --packages moves — so a package installed only under packages/shared/node_modules is listed and checked for a newer release too. It is one row per package: when two members hold different versions, the first found, root first, is the one listed. That reach is the listing’s alone; the capability checks under Project health look only where a pithy <capability> command does.

The update lines name --latest when the declared range does not admit the newest release. pithy upgrade --packages holds such a release back, so the line names pithy upgrade --packages --latest. When the release also crosses a breaking boundary, a new major or a new minor under 0.x, the line ends Crosses a breaking boundary.. An exact pin or a ~ range left behind by a new minor past 1.0 names --latest with no boundary sentence. A capability at 0.4.2 under ^0.4.2, with 0.5.0 published, reads 0.4.2 (0.5.0 available — run `pithy upgrade --packages --latest`. Crosses a breaking boundary.). An update the range admits names plain pithy upgrade --packages and adds nothing.

The CLI line does the same when the CLI runs from the project’s own node_modules. That copy is one of the project’s packages, so Run: names the project’s package command rather than the installer’s, the same command a capability’s line would name, or the lockfile’s package manager’s install (bun install) when the declared range already starts at the newest release. A CLI 0.24.2 under ^0.24.2 with 0.25.0 published reads Update available: 0.25.0. Crosses a breaking boundary. then Run: pithy upgrade --packages --latest. It stays the installer’s command when --packages would leave that copy where it is: undeclared, linked from a checkout, declared with something other than a registry range, or with a prerelease or deprecated newest release. A global CLI keeps its installer’s command, and the boundary sentence still says when its update crosses one.

Project health

This block is pithy upgrade’s manifest-versus-wiring comparison in read-only mode — one engine, two commands: doctor reports drift, upgrade fixes it.

It is reported per Worker, since each Worker under apps/ carries its own config and drifts independently. A healthy Worker collapses to one line, and the whole block is omitted when every Worker is healthy. Doctor exits non-zero when any Worker fails a check, so CI can gate on it — what fails an exit and what merely has not happened yet is the rule this command is the gate for. Nothing else in the CLI tells you a required binding is missing before deploy does. When something is already broken and you do not know what, diagnosing a broken project starts here.

The migrations line asks the question in both directions, and the second one is why it exists. A migration this project declares that the database has not applied is N pending, and pithy migrate is the remedy. A migration the database has applied that the project no longer declares is a different fault with a different remedy — and it is invisible to a pending count.

On a checkout nothing has set up, every local gap names pithy setup instead. A fresh clone has no .dev.config.json — nothing has pinned its ports — and its gaps are all one gap: no dev master key, dev unmigrated, nothing seeded. So the missing master key names pithy setup, and with no local store dev’s migrations read dev: not set up — run: pithy setup, as does the Secret tables: block’s dev line, and --json’s fix says the same. Once pithy setup, pithy dev or pithy feature create has pinned the checkout’s ports, the narrower commands come back.

A checkout with no local store is not set up, and that does not fail the exit. dev’s store is the Miniflare state under .wrangler/state/v3/d1, and a fresh clone or a CI runner has none. There nothing is read, because opening Miniflare over a store that does not exist would create it, and the next run would count every migration as pending. A store that exists is read and gated as usual, even an empty one: one migration behind is dev: 1 pending with its fix, and fails the exit.

So CI needs no setup step to run doctor. Every check of local dev state reads absent state as not set up and reports it: no local D1 store, no .dev.vars, no dev secrets, no dev.json. Only local state that exists and is wrong fails the exit. Every check of committed files gates the same way, set up or not, such as Worker vars, bindings, the project and Worker names, and environment stanzas. So pithy doctor --offline on a CI runner, with no pithy setup before it, fails on a wrangler.jsonc stanza that drops a declared var, and passes a clean checkout with dev: not set up on its migrations line.

The bindings line covers both halves of a binding, not only the half that is config. A Durable Object needs a durable_objects.bindings entry and an export of its class from the Worker’s entry module, and wrangler refuses the deploy when the second is missing. It covers your Worker’s own app as well: a binding the app declares in requiredBindings that a stanza lacks is named here like any capability’s, and fails the exit, because it is the binding the Worker would refuse to boot on. Each missing binding names the command that writes it. pithy worker sync --worker <worker> writes a D1, KV, R2 or queue binding, with --env <env> when only deployed environments lack it, since a binding one of them composes may be one dev does not; pithy upgrade writes every other kind.

A Worker that composes a scope-gated capability — leaderboard, rating or ledger — gets a scopes line too. Those routes are for your own trusted backend, and each one checks a scope that only auth’s resolveScopes can fill. With no resolver, every one of them refuses every caller, and the runtime cannot tell that from a caller who simply is not trusted. So doctor names each gate. For a Worker composing leaderboard and ledger, that is five:

    scopes       gated routes, no scope resolver. Each refuses every caller.
                 leaderboard: PUT /leaderboard/:board/entries/:userId/hidden needs leaderboard:admin
                 leaderboard: DELETE /leaderboard/:board/entries/:userId needs leaderboard:admin
                 leaderboard: POST /leaderboard/:board needs leaderboard:submit
                 ledger: POST /ledger/:currency/credit needs ledger:admin
                 ledger: POST /ledger/:currency/debit needs ledger:admin
                 Give auth() a resolveScopes in pithy.config.ts. Reported, not failed.

It reports and does not fail the exit. A project can compose ledger for its players’ balances and never move one from a backend, and a red over a route nobody calls is a red nobody can clear. It is never collapsed into healthy ✓ either, because this line is the only place the state is said. Once auth has a resolver, the line reads 5 gated routes, resolved by auth's resolveScopes ✓. A Worker that composes no gate prints no line. In --json it rides under project.health.workers[].scopes, and every gate carries fix: null: which caller to trust is your decision. Server-authoritative writes ranks the three ways to make it.

A Worker that composes a capability processing under consent — email, which tracks opens and clicks and sends marketing mail — gets a consent line. With consent composed, email asks before either, and the line reads 2 purposes, recorded by consent ✓. Without it, email behaves as it always has, and doctor says so:

    consent      processing under consent, with no consent record.
                 email: email.marketing runs with no consent record behind it
                 email: email.tracking runs with no consent record behind it
                 Add consent to record and honor it. Reported, not failed.

It reports and does not fail the exit. Whether a law requires consent for that processing is your call, and the kit records and gates without deciding which law applies. A Worker that processes nothing under consent prints no line. In --json it rides under project.health.workers[].consent, and each purpose’s fix is the pithy add consent that records it.

A Worker that composes the mcp capability gets an agents line. Composing it means choosing a floor — a power, an entitlement, or "signed-in" — and an endpoint that lets any signed-in user drive an agent against your app is a decision worth seeing on every run. Letting your users’ agents in is where the floor is set.

    agents       MCP endpoint open to every signed-in user.
                 Set mcp({ floor }) to a power or an entitlement to narrow it. Reported, not failed.

It reports and never fails the exit: an open endpoint is a choice, not a fault. Behind a power or an entitlement it reads MCP endpoint open only to callers whose role holds agents:use ✓. A Worker with no endpoint prints no line. In --json it rides under project.health.workers[].agents as { composed, open, floor }.

A Worker reachable only over a service binding is not an origin fault. "workers_dev": false, "preview_urls": false and no routes entry close every public address on purpose, so the origins check does not report it as no-origin. All three are required; "workers_dev": false alone is still reported.

When the project shares a resource its Workers do not all point at

Beside the per-Worker blocks sits a shared: section. Two bindings in the kit are project-global — EMAIL_SUPPRESSIONS, because “do not email this person again” is not an environment-local fact, and SUPPORT_BUCKET, because the bytes are written from the app Worker and the bucket takes no environment.

Older projects were scaffolded before a manifest could say so, so pithy add email wrote a per-environment database into every stanza while pithy email provision created the single global one — and the app Worker and the email Worker then read different suppression lists. An unsubscribe recorded through either was invisible to the other.

This section is the only thing that will ever tell such a project it is split. Every other reader keys on the binding name alone, deliberately, so that repointing a binding at your own database is never reported as a missing one. It is project-wide because the finding is that two stanzas disagree, and no Worker’s own block can see that. Carrying the data across is what to do about it.

Shared runtimes

A Shared runtimes: block appears when this project resolves more than one copy of Zod, Kysely or Hono. Every kit package declares those three as peerDependencies, so an installer puts one at the top where your own import { z } from "zod" finds the same copy the kit uses. A peer is a request rather than a guarantee: a range conflict, a --legacy-peer-deps, a pinned resolution or a workspace hoisting differently all reintroduce a second copy. The check asks from the project root and every workspace member, and from each capability package installed in any of them, because pithy add installs a capability in its Worker’s own member.

Capability version skew — two Workers resolving different copies of one kit package — is reported here too, and it does not fail the exit. A capability installed nowhere fails, because every command for it refuses today. Skew refuses nothing: a run picks a copy and succeeds, and a project legitimately mid-upgrade would be red for as long as the upgrade took. The version is read from each resolved package’s own package.json, never from a range in a manifest — a range is what somebody asked for, and the file on disk is what would load. No pithy command is printed, because none of them fixes it.

The locations block

Every line between Config dir: and Notifier: reports a location, not a complaint — and each one is a path nothing in your repository mentions.

Secrets: names your dev secret values at <config>/<project>/secrets.jsonc — the file pithy setup and pithy add mint into, pithy seed reads, and every Worker’s .dev.vars is generated from. It is not in your repository, and that is the point: nothing to gitignore, nothing git add -A can reach, nothing npm pack can carry, and nothing an rm -rf on the working copy destroys. Delete the whole clone and the secrets are still there.

The line names the command as well as the path. A path outside the checkout is one no editor’s file tree reaches and no ls in the project finds, so knowing it is not yet a way to open it — pithy secrets edit is.

Ports: names <config>/dev-ports.json, one registry for the whole machine, and lists what is in it. This checkout’s blocks come first and unqualified — which ports am I on, and on which branch. Everything under them is 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.

← not on disk is the one line here you can act on. Pruning cannot tell a deleted checkout from a moved one — both are a missing directory — so a relocated repository has its blocks freed by the next allocation any project on the machine makes, and nothing anywhere reports that it happened. This row is taken before the sweep, and it means: you renamed that directory.

Dev login: names dev.json, the one config file that is per project rather than per machine — the opt-in that makes pithy seed mint a real session instead of leaving you a magic link. The path is reported whether or not the file exists, because where it would go is most of what anybody asking needs. No file is not a fault; a file that will not parse is, and so is one naming no user.

None of the locations block can fail the exit. A checkout that is gone from disk is information, not drift.

The Cloudflare: line

It answers can I reach the account — a session pithy cloudflare connect bound here, or the bootstrap credential pair, verified against Cloudflare rather than merely read. A configured-but-broken credential fails the exit; an absent one does not, because a project that has not been provisioned yet is a legitimate state. When nothing is configured, the line names the sign-in first, because it is the remedy with no token to make by hand.

It names the profile and the kind of credential, because that decides whether an audit row can name a person. A session is verified as the person it names, then given the same account probe a token gets. It reads signed in as jo@example.com, profile acme. An account token says what it is — token active, an account token — audit rows name the token, not a person — because that is the fact a sign-in would change.

A bound profile decides before anything else may, and each of its three faults fails the exit, because every command run here refuses on the same fault:

  • signed_out — a profile is bound here and has no session on this machine. The line names pithy cloudflare connect --profile <name>.
  • session_conflict — the environment exports a CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID that differs from the session. The line says to unset them; Pithy will not choose between the two.
  • session_expired — the session expired and could not be renewed, usually a dead refresh token. The line names the sign-in.

Offline, none of the three is reported: no command refuses them offline, so the line is not checked.

It prints on every run, and names the file it resolved. Which account am I about to deploy to must never require inspection, and once a machine holds cloudflare.leed.json beside cloudflare.other-co.json, the state alone does not answer it.

The line also says where the credentials came from — the file, the environment, or a session. Naming the resolved file is not the same claim, and the difference is the whole of it: CI has no file at all and authenticates from environment variables, so a report reading from ~/.config/pithy/cloudflare.json was naming a path with nothing at it while a token from somewhere else did the work. A session says from the session in ~/.config/pithy/session.<profile>.json, then names the file each account key came from, because a profile reads its store id and R2 credentials from its own cloudflare.<profile>.json, never from cloudflare.json: SECRETS_STORE_ID from ~/.config/pithy/cloudflare.<profile>.json, R2_CREDENTIALS from the environment, SECRETS_STORE_ID in ~/.config/pithy/cloudflare.<profile>.json not used: the file names account <file account>, not <session account>, or no SECRETS_STORE_ID in ~/.config/pithy/cloudflare.<profile>.json. Absent R2 credentials say nothing, since most accounts have none. In --json it is credentialSource — file, environment, session, mixed, or null when neither key resolved.

PITHY_OFFLINE=1 means no ambient credentials and no network call. Set it, or pass --offline, and Pithy stops reading the credential pair out of the environment and doctor reports not checked instead of probing.

It bites in the one function every command resolves credentials through, and it is inherited by a spawned pithy, wrangler or test runner — which a flag is not. --offline exists on this command because run the diagnostic without touching anything is a thing you say once, at a prompt.

Making PITHY_CONFIG_DIR imply it was considered and rejected: it conflates read config from here with do not use the environment, and CI legitimately means the first without the second. What it does not touch is the credentials file — a value written there was written deliberately; a value in the environment is the one nobody in the room remembers exporting.

Project name:

Every resource this project provisions leads with the root config’s name, and teardown recomputes those names rather than scanning for them — so one edit to name orphans everything while every command keeps exiting 0.

Doctor requires positive evidence before it says so, because <app>-<env>-<resource> is also the ordinary Cloudflare convention and a database you brought with you is not an orphan. Two states fail the exit:

  • drifted — the wiring contradicts the config wholesale: every declared name leads with one and the same other project, and the configured name appears nowhere. That is the only shape a one-string rename can leave.
  • orphaned — a database’s pithy_migrations_owner stamp proves Pithy created it under another project’s name.

Neither state ever advises deleting a resource. A single foreign name, a mix, an unset name and an unreadable wrangler.jsonc all pass — none of them establishes anything.

The settings check

Every other check asks whether something is present — the option key, the binding, the migration. None of them looks at the value, so a project stays green while fromAddress names a domain nobody onboarded and BASE_URL points at a host nothing serves.

A capability declares its own settings check on its Capability object. Two tiers, because they cost different things:

TierAsksCost
localDoes the value parse, is it the right shape, is it right for this environment — validated through the same Zod object the capability’s host Worker validates at bootFree, offline, always run
accountIs the domain a zone here, does the secret have a value, is the database thereOne Cloudflare call, on credentials this report already resolved

Both are faults. A local finding fails the exit. An account finding fails it too — mail that will not send is not a warning — but only when the account was actually reached. When it cannot be, the tier is reported as skipped with the reason and gates nothing. An account check that answered for some environments and not others reports both: what the environments that answered hold is listed among the findings and fails the exit like any other, and the tier is still named as unchecked, because the environment that did not answer established nothing.

A capability that declares nothing is skipped in silence, and that is not a fault.

@pithy-sh/support declares a check for inboxes that cannot answer. A mailed reply is sent from the inbox address the thread arrived at, or from reply.replyToAddress, so each domain in inboundAddresses and reply.replyToAddress must be a sending domain on Email Service, or every reply from it fails at send. For each domain, while reply.enabled is on, doctor finds the active zone that covers it and reads that zone’s sending domains: an enabled entry of that name, or a wildcard above it, passes. A domain no active zone on the account covers is a finding too. The action is the one-time onboarding in the Cloudflare dashboard. A credential that cannot read the sending domains leaves the check unchecked, never passed.

@pithy-sh/media and @pithy-sh/storage each declare a check for records outside visibility.allowed. Narrowing allowed in pithy.config.ts never rewrites a record: making a public file private breaks every link already published, so the kit does not do it behind anyone’s back. Instead, for every deployed environment, doctor names each record whose visibility the policy no longer admits, by id, with the move that resolves it — PATCH the media record or the file to an allowed level, or widen visibility.allowed. Which records exist is a fact about a deployed database, so this is an account check: the local tier says nothing, dev is not read, and an environment that is not provisioned yet is unchecked rather than clean while the others are still asked.

Three checks name the Cloudflare API tokens runtime superseded, because a deployed application holds one and nothing revokes the old ones for you (Upgrading to one token). Each asks only in an environment whose Secrets Store already holds a runtime token: before that, the old token is the one that works. @pithy-sh/secrets names the manager’s own token still in the account, <project>-global-secrets-manager or <project>-<env>-secrets, with the redeploy and the revoke. @pithy-sh/media names a media-storage-credentials still holding the Images and Stream token supplied to pithy media provision, and says to revoke it only if you made it for media. @pithy-sh/media and @pithy-sh/storage name an R2 bundle, media-r2-credentials or storage-r2-credentials, still holding a token beside the key pair, and say to keep that token. A bundle is sealed under a key that never leaves the environment’s manager, so the manager is asked whether it carries the field — a bit, never the value. Each fix is the provision that rewrites the bundle, once your app Workers run this kit.

@pithy-sh/audit declares a check for object lock on the checkpoint bucket, because a checkpoint is evidence only while nothing can replace it, and the Worker cannot see a lock through its binding. For every environment but dev, whose bucket is a local one, doctor asks the account about <project>-<env>-audit-checkpoints. A bucket with no indefinite lock over its checkpoints is the AUDIT_CHECKPOINTS object lock finding, fixed by pithy audit lock --env <env>. A bucket that does not exist yet is the AUDIT_CHECKPOINTS bucket finding, fixed by pithy provision --env <env> --yes and then the lock, because until it exists the audit chain is held to nothing outside the database. A locked bucket says nothing, which is how this check says the lock is in force.

Service bindings:

A Service bindings: block appears when an app’s pithy.config.ts declares a service binding that cannot land. Three faults, each one line under the Worker holding the binding. A loop, printed with its whole path — app-b -> app-a closes a loop: app-a -> app-b -> app-a. — for a config edited by hand that pithy worker bind would have refused. It is the same loop the refusal names, not the same words: doctor starts the path at the alphabetically first Worker and names the edge back into it. A self binding is never a loop here. A target that is no Worker, a service naming neither an apps/ Worker nor a kit Worker, which pithy provision would refuse; pithy worker unbind --from <worker> --binding <NAME> is its fix. A kit Worker nothing composes, such as a binding to email left behind when the last Worker composing email removed it, so the binding names a host nobody deploys. Adding the capability back or unbinding it is the choice, and the line says both.

Each fails the exit: the project’s own files establish it, and the consequence is a deploy that refuses or a call that cannot land. A project whose bindings all land gets no block.

Resource names:

A Resource names: block appears when a stanza names a resource other than the one pithy provision would compose for that Worker. It reads each declared environment’s D1 database_name, R2 bucket_name and queue producer queue, and holds each to the name provision composes from the binding’s pithy.manifest.json: <project>-<env>-<thing> for a binding the Worker shares, <project>-<env>-<worker>---<thing> for one it lists in ownBindings (shared by default, owned when a Worker says so), and <project>-global-<thing> in every environment for one its manifest declares scope: "global", such as email’s EMAIL_SUPPRESSIONS or support’s SUPPORT_BUCKET. <thing> is the binding’s resource when its manifest declares one. One line per binding under its Worker, naming both names and the ways out: add the binding to ownBindings in that Worker’s pithy.worker.jsonc, when it does not own it already and it is not global, or run pithy provision --env <env> --yes --repoint for provision’s name, which for a production environment is a person’s decision rather than a command. A global binding is one resource for the whole project, so its line offers only the repoint: pithy provision and pithy worker sync both refuse a global binding in ownBindings. The run rewrites the name either way, so this is where a hand-chosen name is seen first. An ownBindings entry naming no D1, KV, R2 or queue binding the Worker composes gets a line too: it owns nothing.

It reports and never fails the exit, and writes nothing: a name chosen by hand may be the one you meant, until you say which. The top-level stanza is local dev’s and is not read; pithy worker sync keeps its names. It is in --json as declaredNames.

Kit host bindings:

A Kit host bindings: block appears when a Worker’s Workflow or service binding into a capability host reaches the host that reads another database. A Worker that lists a binding in ownBindings that the host binds, such as DB for email and audit, gets a host of its own, <project>-<env>-<worker>---<capability>, that reads its database (naming). A stanza that still binds the shared host is what a project deployed before that looks like: the Worker’s email jobs never send and its audit chain is never checkpointed.

Each line names the binding, the host it reaches and the host it belongs on, and each environment gets one remedy: pithy provision --env <env> points the binding at the right host, then pithy deploy --env <env> ships it. It fails the exit. A binding into a script that is no kit host of the capability is left alone. A Worker whose ownBindings split storage’s or audit’s paired bindings is not checked, because pithy provision refuses it and names the binding to add.

Biome:

A Biome: block appears when the project’s biome.jsonc or biome.json excludes .worktrees, dist or .wrangler in files.includes with a pattern that starts with *, such as "!**/.worktrees" or "!**/dist". Biome matches such a pattern against the directories above the project too, so it excludes every file of a checkout under a directory of that name. Every pithy feature create worktree lives at .worktrees/<issue>-<slug>, and a project kept, or checked out by CI, under a dist or .wrangler meets the same fault. biome check . there checks no file and exits 1 with No files were processed in the specified paths, which reads as a mistyped path or a broken config and names no pattern.

One line per pattern, naming the file and the lines to write instead: "!.worktrees", which skips the worktrees from the main checkout and lets each worktree check its own files, and "!dist" with "!apps/**/dist" and one "!<dir>/**/dist" for every other top-level directory that holds a workspace member, such as "!packages/**/dist" (.wrangler likewise). It fails the exit: the main checkout checks every file and passes, so the fault stays hidden until a worktree’s or a CI checkout’s lint fails with an error that does not point at it. A project pithy init scaffolds today anchors these exclusions and never meets it. It is in --json as biomeIncludes.

Workers tests:

A Workers tests: block appears when the project’s vitest.workers.config.ts lacks a test binding a composed capability declares. Every capability’s manifest declares how a Workers test config provides each binding its composition checks on the first request, and pithy add writes them, so a project that added a capability before that, or removed a line by hand, is the one this names. A binding the manifest marks optional counts only where the Worker’s config makes the capability require it, as controlplane({ replayBackend: "kv" }) requires CONTROL_PLANE; a config changed after the add is the other case this names. It also names a rate limiter the config states without a namespace_id, which Miniflare refuses and the project’s typecheck fails on.

One line per capability, naming the Workers that compose it, the bindings missing and the limiters incomplete — secrets (api): SECRETS, SECRETS_ENCRYPTION_KEYS missing from vitest.workers.config.ts., auth (app-a, app-b): AUTH_RATE_LIMITER in vitest.workers.config.ts has no namespace_id. — then the remedy: run pithy add <capability> again, which writes the missing ones and fills the id in, or edit them by hand. A binding no test config can provide on its own, such as a Durable Object or a Workflow, is never named. A project with no vitest.workers.config.ts says nothing. It reads files only, prints in both forms and never fails the exit, because a project may test its Workers some other way. It is in --json as testBindings, each entry carrying bindings (missing), incomplete (limiters with no namespace_id) and the fix.

Root imports:

A Root imports: block appears when the project root cannot resolve a package its vitest.workers.config.ts imports. The config loads from the root, and under a package manager that does not hoist, such as Bun’s isolated linker or pnpm, the root resolves only what the root’s own package.json declares, so a package only a Worker declares fails the Workers tests with ERR_MODULE_NOT_FOUND after a clean install. pithy add declares the package a test binding imports as a root devDependency; this names a project where that is missing. Resolution stops at the project root, so a feature worktree cannot pass on the main checkout’s node_modules.

One line per package, with the range a workspace member declares — vitest.workers.config.ts imports @pithy-sh/secrets, which the project root does not resolve. Add "@pithy-sh/secrets": "^0.6.8" to devDependencies in the root package.json. — then the remedy: run your package manager’s install at the project root. A package the root declares and has not installed says so instead. It reads files only, prints in both forms, never fails the exit, and has no --fix. It is in --json as rootImports.

Capabilities declared twice:

A Capabilities declared twice: block appears when the project root declares a capability in its dependencies and a Worker declares it too. A Worker declares the capabilities it composes in its own package.json, which is where pithy add installs them, and two Workers composing one capability each declare it; the root has no Worker, so its runtime declaration is a second one that drifts from the first. A root devDependency, which is how the root resolves a package its vitest.workers.config.ts imports, is never counted.

One line per capability — @pithy-sh/secrets is a runtime dependency of the project root and of api. — then the remedy: take each out of the root package.json’s dependencies. It reads files only, prints in both forms, never fails the exit, and has no --fix. It is in --json as duplicateCapabilities.

Worker vars:

A Worker vars: block appears when a stanza of a Worker’s wrangler.jsonc drops a var. env.<name>.vars replaces the top-level block rather than merging with it, so a var the top level sets and an environment leaves out deploys without it. The check names each one, written by hand or declared with defineVars, with the line to add — api: env.prod.vars has no FEED, which the top level sets. Add "FEED": "x". — and a declared var the top level lacks, and a declared var whose value its schema refuses. A declared var a stanza holds at the top level’s value, where the declaration gives that environment its own, is named too, because a new env.<name> stanza starts with the top level’s vars: api: env.prod.vars sets READY_AFTER_MINUTES to 15, the top level's value, where the Worker declares its own for prod. Set "READY_AFTER_MINUTES": 30, or run pithy worker sync --worker api.

A var the CLI writes with each environment’s own value is never suggested at the top level’s: a missing ENVIRONMENT is suggested at the stanza’s own name, and BASE_URL and VECTOR_PROVISIONED are left out, because the top level holds dev’s address and dev’s provisioning record and the stanza gets its own from pithy worker sync or pithy vector provision. A stanza with no vars block at all is the inheritance block’s finding. It reads files and each Worker’s pithy.config.ts, prints in both forms, and has no --fix. A finding about a declared var fails the exit, because the Worker’s own config says what the stanza must hold and the deploy silently runs another value: a declared var a stanza lacks or holds at the top level’s value names pithy worker sync --worker <dir>, which writes every such var, and a value its schema refuses is yours to fix by hand, because sync keeps a value you wrote and only reports it. A var the top level sets by hand, which no declaration covers, reports only and never fails the exit: nothing says what its value should be in that environment. It is in --json as varStanzas.

A Support search: block appears when a deployed environment’s pithy_support_search is provisioned with no triggers maintaining it, when search.fts is on and the index was never provisioned, or when the read that would have established it did not happen.

The support full-text index is maintained by database triggers. pithy support provision creates them beside the virtual table. No message write path calls an index function any more, so a project that upgrades @pithy-sh/support and deploys without re-running pithy support provision has a Worker that indexes nothing and a database whose triggers were never created. Nothing fails. Messages are stored, readable, and quietly absent from the search box.

One line per deployed environment, and only for an environment with something to say:

  • A table with no triggers: prod: pithy_support_search is provisioned and has no triggers, so nothing indexes a new message. Run pithy support provision --worker api. The command creates the triggers and backfills the messages written while none existed.
  • No index at all: prod: search.fts is on and pithy_support_search is not provisioned, so search is a LIKE scan. Run pithy support provision --worker api. search.fts is on by default, so this is every project that upgraded and has not re-provisioned. Search still works, through the LIKE fallback; the command builds the index and backfills it.
  • A partial trigger set: prod: pithy_support_search has only some of its triggers, so some writes are not indexed. Run pithy support provision --worker api. Two of three is drift, not a pass.
  • Triggers with no index: prod: pithy_support_search is gone and its triggers are not, so every message write fails. Run pithy support provision --worker api.
  • An environment with no app database: prod: not provisioned — env.prod has no DB database_id, so there is no index to check. Read from files, so it is true offline too.
  • A read that did not happen: prod: skipped — offline, so no index was read., or prod: skipped — no Cloudflare credentials, so no index was read. Said out loud on purpose: a skip that printed nothing would be indistinguishable from a healthy project.

Only a drift, a missing index or triggers with no index fails the exit; a skipped read leaves the exit alone, on the same rule the migration lines follow. A project that composes no support, or composes it with search.fts off, reaches no database and prints nothing. It is in --json as supportSearchTriggers.

Secret tables:

A Secret tables: block appears whenever a Worker declares a secret table (defineSecretTable — see Declared tables), in both forms of the report. Its first line names every declared table and its keys; then one line per environment, dev first:

  • Every row on the newest key: prod: every row on key v4., or dev: no rows yet. for an empty vault.
  • A checkout with no local store: dev: not set up — run: pithy setup. Nothing is opened, because opening the local store would create it.
  • Rows a rotation did not reach: prod: 12 rows not on key v4 — the last at-rest rotation did not reach them. The at-rest rotation re-encrypts row by row, so a pass that stopped partway across a large customer table leaves rows on the previous key. They still open, and nothing else says so.
  • A table declared and not migrated there: staging: … customer not migrated. Run pithy migrate --env staging.
  • A read that did not happen: prod: not provisioned — env.prod has no SECRETS database_id, so there is nothing to read., prod: skipped — offline, so no table was read., prod: skipped — no Cloudflare credentials, so no table was read., prod: could not be read, so whether every row is on the newest key is unknown., or prod: pithy.config.ts did not compose for prod, so no table was read.

The newest version is what the rows say — the CLI cannot read the master key — and the read is counts and key versions, never a value and never an owner: the same read pithy secrets tables prints. It reports and never fails the exit. A rotation can be mid-pass while doctor runs, and the remedy for a row behind is the next scheduled pass rather than a command anybody types; a row behind, or a read that did not happen, keeps the report verbose instead. It is in --json as secretTables, where dev with no local store is the state not-set-up, with fix pithy setup, and counts as read for the block’s ok.

Secret rotations:

A Secret rotations: block appears when a Worker composes secrets and an environment’s ledger holds a failed rotation, or could not be read; a healthy ledger, and an environment not provisioned yet, say nothing. A secret that declares rotateEveryDays is rotated by its environment’s secrets manager at 03:00 UTC with nobody watching (see unattended rotation), and this is where a failure there surfaces. It reads each environment’s rotation ledger for the newest closed attempt per declared secret:

  • Nothing failed, beside an environment that did: prod: no failed rotation.
  • A failed rotation: prod: 1 secret's last rotation failed., then one line per secret with the day and what the code means — CLOUDFLARE_API_TOKEN — 2026-10-18: the issuer rolled and the store did not take the value — the old credential is dead, act now. A previous version held because a value sealed under it was not re-encrypted reads rotated, and the previous version is kept until what is sealed under it is re-encrypted.
  • A read that did not happen: prod: not provisioned — …, prod: skipped — offline, so no ledger was read., prod: could not be read, so whether a rotation failed is unknown., or prod: pithy.config.ts did not compose for prod, so no ledger was read.

The read is the status read the control plane publishes: a name, an instant and a code, never the ledger’s text. dev is never asked, because nothing rotates there on its own. It reports and does not fail the exit, but for the one case below: the remedy is in the code — a human at the issuer, the next scheduled tick, or a dependent re-encrypting — and none of them is a command this report can name for every case. It is in --json as secretRotations.

One rotation fails the exit: the field key’s. The block also reads the newest closed rotation of the key encrypted fields seal under, listed as PITHY_FIELD_KEYS. When it closed field-key-overdue — a field-key version still live when the next rotation came due — or field-key-ceiling — a rotation refused at four live versions — the exit fails, under failures[].check secretRotations, with no fix. The remedy is a person’s: fix what the guard names in the manager’s secrets/field_key_retirement_blocked audit event, or retire the version with pithy secrets retire-version at a terminal. Every other failed rotation, the field key’s unconfirmed write included, reports and does not gate.

Payments allowances:

A Payments allowances: block appears in a verbose report whenever a Worker composes payments. It names each kit meter, whether it is enforced and whether a quota of its name is declared, then every deployed environment’s unrestricted subjects by name.

  • A meter: api: emails meter enforced; a emails quota is declared., or api: storageBytes meter advisory; no storageBytes quota is declared. A meter is advisory until meters.<name>.enforce turns it on, and a declared quota left advisory reads as a limit and binds nothing.
  • Who holds the whole product: prod: unrestricted — organization:acme. Every quota unlimited and every feature on, for every name declared now or later., or prod: no subject is unrestricted. unrestricted is the largest grant the kit has and the only one whose reach grows by itself, so it is never left to a row nobody opens.
  • A read that did not happen: prod: skipped — offline, so no override was read., prod: skipped — no Cloudflare credentials, so no override was read., prod: not provisioned — env.prod has no DB database_id, so no override was read., prod: could not be read, so who is unrestricted is unknown., or prod: pithy.config.ts did not compose for prod, so no override was read.

One SELECT on pithy_payments_overrides per deployed environment whose composition includes payments. A project that composes no payments reaches no database and prints nothing. An unrestricted subject keeps the report verbose, and nothing here fails the exit: an Enterprise contract and your own account are legitimate grants. Tiers, quotas and features is what the meters and unrestricted mean. It is in --json as paymentsAllowances.

Audit sinks:

An Audit sinks: block appears whenever a Worker’s audit({ sinks }) declares one (shipping the trail) — in a verbose report, and in a terse one while a token is missing. It lists every sink, then whether each deployed environment holds each sink’s token.

  • A sink: api: siem — splunk-hec to splunk.example.com:8088; every action; redacted; token splunk-hec-token. Its profile, the host it posts to (never the path or query, which may carry a key), its action filter, whether it ships IP, user-agent and metadata values or their hashes, and the @pithy-sh/secrets name its token is read through.
  • A token that is set: prod: splunk-hec-token is set.
  • A token that is not: prod: splunk-hec-token is not set, so its sinks retry every event until it is dead-lettered. Run pithy secrets create splunk-hec-token --env prod.
  • A question that was not asked: prod: skipped — offline, so splunk-hec-token was not asked about., prod: skipped — no Cloudflare credentials, so splunk-hec-token was not asked about., or prod: could not ask whether splunk-hec-token is set.

One question to each deployed environment’s secrets manager per distinct token; dev is never asked. A project that ships nothing asks nothing and prints nothing. An unset token keeps the report verbose and does not fail the exit, on the same standard as any unbound secret. It is in --json as auditSinks.

Retention:

A Retention: block appears whenever a Worker declares a retention block or composes the control plane (retention and legal holds). It shows in a verbose report. A terse report shows it too while a block is refused, a legal hold stands, or something could not be checked: an environment that did not compose, or a hold count that was skipped or failed. It gives each Worker’s effective retention, resolved the way the Worker resolves it at assembly: every purge window and where it came from, the audit default and each rule (a (floor) rule is the kit holding a control-plane or lifecycle action at a year), and each class age. Then each deployed environment that has something to say about its legal holds.

  • A Worker’s retention: api: user purge 30d (capability); audit kept forever; inactive past pii 3y. A window from the Worker’s own block reads (policy). Under an audit default, the line reads audit 90d by default, and then every rule, longest prefix first.
  • A block that will not deploy: api: the retention block is refused, so it will not deploy. followed by the refusal, which names the rule and the floor it is under.
  • Holds standing: prod: api has 2 legal holds standing. No purge, prune or inactivity deletion touches a held subject. An environment with none prints nothing.
  • A count that did not happen: prod: skipped — offline, so api's holds were not counted., prod: skipped — no Cloudflare credentials, so api's holds were not counted., or prod: could not count api's legal holds.

One SELECT on pithy_controlplane_holds per deployed environment whose composition includes the control plane; dev is never asked, and an environment with no app database is passed over. Nothing here fails the exit: a refused block is refused again when the Worker assembles, and a hold is a decision someone made. It is in --json as retention.

Attestation:

An Attestation: block appears when a production environment’s auth sets its attestation block to test. Test mode accepts a documented test assertion in place of a real app’s, so a simulator or CI gets through. In production that would let any caller through. Production is prod and every name in the root config’s seed.productionEnvironments, and each Worker is read from its composition for that environment:

Attestation:
  api: prod sets auth's attestation to test, which accepts a test assertion in place of a real app. Set attestation.environments.prod.mode to enforce in apps/api/pithy.config.ts. A production Worker refuses the test assertion anyway, and pithy deploy refuses the environment.

It fails the exit, with fix: null: the remedy is an edit to pithy.config.ts. The Worker accepts the test assertion only where its ENVIRONMENT is dev, staging or feature, whatever its config says; this reports the configuration before it ships. pithy deploy --env <name> refuses the same configuration. It is in --json as attestation.

Carrying the data across

The shared: section names this page rather than printing a pair of wrangler commands, because the obvious pair does not work and one half of it is destructive. It used to print export each old database, then execute it against the expected one. Run exactly as printed, that reports success and copies nothing:

  • wrangler d1 defaults to local. With no --remote the export reads .wrangler/state, prints Resource location: local and Done!, and exits 0. The next line on screen is the repoint, so you run it believing production was copied — and production is live on an empty database.
  • A whole-database export cannot be imported into a provisioned destination. The dump carries pithy_migrations, pithy_migrations_lock, pithy_migrations_owner, a DELETE FROM sqlite_sequence, and an explicit id on every row. The destination already holds all of that. The execute aborts transactionally on the first UNIQUE constraint failed and the whole file rolls back, so the count afterwards is 0.
  • A table-scoped export still collides on id. Every environment’s database allocated id from 1, so importing the first environment succeeds and the second fails.

So the copy is a narrow, table-scoped export plus a text edit — and a text edit is not a command.

One. Export one table from the remote database. Not the whole database, and never the local one.

Two. Edit the export. Two changes to every statement: name the columns and drop id, from the column list and from the values; and append an ON CONFLICT clause deciding which row survives when two environments suppressed one address.

before: INSERT INTO pithy_email_suppressions VALUES(1,'a@example.com','hard_bounce',...);
after:  INSERT INTO pithy_email_suppressions
          (email,reason,job_id,environment,detail,created_at,expires_at)
          VALUES('a@example.com','hard_bounce',...)
        ON CONFLICT(email) DO UPDATE SET
          reason=excluded.reason, job_id=excluded.job_id, environment=excluded.environment,
          detail=excluded.detail, created_at=excluded.created_at, expires_at=excluded.expires_at
        WHERE excluded.expires_at IS NULL AND pithy_email_suppressions.expires_at IS NOT NULL
           OR (excluded.expires_at IS NULL)=(pithy_email_suppressions.expires_at IS NULL)
              AND (excluded.expires_at>pithy_email_suppressions.expires_at
                   OR excluded.expires_at IS pithy_email_suppressions.expires_at
                      AND excluded.created_at<pithy_email_suppressions.created_at);

Three. Apply it to the remote project-global database. Four. Repeat for each environment, then count what arrived.

cd apps/<worker>

wrangler d1 export acme-staging-email-suppressions --remote \
  --table pithy_email_suppressions --no-schema --output staging.sql

wrangler d1 execute acme-global-email-suppressions --remote --file staging.sql

wrangler d1 execute acme-global-email-suppressions --remote \
  --command "select count(*) from pithy_email_suppressions"

Run them from the Worker’s own directory. A Pithy project has no wrangler.jsonc at its root — every Worker owns one, under apps/<name>/ — and wrangler reads the config beside it. Run from the project root, where pithy doctor printed the link, every command here exits 1 before it reaches Cloudflare.

--remote on every command, every time. --table and --no-schema keep the migration ledger and the CREATE TABLE out of the dump, so the destination’s own schema and applied-migration rows survive. Dropping id lets SQLite allocate a fresh one per row. The ON CONFLICT clause is what makes the whole thing re-runnable.

Which row wins, when two environments suppressed one address. email is not null unique, so those two rows merge into one and may disagree about reason and expires_at. “Do not email this person again” is not a field to lose a coin toss over, so the clause decides it, in this order:

  1. A permanent suppression beats a temporary one. A null expires_at replaces any non-null one and is never replaced by one.
  2. Between two temporary ones, the later expiry wins. The address stays suppressed for as long as any environment asked.
  3. Otherwise the earlier created_at wins, so the merged row dates from the first time anybody said it.

In practice it is nearly always the third: every suppression the kit itself writes is permanent, so two rows you actually find agree on the first test and the decision falls to the date. The whole row moves together — reason, environment and detail come from the row that won, never from a mix. The result does not depend on the order you run the environments in, and re-running a file changes nothing.

When two databases answer to one name

The sequence above addresses each database by name, which is right for the split shared: usually reports — the stanzas name different databases, and each name resolves. It is wrong for the other shape. Two stanzas carrying the project’s one name and two different database_ids are two databases answering to one name, and against wrangler 4.130.0 that name resolves to neither. Only the binding-and-environment form reaches either:

cd apps/<worker>

wrangler d1 export EMAIL_SUPPRESSIONS -e staging --remote \
  --table pithy_email_suppressions --no-schema --output staging.sql

wrangler d1 execute EMAIL_SUPPRESSIONS -e prod --remote --file staging.sql

wrangler d1 execute EMAIL_SUPPRESSIONS -e prod --remote \
  --command "select count(*) from pithy_email_suppressions"

wrangler matches the argument against the database_name and the binding of every entry in the selected environment’s stanza, and returns that entry’s database_id without ever consulting the account. So the stanza is the address and the shared name never comes up. Here the Worker’s own directory is load-bearing rather than merely required, and two Workers that each declare the binding are addressed one at a time, from each one’s own directory — -e names an environment, and it cannot tell two Workers’ stanzas apart.

Which environment is which is the decision the report leaves you: pithy provision resolves the expected name on your account and writes whatever that resolves to into every stanza, having never read the ids. Work out which id that is first, make it the destination, and run the repoint only once the rows are in it.

For R2 there is no equivalent to write down

Syncing a bucket is an S3-protocol job, so it is rclone, aws s3 sync, or anything else that speaks S3, pointed at R2’s S3 endpoint with a key pair from R2 → Manage API tokens. A Cloudflare API token cannot do it, which is why Pithy does not offer to. Object keys are unique per bucket, so there is no merge question.

--json

--json mirrors every block, because an agent cannot read aligned columns. One line, one object, and the same exit code, carrying schemaVersion like every other payload.

Three rules hold across the payload.

Paths are absolute here, never tilde-abbreviated — this output is opened by a script, not recognized by a person.

A check with no project to run against is null, not an empty verdict. project, projectName, workerNames, selfBinding, serviceBindings, declaredNames, biomeIncludes, testBindings, rootImports, duplicateCapabilities, varStanzas, environments, origins, workflows, attestation, devPreferences, devSecretsFile, devSecrets, secretBindings, devVarsLocal and devVars all take that shape, so nothing ever reports a name verdict for a directory that has no config.

A check that threw is neither of those. Every probe is guarded, so one that fails costs its own line rather than the report — and it says so on its own value rather than being filed under null. Several report "state":"could-not-check"; cloudflare reports "state":"probe_failed", distinct from not_checked, which is the caller having said not to look. None of these states fails the exit: a check that did not run established nothing.

And every finding carries its own detail sentence beside its fields, so an agent fixing one never has to reproduce the report’s wording from the parts.

failures is the exit, as a list. Every check that fails pithy doctor is one entry there and nothing else is, so failures is empty exactly when the exit is 0 — a script reads one or the other and gets the same answer. Each entry carries fix, built from the finding’s own fields and never from a printed sentence — a self-administering project whose staging stanza binds no SELF reads {"check":"selfBinding","detail":"api: staging binds no SELF — …","fix":"pithy provision --env staging --yes"}.

fix is a whole pithy command an agent runs as written, or null, and null is the honest answer in three cases. The remedy is an edit: a stanza to add, a name to change, a line in pithy.config.ts to delete. The remedy is a person’s: provisioning a production environment needs its --confirm phrase. Running the command blind would lose data: repointing a project-global binding before its rows are carried across leaves it empty. The commands that do appear:

Checkfix
selfBindingpithy provision --env <env> --yes — null for a production environment
serviceBindingspithy worker unbind --from <worker> --binding <NAME> for a binding whose target is no Worker; null for a loop or a kit Worker nothing composes, which are choices
hostBindingspithy provision --env <env> --yes, which rewrites the binding to the host that reads the Worker’s database; a pithy deploy --env <env> ships it — null for a production environment
originspithy worker sync --worker <worker> --env <env>, for an origin a domains declaration names and nothing serves
workflowspithy worker sync --worker <worker> --env <env>, for an unsynced stanza
varStanzaspithy worker sync --worker <worker> for a var the Worker declares and a stanza lacks or holds at the top level’s value; null for a declared var whose value its schema refuses, whose detail names the edit
supportSearchTriggerspithy support provision --worker <worker>
settingsThe capability’s own command, where its finding names one
projectpithy add <peer> --worker <worker> for a missing prerequisite, and pithy add <capability> --worker <worker> for a capability composed and installed nowhere — each with --with-prerequisites when it brings a prerequisite that Worker lacks, and null when it has an option with no default that the Worker’s config does not already state, which is a person’s choice; pithy worker sync --worker <worker> for a missing D1, KV, R2 or queue binding, with --env <env> naming the first environment that lacks it when dev does not; pithy upgrade --worker <worker> for a missing option, any other binding, or an entry export; pithy migrate --env dev for dev’s pending migrations, or pithy setup when the checkout nothing has set up holds a local store that is behind. A checkout with no local store adds no entry

Everything else that fails the exit — credentials, the project name, a stamp, an environment declaration, a config that throws, a dev.json, a decline, an entitlement gate nothing resolves, a Biome exclusion to anchor, a declared var’s value its schema refuses, a production environment in attestation test mode — carries fix: null.

Every finding carries fix in its own block too, gated or not. A finding that reports and never gates — a deployed environment’s pending migrations, an unbound secret, an AI client nobody connected, a missing test binding, a Worker whose .dev.vars holds nothing, a Turnstile sitekey nothing renders — is a fault all the same, so each entry of a finding list carries fix on the same rule. A deployed environment’s pending migrations name pithy migrate --env <env>. An unbound secret the kit composes carries null: pithy secrets provision mints it, and runs against every environment, production included, so it is a person’s decision. One only you have names pithy secrets create <secret>, with --env <env> unless the secret is global. An unconnected AI client names pithy docs connect --client <id>; a capability missing test bindings names pithy add <capability> --worker <worker> for the first Worker composing it, a re-run that writes the missing test bindings, fills a missing rate-limiter namespace_id in, and wires nothing else; an empty .dev.vars names pithy seed --env dev. An environment where a declared secret table is not migrated names pithy migrate --env <env>; a row behind the newest key carries null, because the next scheduled at-rest pass moves it, not a command.

A root import the project root cannot resolve carries null too: the remedy is a line in the root package.json’s devDependencies, then an install at the root, and no pithy command makes either.

A capability the root declares beside a Worker carries null as well: the remedy is taking the entry out of the root package.json’s dependencies, and no pithy command does it.

A declaredNames mismatch, and an ownBindings entry that owns nothing, carry null: each is a decision, to own the binding or to repoint it.

KeyTypeMeaning
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
cliobjectThe installed version, the latest known, the detected installer, the state, and the command that upgrades it
shellstring or nullThe detected shell
aliasobjectstate (installed, not-installed, unknown), rcPath, and reason — the refusal’s own sentence, null on the two known states
configDirstringThe config directory
stateFilestringThe notifier state file
notifierstringenabled or disabled
offlinebooleanWhether this run refused ambient credentials and the network
projectobject or nullpresent, then either loadError or the project’s capabilities and health. null outside a project
cloudflareobjectstate, missing, tokenStatus, credentialSplit, configPath, accountName, accountMismatch, credentialSource, session, credentialKind, accountKeySources, detail. session carries the bound profile, via (directory or default), the signed-in email and the session file’s absolute path, or is null when no profile is bound; credentialKind is session, account-token, user-token, or null when none resolved or its kind cannot be told. Under a bound profile, accountKeySources maps SECRETS_STORE_ID and R2_CREDENTIALS each to file (the configPath file, the profile’s own), environment, other-account (the file holds one but names another account than the session’s, so it went unused), or null; it is null where no profile is bound
projectNameobject or nullstate, project, misnamed, detail
workerNamesobject or nullstate, and one mismatches entry per stamp that disagrees
docsMcpobject or nullstate, findings, clients, detail — any detected AI client that cannot read the Pithy docs, and the pithy docs connect command for each. Each entry in clients carries its client id, label, fix, and paths: every file the check read for it, one per scope, absolute. Those files follow CLAUDE_CONFIG_DIR and CODEX_HOME as pithy docs connect does. Never gates the exit
testBindingsobject or nullstate (ok, missing, could-not-check), one missing entry per composed capability whose test bindings vitest.workers.config.ts lacks or states incompletely — its capability, the workers composing it, the bindings missing, the rate limiters stated with no namespace_id as incomplete, a detail sentence and the fix — and one findings line per entry, or the one line saying the check could not run. null outside a project, or when its Workers did not resolve. Never gates the exit
rootImportsobject or nullstate (ok, unresolved, could-not-check), one unresolved entry per package vitest.workers.config.ts imports that the project root does not resolve — its file, the package, whether the root already declared it, the line to add to the root’s devDependencies (or null when no workspace member names a range), a detail sentence and a fix that is always null — and one findings line per entry, or the one line saying the check could not run. null outside a project. Never gates the exit
duplicateCapabilitiesobject or nullstate (ok, duplicated, could-not-check), one duplicates entry per capability the project root declares in dependencies beside a Worker that declares it — its package, the members declaring it (. for the root, then each apps/ Worker), a detail sentence and a fix that is always null — and one findings line per entry, or the one line saying the check could not run. A root devDependency is never one. null outside a project. Never gates the exit
varStanzasobject or nullstate (ok, faulty, could-not-check), one vars entry per finding — its worker, kind (missing, invalid or copied), stanza (vars for the top level, env.<name>) and name; for missing whether it is declared and the line to add, for invalid the value and the problem, for copied the value the stanza holds and the line that sets the environment’s own — each with a detail sentence and a fix, and one findings line per entry, or the one line saying the check could not run. null outside a project. Every invalid and copied entry, and every missing entry whose declared is true, fails the exit with a failures entry of check varStanzas; a missing entry whose declared is false never does, and neither does could-not-check
selfBindingobjectstate, declared, missing — the binding a self-administering project needs
serviceBindingsobject or nullstate (ok, could-not-check, faulty) and one faults entry per service binding that cannot land — kind is loop, missing-target or uncomposed, with worker, binding and target, or for a loop path — each carrying its own detail and fix. faulty fails the exit
hostBindingsobject or nullstate (ok, stale, could-not-check) and one stale entry per Workflow or service binding a declared environment’s stanza points at a kit host that reads another database than its Worker’s — worker (the apps/<dir>), env, binding, capability (whose host it reaches), boundTo (the host script the stanza binds) and expected (the host script that reads the Worker’s database) — each carrying its own detail and fix. stale fails the exit. null outside a project
declaredNamesobject or nullstate (ok, drifted, could-not-check); one mismatches entry per declared environment’s binding whose stanza names another resource than provision would compose — worker (the apps/<dir>), env, binding, kind (d1, r2, queue), declared, expected, owned, whether the Worker owns the binding, and global, whether its manifest declares it scope: "global", so expected is <project>-global-<thing> and the remedy never offers ownBindings; and one unrecognized entry per ownBindings entry naming nothing the Worker composes, with worker and binding. Each carries its own detail and fix, always null. Never gates the exit
featureRatelimitIdsobjectstate, findings — rate-limiter ids a feature environment stranded
biomeIncludesobject or nullstate (ok, could-not-check, unanchored) and one findings sentence per files.includes pattern that excludes .worktrees, dist or .wrangler unanchored, naming the file and the lines to write instead. Sentences, not objects, so they carry no fix; the failures entry carries fix: null. unanchored fails the exit
environmentsobject or nullstate, declared, and one drift entry per Worker-and-environment that disagrees — kind is undeclared, missing or orphaned
environmentInheritanceobjectstate, unrepeated — a value a stanza inherits where wrangler does not inherit it
environmentConfigsobjectunresolved, detail
turnstileSitekeysobjectstate, stranded, unrendered, detail
originsobject or nullstate, and one drift entry per Worker-and-environment whose named and served origins disagree — fault is no-origin, unserved-origin or workers-dev-open
workflowsobject or nullstate, and one drift entry per Worker-and-environment whose declaration and stanza are not the same table
attestationobject or nullstate (ok, findings, could-not-check), and one findings entry per Worker-and-production-environment whose auth sets attestation to test: worker and environment, with its detail and fix: null. A finding fails the exit
supportSearchTriggersobject or nullstate (ok, not-applicable, could-not-check, findings), and environments, one entry per deployed environment per Worker composing support with search.fts on, each with its env, worker, state and fix
secretTablesobject or nullstate (ok, not-applicable, could-not-check, findings); declared, every declared secret table with its worker, table, keys and secrets; environments, one entry per environment, dev first, each with its env, its state (read plus newestKeyVersion, behind and notMigrated, not-provisioned, skipped plus reason, unreadable, not-composed) and its fix; and detail, the report’s lines. findings is a row behind the newest key. Never gates the exit
secretRotationsobject or nullstate (ok, not-applicable, could-not-check, findings); environments, one entry per declared environment, each with its env, its state (read plus failed — each with name, at and reason, a code or null — not-provisioned, skipped plus reason, unreadable, not-composed) and its fix, always null; and detail, the report’s lines. findings is a secret whose newest closed rotation attempt failed. Gates the exit only for the field key, on field-key-overdue or field-key-ceiling
paymentsAllowancesobject or nullstate (ok, not-applicable, could-not-check); meters, one entry per kit meter per Worker composing payments, each with its worker, meter (emails, storageBytes, mediaItems), enforced and quotaDeclared; environments, one entry per deployed environment per Worker composing payments, each with its env, worker and state (listed plus subjects, every kind:id that is unrestricted, not-provisioned, skipped plus reason, unreadable, not-composed); every entry’s fix is null; and detail, the report’s lines. Never gates the exit
auditSinksobject or nullstate (ok, not-applicable, findings, could-not-check); sinks, one entry per sink a Worker declares, each with its worker, sink, profile (splunk-hec, datadog-logs, webhook), host, actions (empty for every action), detail and secret, and fix null; secrets, one entry per deployed environment per distinct token, each with its env, secret and state (set, unset, unreadable, skipped plus reason), and fix — the pithy secrets create that sets an unset token, null otherwise; and detail, the report’s lines. Never gates the exit
retentionobject or nullstate (ok, not-applicable, findings, held, could-not-check); workers, one entry per Worker with its effective retention (null when refused) and refused, the refusal or null; holds, one entry per deployed environment and Worker composing the control plane, state counted with standing, not-provisioned, skipped with its reason, or unreadable. Never gates the exit
extensionsobjectOne entry per capability extension this project composes — its kind, id, the tables it adds, and a detail sentence
portsRegistryobjectpath, present, root, entries — every block on the machine, each with own, onDisk and orphaned
devPreferencesobject or nullstate, path, user, detail — the dev.json this project resolves
devSecretsFileobject or nullpath, present, orphans — reported whether or not the file exists
devSecretsobject or nullThe dev-secrets findings. healthy is the one field to gate on. mode is octal-formatted (600), because 384 is not a permission anybody recognizes
secretBindingsobject or nullstate, one missing entry per Worker-and-environment-and-binding a declared environment does not bind
settingsobject or nullstate, account (checked or skipped, with the reason), checked, one findings entry per setting that does not work, and unchecked
sharedRuntimesobjectduplicated, copies, detail — every resolved copy of zod, kysely and hono
localDeliveryobject or nulllive — whether a message sent from this machine leaves it, from every host that sends one — the capability that answers for delivery, a detail, and hosts, one verdict per sending host: host (its dev-set name, email or <owner>---email for a Worker that owns its database), live and detail. A Worker’s own host is decided by that Worker’s config, as pithy dev decides it. Never gates the exit
devVarsLocalobject or nullThe root .dev.vars.local classification
devVarsobject or nullThe root .dev.vars classification — names only, never a value
osstringThe operating system and its version
runtimeobjectname, version and nodeCompat — the interpreter that ran
nodestringThe Node version it emulates. Equal to runtime.version on Node, different under Bun
failuresobject[]Every check that fails the exit, in report order: check (the block’s key above, project for project health), detail (the sentence, naming the Worker and environment), and fix — a pithy command that rights it, run as written, or null. Empty exactly when the exit is 0

runtime names the interpreter actually executing. Under Bun, process.versions.node is the Node version being emulated, so reporting it alone would name a runtime that is not running — the one thing a diagnostic must not do.

Errors

Nothing here refuses except a flag doctor does not take and a contradiction between two flags. Doctor is a report, and what it finds is carried in the exit code rather than in a throw — a diagnostic has to work in the environment it diagnoses, so every read failure it meets is discarded into a line.

So doctor exits one of three ways: 0 when every gating check passes, 1 when one fails — the report is the answer, and failures names each one with its fix — and 2 for a call it refuses. It never exits 3, 4 or 5: a missing precondition or an unreachable account is a finding on its line, not a refusal.

ConditionEffect
A flag doctor does not declare — --env, --bogus-flagRefused before anything is read, exit 2: Unknown flag: --bogus-flag. then the flags doctor takes
--disable-notifier and --enable-notifier togetherRefused before anything is read, exit 2
A pithy.config.ts that will not loadExit 1
A Worker failing a config, binding, dev migration or entitlement check, or a manifest nothing can readExit 1
A checkout with no local D1 store, so dev is not set upExit 0. Reported on the Worker’s migrations line, with pithy setup as its fix. A store that exists, even an empty one, is read and gated by the row above
A deployed environment’s migrations pending, undeclared, unprovisioned or skippedExit 0. Reported on the Worker’s migrations line, never gating
A Worker whose plan could not be built, or a dev database whose ledger could not be readExit 1. A check that did not run established nothing, and a healthy verdict around a hole is the under-report this block exists to prevent
A Cloudflare credential that is configured and broken, a pinned account the credentials do not match, or a bound profile that is signed out, overridden by the environment, or expiredExit 1. not configured and not checked establish nothing, so neither gates
A project name that is invalid, drifted or orphanedExit 1
A Worker whose three names disagreeExit 1
A declared Worker var that a wrangler.jsonc stanza lacks, holds at the top level’s value where the declaration gives that environment its own, or sets to a value its schema refusesExit 1. The failures entry’s fix is pithy worker sync --worker <dir> for a lacking or copied var, and null for a refused value, whose detail names the edit. A var no declaration covers that a stanza lacks is reported and never gates
A Worker whose Workflow or service binding reaches a kit host that reads another databaseExit 1
A production environment whose auth sets attestation to testExit 1, with fix: null
A support search index with no triggers or only some of them, triggers that outlived their index, or search.fts on and no index provisionedExit 1
A dev.json that will not parse, or that names no userExit 1. No file at all is the documented default and never gates
A capability setting that does not work, from either tierExit 1. The account tier contributes findings only when the account was reached
A settings check that could not be run, or an account that could not be reachedNever fails the exit. Reported as skipped or unchecked, never as a pass
Local delivery running on the simulatorNever fails the exit. It is a choice, and offline it is the only one
Toolchain state — the CLI version, the shell, the aliasNever fails the exit

Examples

When everything is up to date, the output is correspondingly terser:

$ pithy doctor

pithy 1.3.0 (installed via brew)
Up to date.

Shell: zsh
Alias: installed

Secrets: ~/.config/pithy/acme/secrets.jsonc (run `pithy secrets edit`)

Project: pithy.config.ts found
Project capabilities: all up to date

Cloudflare: reachable (token active)

OS:      macOS 14.5
Runtime: Bun 1.4.2 (Node 26.3.0 compat)

The Secrets: line survives into the terse report, and it is the only one that does. Every other line reports a fault, and terse is the report saying there is none; this one reports a location, and where is my dev secrets file is a question rather than a complaint — asked most often by the developer whose project is working fine.

Outside a project, the Project: line states the one fact and every other project line is omitted. The exit stays 0 when the toolchain is clean: checking the CLI version, the shell or the alias from anywhere is legitimate, and somebody doing it is asking about their toolchain rather than their project.

$ cd /tmp && pithy doctor

pithy 1.3.0 (installed via brew)
Up to date.

Shell: zsh
Alias: installed

Project: no pithy.config.ts here — run `pithy init`, or change to a project directory

Cloudflare: reachable (token active)

OS:      macOS 14.5
Runtime: Bun 1.4.2 (Node 26.3.0 compat)

The Cloudflare: check still runs there, and it is the one check that never needed a project: the credentials are account-scoped, so are my credentials right has the same answer in every directory on the machine.

ESC