pithy worker

Manage the project’s Workers under apps/ — the registry every other command discovers.

Adding a second Worker is the walkthrough; two Workers sharing a binding name share one database unless one owns it; and pithy dev runs every Worker it finds.

Synopsis

pithy worker add <name> [--skip-install] [--json]
pithy worker list [--json]
pithy worker remove <name> [--json]
pithy worker rename --from <worker> --to <name> [--force] [--dry-run] [--json]
pithy worker sync [--worker <name>] [--env <environment>] [--dry-run] [--json]
pithy worker bind --from <worker> --to <worker> [--binding <NAME>] [--json]
pithy worker unbind --from <worker> (--to <worker> | --binding <NAME>) [--json]

apps/ is the registry. There is no hand-maintained list: pithy dev, pithy deploy, pithy migrate and the rest enumerate apps/* and read each Worker’s pithy.worker.jsonc. Add, remove or rename a Worker here and the set follows automatically. The dev set is larger than this registry — it is apps/* plus the host Worker of every capability those Workers compose — which is why pithy dev --list exists and this command does not answer that question.

Only rename and an interactive add reach Cloudflare, and only to ask a question. rename asks the account which scripts are live under the old name before anything moves. An interactive worker add reads the account’s zones to offer a domain picker; under --json it asks nothing and reads nothing. Neither ever writes there. list, remove, sync, bind and unbind touch no account at all — sync in particular writes config and runs no deploy, so it is safe on any branch, at any time, as often as you like.

Flags

Argument or flagApplies toDefaultPurpose
<name>add, removerequiredThe Worker. add takes a new kebab-case name; remove takes the name worker list shows or the apps/<dir> basename
--from <worker>bind, unbind, renamerequiredbind and unbind: the Worker that holds the binding, an apps/ Worker, never a kit Worker. rename: the Worker to rename. At a terminal a missing one is asked for, from the apps/ Workers; under --json it fails input/required, naming --from
--to <worker>bind, rename; unbind unless --bindingrequiredbind and unbind: the Worker called — an apps/ Worker, or a kit Worker named by its capability (email, secrets, …). rename: the new kebab-case name. On bind and rename a missing one is asked for at a terminal and fails input/required, naming --to, under --json. unbind never asks: passing neither --to nor --binding, or both, fails validation/invalid_input at once, at a terminal too
--binding <NAME>bind, unbindbind: --to in upper snake case (app-b → APP_B)The binding name in env, SCREAMING_SNAKE_CASE. On unbind it picks the entry instead of --to, and exactly one of the two is passed
<from> <to>rename—The positional form, still accepted. It prints one line, on stderr, naming the flag form
--skip-installaddfalseSkip the workspace install after scaffolding
--forcerenamefalseRename even though a script is deployed under the old name. It stays live, and the report names it
--dry-runrename, syncfalseShow the plan and write nothing. Every refusal still applies, rename’s live-script check included
--worker <name>syncresolvedWhich Worker to reconcile. A single-Worker project needs no flag; several prompt at a terminal and, where nobody may be asked (--json, --no-input or PITHY_NONINTERACTIVE=1), fail input/required, naming --worker
--env <environment>syncevery declared oneReconcile just this environment — its route, its D1, KV, R2 and queue bindings, its Workflow bindings, its cron, its service bindings, its D1 names, its declared vars
--jsonall sevenfalseOne line of machine-readable output

What it does

add

Scaffolds apps/<name>/ and wires it in: the Worker’s wrangler.jsonc (named <project>-<name>), its pithy.worker.jsonc, its tsconfig.json and its package.json.

It then generates every discovered Worker’s .dev.vars — not only the new one, because generation is idempotent by content and a run that changes nothing writes no bytes — takes a port when there is a feature block to take one from, and installs the workspace, named as it starts: ▸ Running bun install.... A cold install is minutes of nothing otherwise. --json prints none of it. At a terminal it also asks where the Worker answers, per environment, against the account’s real zones, and writes the answer as a domains block.

All-or-nothing: anything that fails after the directory is made rolls it back, so the same command works on the retry.

list

Reports the discovered Workers with their autostart state and pinned dev port. It is the registry view — which Workers exist under apps/, which you have kept out of your local dev set, which port each holds.

Every Worker autostarts. One you have turned off on this branch reads off here, because that decision is yours and is not in any committed file — see keeping a Worker out of your dev set.

It also names answers recorded for a checkout that is gone. Those answers are keyed on the checkout’s absolute path, so moving or renaming the checkout orphans them and every Worker starts again — and the listing says so rather than leaving you to wonder why a parked Worker came back:

$ pithy worker list
Autostart answers are recorded for a checkout at /home/you/Projects/app, which is gone: acme-web.
Nothing looks them up again. If that was this project before it moved, re-set them here with pithy dev, naming each Worker with --app beside --disable-autostart.
acme-api  api  autostart  port 8787
acme-web  web  autostart  port 8788

For the run view — what pithy dev would actually start, capability hosts included — use pithy dev --list. Two commands, two questions.

remove

Deletes apps/<name>/ and releases its port back to the feature’s block. The target is resolved from the discovered set and restricted to apps/*, so nothing outside it can be addressed. Your data is untouched: this deletes a directory, not a database. It refuses while another Worker binds the one going, and names every one: their service bindings would name a script nothing deploys. Unbind each first.

sync

Writes what the Worker’s pithy.config.ts and pithy.worker.jsonc declare into its wrangler.jsonc: its address, its Workflows and cron, its bindings, its owned bindings and its vars. Six halves, one job — the declaration is the truth, and this is what makes wrangler agree with it.

The first half is the address. A domains block names where the Worker answers per environment, and sync writes the custom_domain route and the vars.BASE_URL it implies. This is the only non-interactive way to get that route written. Before it, the route was written by the domain prompt during pithy init or pithy worker add and nowhere else — so a domains block added by hand, which is the documented way to add an environment, declared an address nothing served: doctor reported it healthy, deploy shipped it, and the Worker answered on nothing.

The second half writes the app capability’s declared Workflows and cron triggers, for every environment it declares — the app’s equivalent of what pithy <capability> provision writes for a library capability’s. Three rules: the app’s entries are replaced rather than merged; an entry carrying a script_name belongs to a library capability’s provisioner and is never touched, and neither is one you wrote for a library job your own Worker hosts, such as @pithy-sh/auth’s purge or @pithy-sh/payments’ usage pass; triggers.crons is set to exactly the declared schedules, plus any such job’s schedule already there. The WorkflowEntrypoint subclass stays yours to export from the Worker’s main.

The class is checked, not assumed. Every run, an already-in-sync one included, reads the module main names and prints Export a WorkflowEntrypoint subclass from src/index.ts for each: SweepWorkflow., naming only the declared classes it does not export — the same declaration pithy doctor compares each stanza against — since wrangler refuses the deploy until it does. When main exports every class, nothing is said about them. When main cannot be checked, the run says why instead, Could not check main exports each Workflow class: <reason>.: wrangler.jsonc names no main module, the file could not be read, or it re-exports with export * from, which cannot show that a class is absent.

The third half writes every D1, KV, R2 and queue binding the Worker composes, the app’s own requiredBindings and every library capability’s, after the Worker’s honored declines, into every stanza that lacks one. Each entry is the one pithy add and pithy provision write, through the same writer, and lands right after the stanza’s last binding (before its env, or at its end, when it has none), so the diff is the entry and nothing else: a D1 entry names the database pithy provision will create, and a queue gets its producer and, when it consumes, its queues.consumers entry. An entry a stanza already has is left as written. Names come from the name in the root pithy.config.ts. A Worker with an app capability or an ownBindings list is refused without one, before anything is written. A Worker with neither, one that composes only library capabilities, is still synced: its queue entries are skipped and reported, its D1 entries are written with no database_name, and the rest are written as usual. A declinedBindings block that cannot be read is refused before anything is written, as pithy upgrade refuses it, because a decline nobody can read leaves nothing out. pithy doctor names this command for any of them a stanza lacks.

The fourth half is the app’s service bindings: each declared one written into services in every stanza, at the script its target deploys as there, as bind writes it. An entry you wrote by hand is left as it is.

The fifth half is the Worker’s D1 entries against its ownBindings. A binding listed after its entries were written still names the shared database, and one taken out still names the Worker’s own, so each entry naming the other of the pair gets the database_name pithy provision composes for this Worker. The top-level stanza, which is local dev’s, also gets a database_id of its own for an owned binding, and loses it when the entry is taken out, so pithy dev, migrate and seed keep the two databases apart. Only names the kit composed are rewritten: a name you chose is yours, and pithy doctor reports it. An environment stanza that already holds a real database_id is left for pithy provision --env <env> --repoint, because renaming it here would point the name at one database and the id at another. A scope: "global" binding of any kind in ownBindings, such as support’s SUPPORT_BUCKET R2 bucket, is refused before anything is written, naming the capability that declares it global, in a Worker that composes no database as in one that does.

The sixth half is the vars the Worker declares with defineVars, in its pithy.config.ts or on a capability it composes (declaring your own vars). Each is written into the top-level vars and every env.<name>.vars that lacks it, at that environment’s value, else the default. It runs after every other half, so a stanza another half has just created gets them too. A value a stanza already holds that parses under the var’s schema is yours and stays. One that does not is reported and left as it is — prod: READY_AFTER_MINUTES is "soon", which its declaration refuses: … Kept. A var nobody declared is never written or deleted. The one value it rewrites is a copy of the top level’s in an environment the declaration gives its own value: every command that creates an env.<name> stanza seeds its vars from the top level, so a new env.prod starts at dev’s. pithy doctor names a stanza that drops a declared var, holds one at the top level’s value, or holds one its schema refuses, and names this command for the first two. A refused value is yours to fix by hand.

pithy doctor and pithy deploy --env <name> read the Workflow half back. A declared job that was never synced used to deploy clean and never run, with nothing anywhere saying so. Which is why an app capability declaring no Workflows is reconciled too rather than skipped: dropping the last job has to take its binding and its cron out, or the fault would name a command that could not fix it. Nothing is invented for a project that never had either — no empty workflows key, no triggers block.

sync --dry-run runs the real reconcile in a private copy of the project and plans the difference, the way pithy add plans (one shape for every plan): the plan’s one file is the Worker’s wrangler.jsonc, its diff is the bytes the real run writes, and its changes are the sentences the real run prints. A run that would write no file but skip a binding — a queue in a project whose root pithy.config.ts names no project — puts those sentences in the plan’s notes instead. The line naming a Workflow class main does not export, or saying main could not be checked, goes in notes too. It is how to check, before writing anything, that a sync keeps what provisioning wrote — a D1 database_id, an R2 bucket_name, a Secrets Store entry — since an entry a stanza already has is left as written and so appears in no diff. Every refusal the real run makes is made first. Nothing is written in the project, and the copy is gone before the command exits.

Idempotent, comment-preserving and all-or-nothing.

bind

Declares a service binding from one of your Workers to another Worker of the project, so a call stays inside Cloudflare instead of going out through the edge and back. It adds { type: "service", name: "APP_B", service: "app-b" } to the binding Worker’s app capability, in its requiredBindings, and leaves every other byte of pithy.config.ts as it was. Then it writes the services entry into each stanza of that Worker’s wrangler.jsonc, at the script the target deploys as there — read from the target’s own wrangler.jsonc where it says, composed the way pithy provision composes it where it does not. A kit Worker resolves to the host the binding Worker reaches: email is <project>-staging-email in staging, and <project>-staging-<worker>---email for a Worker that owns a binding the email host binds, such as DB (naming). A run that finds the binding already there changes nothing, says so, and exits 0.

A binding has a direction, so every Worker is named by a flag. The target is any apps/ Worker, by its directory name or its deploy name, or a kit Worker named by its capability — the name pithy dev registers it under. A kit Worker is bindable only when some Worker composes that capability, because only then is its host deployed.

Every refusal comes before anything is written. A --from that is a kit Worker. A Worker binding itself, which is the self binding’s job (administersItself). A target that is no Worker, naming what is bindable. A kit Worker nothing composes, with pithy add as the action. A --binding that is not a binding name, or that the Worker already uses for something else — a capability’s binding, one of the app’s own Workflow bindings, a services entry written by hand, or SELF. A second binding to a target already bound under another name. And a binding that would close a loop through the project’s bindings — A -> B -> A, or A -> B -> C -> A — prints the whole path and is refused. pithy doctor reports the same loop for a config edited by hand.

Every environment carries it. staging, prod and every declared stanza get it from bind and sync. A feature gets it from pithy provision --feature, at the feature’s own deployment of the target, kit Workers included, so a call stays inside the feature. Under pithy dev the call reaches the local target on its pinned port, never an edge address and never wrangler’s own registry. A Worker run through a custom dev.command, such as a Vite dev server, gets the same routing through devWorkerConfig() in its vite.config.ts. A target nobody is running refuses the connection, and the call fails at once as core/upstream_failed, naming the binding and the address. pithy deploy ships a binding’s target before the Worker that binds it, the kit’s Workers first when an app binds one.

unbind

Takes one out, chosen by --to or by --binding, never both: the entry in pithy.config.ts, and its services entry in every stanza. A binding that is not there changes nothing and exits 0.

rename

A Worker’s name is three strings that have to agree: the directory apps/<name>/, the deployed script name in wrangler.jsonc and package.json, and vars.WORKER — which is what tells two Workers’ audit events apart when they share a database. This moves all three at once, comment-preserving, holding the new name to the same kebab-case rule add holds a new one to and refusing a destination that already exists.

Two things it deliberately leaves alone: the app capability’s name in pithy.config.ts, which is a migration namespace stamped into every applied row, and a script name you chose yourself — only a name carrying the Worker segment is recomputed, so a Worker migrated in as my-service keeps its name and the command says so.

A rename after a deploy is not a rename. Resource names are computed rather than stored, so <project>-<env>-<binding> survives untouched — but the Worker script is named for the Worker, so a renamed Worker deploys as a new script and leaves the old one live, serving and billing. So the account is asked first, and a live script under the old name is refused by name. --force is how you say that is understood; the report then names exactly what was left behind.

Where the account cannot be reached — no credentials, an offline laptop, a token that will not list — the rename proceeds and says it did not check. It never reports an unchecked account as a clear one, which is what accountChecked exists for.

--dry-run decides everything the rename decides and moves nothing. The name is checked, the destination is checked, and the account is asked about a live script exactly as the real run asks it — a refusal there is the refusal the rename would give. Then, instead of moving anything, it plans the move and the edits, with their diffs.

$ pithy worker rename --from api --to board --dry-run
Would move apps/api to apps/board.
Would edit apps/board/wrangler.jsonc.
Would edit apps/board/package.json.
Would deploy as acme-board, not acme-api.
Dry run. Nothing written.

Every other Worker’s binding follows the rename. Each service: in another app’s pithy.config.ts that names it, by its directory or its deploy name, becomes the new directory name, and each services entry naming one of the old scripts takes the script its stanza deploys as now. The binding names stay, because that app’s code reads them. rebound names the Workers it rewrote.

What it does not touch is everything outside the Worker’s own directory: the root tsconfig.json references, a vitest config, a CI workflow. Those are yours, they are grep-able, and the command’s last line says to look. pithy doctor checks the three stamps agree on every run, so a hand-rename that misses one fails CI instead of a deploy.

Owning a binding: ownBindings

Every binding is shared by name: two Workers that both declare DB are backed by one database. A Worker that lists a binding in ownBindings in its pithy.worker.jsonc gets a resource of its own instead, for D1, KV, R2 and queues, and its code still reads env.DB:

// apps/billing/pithy.worker.jsonc
{
  // Bindings this Worker gets its own resource for. Everything else is shared by name.
  "ownBindings": ["DB", "SESSIONS"]
}

pithy add writes the owned name into each stanza for a binding already listed, sync reconciles one listed later, and pithy provision creates it. The naming rules state the rule and the name; pithy provision says what happens to a binding that moves between shared and owned.

--json

One line, one object, one shape per subcommand. The command field is the subcommand’s dotted name. 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.

Five subcommands name the Worker the same way, and bind and unbind, which name two, say from and to. worker is the apps/ directory — what you typed, what --worker accepts, and what every path in the same payload is relative to. deployedAs is the script name from wrangler.jsonc — what the Cloudflare dashboard shows, and what wrangler deploy writes.

They are two identities and not interchangeable. A Worker scaffolded as web in project acme is web and acme-web at once, and pithy worker rename can leave the two unrelated entirely. Read worker to act on a Worker, deployedAs to find it in an account.

worker.add

$ pithy worker add web --json
{"command":"worker.add","schemaVersion":1,"worker":"web","deployedAs":"acme-web","dir":"/repo/apps/web","port":null,"reconciled":false,"devVarsRefused":[],"domains":null}
KeyTypeMeaning
command"worker.add"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
workerstringThe apps/ directory the Worker was scaffolded at
deployedAsstringThe script name it will deploy under, <project>-<worker> as scaffolded
dirstringThe absolute directory the Worker was scaffolded at
portnumber or nullThe port pinned for this Worker, or null when none was — which is what a plain checkout looks like, since there is no feature block to take one from
reconciledbooleanWhether the feature’s .dev.config.json was rewritten. Only ever true inside a feature worktree
devVarsRefusedstring[]One sentence per Worker whose .dev.vars this run did not generate. This command regenerates every Worker it discovers, so a sibling that will not get its bindings is named here
domainsobject or nullThe domains declaration this run wrote. Always null under --json: the picker is interactive
domains.<env>.patternstringThe hostname
domains.<env>.zonestringThe Cloudflare zone the hostname sits under

worker.list

$ pithy worker list --json
{"command":"worker.list","schemaVersion":1,"workers":[{"worker":"api","deployedAs":"acme-api","dir":"/repo/apps/api","autostart":true,"autostartLocal":null,"hasWrangler":true,"port":8787}],"staleAutostart":[]}
KeyTypeMeaning
command"worker.list"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
workersobject[]The discovered Workers, in discovery order
workers[].workerstringThe Worker’s apps/ directory
workers[].deployedAsstringThe Worker’s wrangler.jsonc name, or the directory basename when the file declares none
workers[].dirstringThe Worker’s directory
workers[].autostartbooleanWhether pithy dev starts it. true unless you have turned it off on this branch
workers[].autostartLocalboolean or nullnull when nothing local was set, so autostart is the default. Otherwise what this branch said, on this machine
workers[].hasWranglerbooleanWhether the directory holds a wrangler.jsonc. false means a non-Worker process in the dev set, which pithy deploy skips
workers[].portnumber or nullThe port pinned in .dev.config.json, or null when none is assigned
staleAutostartobject[]Checkout roots that are gone from disk and still hold autostart answers. Empty on a machine where nothing has moved, and never absent
staleAutostart[].rootstringThe absolute checkout root the answers are filed under — a path no longer on disk
staleAutostart[].branchesobject[]The branches under that root that said something
staleAutostart[].branches[].branchstringThe branch key. It may be local:<path> — what a checkout off a branch is keyed on, which is why nothing can match it to a branch name here
staleAutostart[].branches[].workersstring[]The Workers that branch named, sorted

worker.remove

$ pithy worker remove web --json
{"command":"worker.remove","schemaVersion":1,"worker":"web","deployedAs":"acme-web","dir":"/repo/apps/web","reconciled":true}

The name argument is matched against either identity, so both pithy worker remove web and pithy worker remove acme-web find the same Worker. The payload always reports both.

KeyTypeMeaning
command"worker.remove"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
workerstringThe removed Worker’s apps/ directory
deployedAsstringThe script name it deployed under
dirstringThe directory that was deleted
reconciledbooleanWhether the feature’s .dev.config.json was rewritten, returning the freed port to the block

worker.rename

$ pithy worker rename --from api --to board --json
{"command":"worker.rename","schemaVersion":2,"dryRun":false,"worker":"board","deployedAs":"acme-board","from":"api","to":"board","dir":"/repo/apps/board","script":{"from":"acme-api","to":"acme-board"},"orphaned":[],"accountChecked":true,"reconciled":false,"rebound":["web"]}

worker and deployedAs describe the Worker after the move, so a caller reading the identity keys gets the same two facts here it gets from the other four subcommands. from, to and script are what a rename adds on top: the transition.

KeyTypeMeaning
command"worker.rename"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
workerstringThe Worker’s apps/ directory after the move. The same string as to
deployedAsstringThe script name it deploys under after the move
fromstringThe apps/ directory basename before the move
tostringThe new name — the directory, the script’s Worker segment, and the WORKER var
dirstringWhere the Worker now lives: apps/<to>
scriptobject or nullThe deployed script name before and after, or null when the declared name carried no Worker segment to move
script.fromstringThe script name as declared before the rename
script.tostringThe script name it deploys under now
orphanedstring[]Script names left live on the account under the old name. Non-empty only under --force. Read it with accountChecked — it is empty both when the account said nothing is there and when it said nothing at all
accountCheckedbooleanWhether the account answered. false means unchecked, not clear
reconciledbooleanWhether the feature’s .dev.config.json was rewritten. Only inside a feature worktree, and never under --dry-run
reboundstring[]The other apps/ Workers whose service bindings named the renamed one and now name the new name. Their binding names are unchanged
dryRunbooleanWhether this was --dry-run. Nothing was moved or written when it is true, and every other key is what the rename would report
planobjectPresent only under --dry-run: the move, the two edits with their diffs, and the dev config inside a worktree

worker.sync

$ pithy worker sync --worker api --json
{"command":"worker.sync","schemaVersion":1,"dryRun":false,"worker":"api","deployedAs":"acme-api","routes":[{"env":"prod","pattern":"api.example.com","baseUrl":"https://api.example.com","changed":true}],"bindings":[{"env":"dev","written":[{"binding":"DB","type":"d1"}],"skipped":[]}],"runs":[{"env":"dev","workflows":[{"binding":"KEY_ROTATION","name":"acme-dev-app-key-rotation","class_name":"KeyRotationWorkflow"}],"crons":["0 4 * * *"],"changed":true}],"serviceRuns":[{"env":"dev","services":[{"binding":"APP_B","service":"acme-app-b"}],"changed":true}],"ownedBindings":[],"vars":[{"env":"dev","written":[{"name":"READY_AFTER_MINUTES","value":15}],"invalid":[]}],"exports":{"state":"exported"}}
KeyTypeMeaning
command"worker.sync"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
dryRunbooleanWhether this was --dry-run. Nothing was written when it is true, and every other key is what the real run would report
workerstringThe apps/ directory
deployedAsstringThe deployed script name, from wrangler.jsonc
routesobject[]One entry per environment the domains block declares. Empty when the Worker declares none
routes[].envstringThe environment routed. Never dev — local answers on the pinned port
routes[].patternstringThe hostname the custom_domain route now points at
routes[].baseUrlstringWhat vars.BASE_URL now holds: https://<pattern>
routes[].changedbooleanWhether that stanza moved. false on a re-run, and nothing is written
bindingsobject[]One entry per environment, for the D1, KV, R2 and queue bindings the Worker composes. Empty when it composes none
bindings[].envstringThe environment written. dev names the top-level stanza
bindings[].writtenobject[]The entries that stanza lacked and now has, each { binding, type }. Empty on a re-run
bindings[].skippedobject[]The entries that stanza lacks and could not be given, each { binding, type, reason }
runsobject[]One entry per environment reconciled. Empty when the Worker declares no app capability at all; one entry each, binding nothing, when the app declares no Workflows
runs[].envstringThe environment reconciled. dev names the top-level stanza
runs[].workflowsobject[]The entries that environment’s workflows table now declares for the app, verbatim as written
runs[].workflows[].bindingstringThe binding name the Worker env exposes, e.g. KEY_ROTATION
runs[].workflows[].namestringThe deployed Workflow name, <project>-<env>-<capability>-<job>
runs[].workflows[].class_namestringThe exported WorkflowEntrypoint subclass that runs the job. Cloudflare resolves it in this script, so it must be exported from the Worker’s main
runs[].cronsstring[]The cron schedules that environment’s triggers now carries
runs[].changedbooleanWhether anything moved
serviceRunsobject[]One entry per environment reconciled, when the app declares a service binding. Empty when it declares none
serviceRuns[].envstringThe environment reconciled. dev names the top-level stanza
serviceRuns[].servicesobject[]The services entries the app’s declarations wrote there
serviceRuns[].services[].bindingstringThe binding name in the Worker’s env
serviceRuns[].services[].servicestringThe script it calls in that environment
serviceRuns[].changedbooleanWhether that stanza moved
KeyTypeMeaning
ownedBindingsobject[]One entry per field ownBindings changed in the Worker’s D1 entries. Empty when nothing moved, which a re-run always is
ownedBindings[].envstringThe environment written. dev names the top-level stanza
ownedBindings[].bindingstringThe D1 binding
ownedBindings[].field"database_name" or "database_id"The field written or removed. database_id only ever moves in the top-level stanza
ownedBindings[].fromstringWhat it said before. Absent when the field was not there
ownedBindings[].tostringWhat it says now. Absent when the field was removed
varsobject[]One entry per environment, for the vars the Worker and its capabilities declare with defineVars. Empty when it declares none
vars[].envstringThe environment written. dev names the top-level stanza
vars[].writtenobject[]The vars written into that stanza, each { name, value }: the environment’s own value, else the default. Each one it lacked, and each it held at the top level’s value where the declaration gives the environment its own. Empty on a re-run
vars[].invalidobject[]The vars that stanza holds a value for that the declaration refuses, each { name, value, problem }. The value is kept as it is
exportsobjectWhether the Worker’s main module exports each Workflow class the app declares for the environments reconciled. state is "exported" when it exports them all or none is declared, "missing" with main (the module, relative to the Worker) and missing (each class it does not export, in declaration order), or "unreadable" with reason
planobjectPresent only under --dry-run: the Worker’s wrangler.jsonc edit with its diff and one sentence per change, in the shape every --dry-run shares. files is empty when the run would change nothing

worker.bind and worker.unbind

$ pithy worker bind --from app-a --to app-b --json
{"command":"worker.bind","schemaVersion":1,"from":"app-a","to":"app-b","binding":"APP_B","kind":"app","changed":true}

bind and unbind write the same keys. Only command tells them apart.

KeyTypeMeaning
command"worker.bind" or "worker.unbind"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
fromstringThe apps/ Worker that holds the binding, by its directory
tostring or nullThe Worker it calls: an apps/ directory, or a kit Worker’s capability. null only for an unbind --binding that found nothing
bindingstringThe binding name in from’s env
kind"app", "kit" or nullapp for an apps/ Worker, kit for a kit Worker. null exactly when to is
changedbooleanWhether this run wrote anything. false on a run that found it already so

That worker/deployedAs split holds across every command that reports a Worker — pithy add, pithy ui and pithy upgrade included. It did not always: four subcommands reported a single name, and it was the directory in one and the deployed script name in the other three, with nothing in the payload saying which. The two coincide whenever a project and its Worker are named alike, which is what kept it hidden.

Errors

No such Worker. remove and rename, when nothing under apps/ answers to the name. A usage error, exit 2: a different name is the fix.

No worker named "wbe" under apps/.
Run pithy worker list to see the workers this project has.

A name that is not kebab-case.

Worker name must be kebab-case (got "Admin_API").
Use lowercase words joined by hyphens, e.g. api or admin-api.

The destination already exists.

apps/board already exists.
Pick another name, or remove that directory first.

A live script under the old name. The refusal names every script the account reported.

api is deployed as acme-api, acme-api-prod.
A renamed worker deploys as a NEW script and leaves that one live and serving. Delete it first, or pass --force to rename anyway and orphan it.

An unreadable wrangler.jsonc. Raised before anything moves — this command edits that file.

Nothing to sync. sync writes what domains, an app capability, ownBindings, vars and the D1, KV, R2 and queue bindings it composes declare, and a Worker with none of them, and no D1 entry left naming its own database, has nothing to write. A Worker that composes only a library capability’s resources, or declares only vars, is synced, not refused.

api declares neither domains nor an app capability, and no vars.
Declare `domains`, `vars` or `app` in the worker's pithy.config.ts. This writes what they imply into wrangler.jsonc — the route and BASE_URL, each var, the Workflow bindings and cron.

A vars declaration that cannot be read. Refused before anything is written: a vars not built with defineVars, and a var two sources declare, naming both.

The var READY_AFTER_MINUTES is declared twice: by pithy.config.ts and by stats-feed.
Declare each var once. Rename one, or take it out of the Worker's own vars.

A domains block that is not valid. Refused with the field named, rather than written into a routes entry Cloudflare rejects at deploy.

An illegal --env. Checked first, before any config is loaded.

The project has no name. sync requires the root config’s name for a Worker with an app capability or an ownBindings list, and never guesses it: a Workflow name is account-scoped and stable forever once deployed, so a guessed project would name a Workflow another project owns. It is core/precondition_failed, exit 3, and nothing is written. A Worker that composes only library capabilities is synced without one, as the third half says.

A binding that would close a loop. The whole path, from the target.

$ pithy worker bind --from app-b --to app-a
app-b -> app-a would close a loop: app-a -> app-b -> app-a.
Remove one binding in that path first.

A kit Worker nothing composes.

$ pithy worker bind --from app-a --to email
No Worker in this project composes email, so there is no email Worker to bind.
Run `pithy add email --worker app-a` first.

A Worker binding itself.

$ pithy worker bind --from app-a --to app-a
A Worker does not bind itself here.
Declare `administersItself: true` in the root pithy.config.ts instead. Provision then binds SELF in every environment (#616).

A target that is no Worker.

$ pithy worker bind --from app-a --to app-z
No Worker named app-z.
Bindable: app-b, app-c, email, secrets.

A binding name the Worker already uses.

$ pithy worker bind --from app-a --to app-b --binding DB
app-a already binds DB, to a D1 database.
Pass a different --binding.

A second binding to one target.

$ pithy worker bind --from app-a --to app-b --binding OTHER
app-a already binds app-b as APP_B.
A Worker binds another once. Use APP_B, or run pithy worker unbind first.

A --from that is a kit Worker, and unbind with both --to and --binding, or neither — each a call to fix, exit 2.

Removing a Worker another one binds.

$ pithy worker remove app-b
app-a and app-c bind app-b.
Run pithy worker unbind for each first.

Examples

Scaffold a second Worker.

$ pithy worker add web
Worker web scaffolded at /repo/apps/web.
Ports are assigned when you run pithy feature create or pithy feature sync.
Done.

See what the project has.

$ pithy worker list
acme-api  api  autostart  port 8787
acme-web  web  autostart  port 8788

Rename, when nothing is deployed under the old name.

$ pithy worker rename --from api --to board
Renamed api to board.
Deploys as acme-board, not acme-api.
Check anything outside the worker that names it: tsconfig, CI, imports.
Done.

Rename anyway, knowing what is orphaned.

$ pithy worker rename --from api --to board --force
Renamed api to board.
Deploys as acme-board, not acme-api.
Still deployed under the old name: acme-api. Delete or keep.
Check anything outside the worker that names it: tsconfig, CI, imports.
Done.

Reconcile one environment: its bindings, its Workflows and its cron.

$ pithy worker sync --worker api --env prod
prod: DB, PUBLISHED written.
Done.

Write the route for a domains block added by hand, then run it again.

$ pithy worker sync --worker api
prod: routed to api.example.com. BASE_URL https://api.example.com.
Done.

$ pithy worker sync --worker api
acme-api is already in sync.
Done.

See what a sync would write before it writes it.

$ pithy worker sync --worker api --env prod --dry-run
Would edit apps/api/wrangler.jsonc.
  prod: DB, PUBLISHED written.
Dry run. Nothing written.

Bind one Worker to another, then run it again.

$ pithy worker bind --from app-a --to app-b
Bound app-a to app-b as APP_B.
Done.

$ pithy worker bind --from app-a --to app-b
app-a already binds app-b as APP_B.
Done.

Bind a kit Worker, and take a binding out by name.

$ pithy worker bind --from app-a --to email
Bound app-a to email as EMAIL.
Done.

$ pithy worker unbind --from app-a --binding EMAIL
Unbound EMAIL from app-a.
Done.
ESC