pithy feature

Stand up an isolated environment for one issue — worktree, ports, local backend, and its own ephemeral Cloudflare resources — and tear the lot back down.

Synopsis

pithy feature create <slug> --issue <n> [--skip-install] [--json]
pithy feature sync [--skip-data] [--json]
pithy feature destroy [--branch <name>] [--env <environment>] [--local-only] [--json]
pithy feature prune [--dry-run] [--json]

create runs from the main checkout. sync and destroy run from inside the worktree and take no name: the branch says which feature it is. destroy also takes --branch, for the one caller that cannot be inside the worktree — a merged pull request’s runner, which has neither the worktree nor the branch. prune runs from any checkout of the repository.

The feature’s live Cloudflare environment is pithy provision --feature. Provisioning is one job whichever environment it is for, so it is one command and one page. What lives here is the rest of a branch’s lifecycle.

destroy needs a Cloudflare account. It acts on real Worker scripts, D1, KV, R2 and queues. create, sync and prune are entirely local — a git worktree, a port reservation, and a Miniflare-backed dev backend. destroy --local-only is the deliberate way to tear down the local half without credentials. It resolves no account at all, so a shell exporting credentials for an account other than the one pithy.config.ts pins does not refuse it. Without --local-only, that mismatch refuses before anything is deleted.

Flags

Argument or flagApplies toDefaultPurpose
<slug>createrequiredShort kebab-case name for the feature, e.g. media-cli. Refused rather than truncated when it is too long for a name the feature composes
--issue <n>createrequiredThe issue number this feature tracks. Digits only, at most six
--skip-installcreatefalseSkip installing dependencies in the new worktree
--skip-datasyncfalseReconcile ports only, leaving the backend alone
--branch <name>destroythe checked-out branchThe feature branch to tear down, for a caller standing outside the worktree
--env <environment>destroyfeatureThe environment whose teardown is recorded on the audit trail. It never changes what is deleted
--local-onlydestroyfalseTear down only the worktree and its ports, leaving the Cloudflare resources in place
--dry-runprunefalseShow the plan and write nothing. Lists the blocks it would free, and writes nothing — not even the lock file
--jsonall fourfalseOne line of machine-readable output

What it does

The branch is cut from local main. Not from origin/main: a repository holding unpushed work would otherwise start every feature before that work, and where the older tree still loads there is no symptom at all — just a branch rooted in the past, found at merge. When local main is behind its remote the run says so and carries on, because cutting from a main a few commits behind is usually fine and sometimes deliberate; being told is what stops it becoming a surprise.

create

Validates the issue number and the slug at the boundary — before a branch or a worktree exists, so a refusal leaves nothing behind — including that the slug fits every name the feature will compose. Feature names are never truncated, so a slug too long for any of them is refused with the project’s maximum at that issue. Then it cuts the worktree and its feature/<issue>-<slug> branch, installs dependencies, reserves a port block, pins one port per Worker, and migrates and seeds the local dev backend.

Each step names itself as it starts — ▸ Running bun install..., then each database, migration and seeded store, in pithy migrate’s and pithy seed’s own words. A first create on a cold project is otherwise a minute of silence. --json prints none of it.

Before Done. it prints how to check a dependency change outside the checkout. The worktree sits under the main checkout, so Node resolves any package the worktree’s own node_modules lacks from <root>/node_modules. A dependency you removed still resolves, and the change passes in the worktree and fails on a clean install. The check copies the worktree to a temporary directory, which has no checkout above it, runs a frozen install there in the project’s package manager (bun install --frozen-lockfile, or npm ci), and then your typecheck, lint and tests. Run it on any change to a package.json or the lockfile. --json prints none of it.

Port allocation takes a lock over the machine’s <config>/dev-ports.json, claims the lowest free non-overlapping block across every checkout on the machine, and writes a per-worktree .dev.config.json that fixes each Worker’s port for the life of the feature. Assignment is sticky and never probed at startup, which is what lets several worktrees run at once. pithy dev has the whole model.

sync

Makes the worktree’s local environment ready, whatever state it is in, and covers the two everyday cases with one command: you added a Worker, or a colleague pushed the branch and you pulled it.

None of that state is in git — the .dev.config.json and the port reservation are both machine-local — so a sync creates them on your machine, with your own free block. It reconciles ports through the same code create uses, then runs every step of pithy setup but the install — the worktree was installed when it was created: the project check, the local secrets, the dev migration, each Worker’s .dev.vars, and a seed into an empty database. One implementation of ready, so a worktree and a clone cannot come to two answers about it. Each step is named as it goes, and every step is idempotent.

--skip-data reconciles ports only. It leaves the backend entirely alone: no secrets, no migrate, no seed, and no .dev.vars. Without the flag each Worker’s .dev.vars is generated exactly as pithy dev generates it, from sources already on your machine — never repaired or merged.

Provisioning the live half

pithy provision --feature, run from inside the worktree. It resolves the feature identity from the branch and the project name from the root pithy.config.ts.

Nothing is stored to make this work: every name is derived from the branch, and an already-provisioned resource is recovered by looking its name up in Cloudflare — which is what makes it idempotent and resumable. On a second push, CI computes the same names, finds the existing resources, rewrites the same wiring and deploys. There is no id file to merge, so there is nothing to conflict.

The config it writes is a build artifact, and it is not written where source lives. The ids go into apps/<worker>/.wrangler/pithy/wrangler.feature.jsonc, generated from the Worker’s tracked wrangler.jsonc on every run — so the tracked file is never dirty, git add -A cannot reach the ids, and a feature abandoned without destroy strands nothing.

The consequence worth stating: pithy env reports what a Worker’s tracked config declares, so a feature environment does not appear there.

It gives the feature its own secrets infrastructure, the way a declared environment gets one. A feature has its own SECRETS database, so it gets its own secrets manager too: its own master key and its own manager Worker, created through the provisioner pithy secrets provision uses and deployed with the feature’s other kit Workers. It holds no Cloudflare API token — its manager hosts no rotation Workflow and runs no cron, so branch code never holds write access to the account’s one Secrets Store, where production’s master key lives. That manager then creates every secret the registry says may be generated, auth-session-secret among them, exactly as a declared environment’s manager does: probed first, written with create, never over a value that is there. The feature’s stores are the only copy, nothing depends on which run created the key, and a run that fails partway is finished by the next one. destroy deletes the key and the manager with the rest — pithy secrets deprovision preserves a key unless asked, because losing it orphans every secret, and for an ephemeral environment that reasoning inverts. A secret somebody else issues, like an OAuth client secret, is one the report names as unbound under the feature’s own entry name.

It stands up every kit Worker the feature composes. A magic link runs in email’s send Workflow, an upload’s sweep in storage’s, a reconcile in payments’ — each in a host Worker the capability owns. So a feature gets its own of every one it composes, the way a declared environment does: <project>-f<issue>-<slug>--<capability>, with Workflows named the same way, bound to the feature’s own databases, buckets, indexes and keys, and its app Worker bound to each — but only once that host has deployed. A Worker that owns a binding a host binds gets its own feature host, <project>-f<issue>-<slug>--<worker>---<capability>, over the feature’s own copy of that binding, and its Workflow bindings reach that host (naming). A run mints declared secrets into the feature’s shared vault only, so every featureSecrets entry describes that vault; nothing is minted into the feature copy of a vault a Worker owns. They are deployed by provision --feature, redeployed by pithy deploy --env feature when they change, and deleted by destroy. The set is never listed: it is every host the kit’s registry knows that the branch composes, so a capability that gains a host joins a feature with nothing else changed.

It shares nothing with any other environment. The account and its one Secrets Store are the only things a feature cannot have its own of; everything inside them is split, a global secret’s entry included. Its rate limiters’ namespaces are the one exception — every feature shares them, and no staging or production config can.

It answers on its own workers.dev address and nothing else. Its stanza states routes: [], because wrangler would otherwise hand it the top level’s routes — a branch deploy taking the project’s custom domain — and the run names the routes it gave up.

destroy

Deletes the feature’s Worker scripts, then its Cloudflare resources — each first from the worktree’s manifest, then by recomputing every name the branch could have produced and deleting what still exists — then frees the port block, prunes the worktree and removes its directory, and deletes the branch if it has been merged. That second pass is what catches a partly-failed provision. A manifest entry is trusted for its name and nothing else. The id destroy deletes is the one the account answers for that name, never the id the entry states, so an entry that pairs the feature’s own name with production’s id reaches nothing.

The directory goes last, and only once git has forgotten the tree. The gitlink is dropped, the registration pruned, and then the directory removed — never git worktree remove, which recursed while git still held the registration. A live pithy dev session keeps its files: deleting a node_modules tree out from under a running watcher is the one shape that has crashed a box, and .dev-state.json names the supervising pid. Anything short of proof that pid is gone keeps the directory, and says so; pithy feature prune clears it later. An editor’s watcher cannot be detected from here and stays yours to know.

None of that runs on an interrupted teardown. A remote half that fails throws before the local half, deliberately: pruning the worktree would remove the checkout the re-run has to happen from, and the .pithy-feature.json saying what is left to delete lives in it. So the directory is removed only when there is nothing left to resume.

Scripts go first, and only once the account confirms they are there. Provisioning names each Worker’s script and records it, but it is the deploy that uploads it — so a Worker provisioned and never deployed has nothing to delete, and says nothing. Deleting the scripts before their resources means no reachable Worker is ever left bound to a database that is gone. Each delete is forced, because Cloudflare refuses to delete a Worker another Worker still binds and a feature’s Workers bind each other — apps/web calling apps/api puts the callee first, and an unforced teardown failed on it every run. Forcing also removes the Durable Objects a script hosts, which are the feature’s too. An account nothing vouches for is refused rather than asked: an empty script listing from it is not an absence, and a script found on it is somebody else’s.

Every kit host the feature could have stood up is one of those scripts, recomputed from the branch for every host the registry knows — whatever the branch composes now, since a host deployed before its capability left the branch is still the feature’s — and for each Worker that lists ownBindings, that Worker’s own host of each. An owned host or index name too long to compose is skipped rather than failing the teardown: no provision could have created it. Their Workflows go first, explicitly, found by the exact name of the script that hosts them: Cloudflare documents that deleting a Workflow leaves its script alone and says nothing of the reverse, so teardown does not rely on a script taking its Workflows with it. Then the feature’s own Vectorize indexes, a Worker’s own vector and support indexes among them, every repository in the feature’s own Artifacts namespace where anything binds artifacts — <project>-f<issue>-<slug>--artifacts, so no sibling’s and no environment’s — and every store entry it named, a global secret’s included. Its rate-limit namespaces are fixed per limiter and shared by every feature, so there is nothing of them to remove. There is no token to revoke.

The Artifacts namespace goes last. Cloudflare made it on the first repository, and nothing else deletes it. A repository delete finishes after Cloudflare answers it, so the namespace can still be busy after 30 seconds of retries. Then destroy fails with every other remote resource already gone, and stops there: the local half does not run, so the port block stays reserved, the worktree and its manifest stay, and the branch is not deleted. A second run takes the namespace and then does the rest. A namespace already gone, or never made, is nothing to do.

destroy does not count retained rows. A feature has its own copy of every d1 binding, SECRETS and EMAIL_SUPPRESSIONS included, and destroy deletes them with the rest, rows and all. pithy migrate --rollback, pithy secrets deprovision and pithy email deprovision --suppression refuse over the same tables unless --destroy-retained <n> matches the count. destroy takes no such flag: the database is the branch’s own, and the teardown runs headlessly when a branch merges, where nobody can type a count. Every name it deletes is recomputed from the feature’s identity, so it never reaches a declared environment’s database.

A feature provisioned before scripts were recorded is torn down by its own names, recomputed from the Workers under apps/ in the two shapes that carried the feature’s identity: <project>-f<issue>-<slug>-<app>, and the <project>-f<issue>-<slug>-<project>-<app> it used before the project segment stopped doubling. A feature deployed across that change runs under both, and both go. Names are matched exactly, never by prefix, so a sibling feature whose slug extends this one’s is left alone.

One name it deployed under is not among them. Before scripts were recorded, a feature with a Secrets Store had its generated config rewritten without the script name, and wrangler deployed it as <script>-feature — acme-api-feature. That name carries no issue and no slug, and every such branch of the project deployed over the same one, so no single feature’s teardown can claim it: deleting it would take down whichever open branch deployed last. destroy leaves it and does not report it. Once no feature branch from before that fix is still deployed, delete it by hand with wrangler delete --name <script>-feature.

It does not need a Worker config to load. Its local half is derived from the branch and the root config, and that is deliberate: the state it is most needed in is a create that failed partway, which leaves a worktree whose Worker config throws. A teardown that loaded it first was unavailable in exactly that state, and the port block leaked to a branch that no longer existed.

Missing credentials are a hard failure rather than a silent skip. Skipping the remote half would leak every Worker script, D1, KV, R2 and queue while reporting success — and the teardown then deletes the branch the resource names are derived from, so a later attempt could no longer work out what to delete. A CI job whose credentials did not propagate must fail loudly. --local-only is the deliberate opt-out.

--branch is how a merged pull request tears its own environment down. Every other subcommand here infers the feature from the checkout, which is right for a developer and impossible for a runner: on pull_request: closed the branch is already deleted and refs/pull/<n>/head checks out detached, so there is no branch to read. The pipeline holds the name anyway — github.event.pull_request.head.ref is a snapshot in the event payload and outlives the branch it names. The name goes through the same parser the inferred path uses, so the two cannot disagree about what a feature is called, and the project still comes from this checkout’s pithy.config.ts, which is what keeps the flag inside this project. With no --branch, the checkout’s branch decides, exactly as before. provision and create take no such flag; teardown is the only half with a caller standing outside the worktree.

Where --branch reads the feature’s record. A feature’s record is two things, and both live in its worktree rather than in the checkout the command runs from: .pithy-feature.json, which lists what provision --feature actually created, by id; and the branch’s own apps/<name>/pithy.config.ts, whose bindings every recomputed name comes from. destroy --branch reads both from <root>/.worktrees/<issue>-<slug> when that directory is on the machine. A successful teardown removes that directory, so after one the ordinary case is that it is gone; a directory is still there when a pithy dev session was running at teardown, or when one was made by hand, and it still counts. On a CI runner it is not there at all, and the two differ:

  • The manifest is gone, and the run says so. manifestRead is false, and stdout carries No feature manifest at <path>. followed by Deleted by recomputed name alone; anything only it recorded is still there. Everything named from the branch and the checkout’s config still goes; a resource provisioned for a binding the config no longer declares does not. That is a real narrowing, and it is stated rather than left to be inferred from a shorter list.
  • The config comes from the checkout, so check out the feature’s own ref. A workflow on pull_request: closed must check out refs/pull/<n>/head — the merge commit’s parent carries the feature’s pithy.config.ts, and that is what makes the reconcile the feature’s own. A runner left on the trunk reconciles against the trunk’s bindings, which is the same narrowing one level worse. The event payload gives you both: head.ref for --branch, head.sha for the checkout.

A runner has no worktree, no port block and no branch, and the report says so rather than claiming otherwise. All three are machine-local, so on a fresh container there is nothing local to tear down. That is a successful run, not a failure: the remote half is reported, and the local half reports portsFreed: false, worktreePruned: false, branchDeleted: false, with No port block and no worktree here. Nothing local to tear down. on stdout. That sentence reads all three fields, so it is never printed over a run that deleted a branch.

Both provisioning and destroy are audited. The trail lands in the project’s own top-level dev database rather than the feature’s, because the feature’s does not exist yet when provisioning starts and is deleted by teardown.

prune

Frees the port blocks of features whose worktree and branch are both gone. destroy frees a feature’s block, but it has to run from inside the worktree to know which — so a worktree removed any other way, by git worktree prune, a teardown script of your own, or a directory deleted by hand, leaves nothing to run it from. The branch outlives the worktree, the block outlives both, and the sweep that frees a deleted checkout’s blocks never reaches it, because the checkout it is filed under is still there. prune is how you get those ports back.

A block is freed only when its worktree’s directory is gone from disk and its branch no longer exists locally. Either one surviving keeps it, and so does anything prune cannot decide.

  • The branch exists. Checked out in some worktree or in none — a branch whose worktree you removed is a feature you may come back to, and it keeps its ports until you delete the branch.
  • A directory on disk holds it. A worktree still there with the branch checked out, a .dev.config.json there pinning it, or .worktrees/<issue>-<slug>, where create puts it. A directory counts whether or not git still registers it — git worktree list marks a deleted directory prunable, and that is not the test; the directory is. destroy removes the directory itself now, so prune’s remaining work is a worktree removed some other way, or one a live pithy dev session kept.
  • A local:<path> key, which pithy dev files a checkout in detached HEAD under, has no branch, so it is freed once <path> is gone.

Run it from the project directory, as you run pithy dev. pithy dev runs where the project is, so a repository whose project sits in a subdirectory pins <worktree>/app/.dev.config.json rather than one at the worktree’s root; prune reads each worktree’s pin at the worktree’s root and at the same place the directory you run it from has in its own checkout. A branch a same-named tag shadows is filed under heads/<branch>, the way git spells it, and is read that way too. The checkout prune runs from is never freed — it is on disk. Only this checkout’s blocks are judged: another project’s are its own business, and a repository speaks only for its own branches.

It frees under the registry lock, in one read-modify-write, and asks git inside the lock, so it cannot race a pithy dev or pithy feature create allocating at the same moment. --dry-run reads without the lock and writes nothing — not even the lock file — and the registry is byte-identical afterward.

The same rule rebuilds a lost registry. pithy dev without a .dev.config.json, create and sync put back the blocks the .dev.config.json files under .worktrees/ still pin, and they keep exactly the ones prune would keep. A block prune frees never comes back that way, and a block it keeps is never handed to somebody else. pithy doctor marks the same blocks with ← no worktree; pithy feature prune, decided by the same function, so the two cannot disagree.

It is not run for you. Every allocation already sweeps checkouts that are gone from disk, for the price of one stat each. This question costs several git spawns and a walk of every worktree, inside a lock held on a file every project on the machine shares, some of which are not repositories. A command you chose to run is the right price for that.

--json

One line, one object, one shape per subcommand. 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.

feature.create

$ pithy feature create media-cli --issue 69 --json
{"command":"feature.create","schemaVersion":1,"branch":"feature/69-media-cli","worktree":"/repo/.worktrees/69-media-cli","worktreeCreated":true,"dev":{"version":1,"branch":"feature/69-media-cli","ports":{"index":1,"base":8807,"size":20},"workers":{"api":{"port":8807,"origin":"http://localhost:8807"}}}}
KeyTypeMeaning
command"feature.create"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
branchstringThe feature branch created or attached
basestring or nullThe ref the branch was cut from — the trunk’s name, or "HEAD". null when nothing was cut: an already-registered worktree, or a branch that already existed and was attached to
worktreestringThe absolute worktree path
worktreeCreatedbooleanWhether a new worktree was created. False on an idempotent re-run over an existing one
behindRemotenumber or nullHow many commits local main is behind origin/main, or null when it is level, has no remote, or the repository has no local main. The branch is cut from local main either way — this reports it rather than refusing
devobjectThe feature’s dev config — the document written to the worktree’s .dev.config.json
dev.version1Dev-config schema version
dev.branchstringThe branch this config belongs to
dev.ports.indexnumberThe block’s index in the machine’s registry
dev.ports.basenumberThe first port in the block
dev.ports.sizenumberHow many ports the block spans — its Worker capacity
dev.workers.<name>.portnumberThe port that Worker binds locally, for the life of the feature
dev.workers.<name>.originstringThe origin sibling Workers reach it at

feature.sync

$ pithy feature sync --json
{"command":"feature.sync","schemaVersion":1,"branch":"feature/69-media-cli","block":{"block":1,"base":8807,"size":20},"dev":{…},"addedWorkers":["web"],"removedWorkers":[],"data":true}
KeyTypeMeaning
command"feature.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
branchstringThe feature branch
blockobjectThe feature’s reserved port block, as the central registry holds it
block.blocknumberThe block index, 0-based
block.basenumberThe first port in the block
block.sizenumberHow many ports the block spans
devobjectThe reconciled dev config, in the shape feature.create reports
addedWorkersstring[]Workers that gained a port on this run
removedWorkersstring[]Workers that went away and released their port
databooleanWhether the backend steps ran — everything pithy setup does but the install, together. false under --skip-data, and never anything else: one flag governs them all, so they cannot disagree

block and dev.ports describe the same reservation from two sides — block is the registry’s record, dev.ports is the worktree’s copy — and they spell the index differently because each keeps the name its own file uses.

feature.destroy

$ pithy feature destroy --json
{"command":"feature.destroy","schemaVersion":3,"deletedResources":[{"kind":"worker","name":"acme-f69-media-cli--api","id":"acme-f69-media-cli--api"},{"kind":"d1","name":"acme-f69-media-cli--db-d1","id":"…"}],"remote":true,"portsFreed":true,"branch":"feature/69-media-cli","worktreePruned":true,"branchDeleted":false,"manifestRead":true,"manifestPath":"/repo/.worktrees/69-media-cli/.pithy-feature.json"}
KeyTypeMeaning
command"feature.destroy"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
deletedResourcesobject[]Every Worker script and Cloudflare resource deleted, from the manifest and from the name reconcile, scripts first. Empty when nothing remained, or when the remote half was skipped
deletedResources[].kind"worker", "d1", "kv", "r2", "queue", "workflow", "vectorize", "artifacts" or "artifacts-namespace"The resource kind. worker is a Worker script, workflow a Workflow definition, artifacts one repository, named <namespace>/<repo>, and artifacts-namespace the feature’s Artifacts namespace, deleted after its repositories
deletedResources[].namestringThe resource name
deletedResources[].idstringThe id that was deleted. A Worker script’s is its name, which is all Cloudflare addresses one by
remotebooleanWhether the remote teardown ran. false under --local-only
portsFreedbooleanWhether the feature’s port block was returned to the registry — and whether there was one. false when the registry held no block for this branch, which is every CI runner, and on a re-run of a teardown that already freed it
branchstringThe feature branch this run was about, canonically spelled. --branch feature/012-x reports feature/12-x: a caller that logs what it asked for and a report that says what was torn down should not be two strings
manifestReadbooleanWhether the feature’s own .pithy-feature.json was read. false when its worktree is not on this machine, when the directory is there and the file is not, and whenever the remote half did not run — each of which narrows the teardown to recomputed names
manifestPathstringWhere that manifest is — read, or merely named when manifestRead is false
worktreePrunedbooleanWhether a registered worktree was pruned
branchDeletedbooleanWhether the feature branch was deleted. Only when it has been merged
interruptedbooleanPresent and true only on a teardown that failed partway. It says deletedResources is a record of what went before the failure rather than of the whole teardown, and that the three local flags are all false because the local half deliberately did not run — the worktree is where the re-run happens from, and the manifest naming what is left lives in it. The failure itself is the {"error":{…}} line on stderr, and the exit is non-zero by the failure’s class

A teardown deletes real infrastructure one resource at a time, with no transaction across them. So a failure on the fourth delete still fails the command, and stdout still names the three that went: an operator finishing the teardown by hand needs the record more on that run than on the one that worked.

feature.prune

$ pithy feature prune --json
{"command":"feature.prune","schemaVersion":2,"root":"/repo","dryRun":false,"freedBlocks":[{"branch":"feature/70-old-idea","block":2,"base":8827,"size":20}]}
KeyTypeMeaning
command"feature.prune"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
rootstringThe main checkout root whose blocks were judged — the registry key they are filed under
dryRunbooleanWhether this was --dry-run. Nothing was written when it is true
freedBlocksobject[]The blocks freed, in port order — or under --dry-run, the blocks that would be. Empty when every block is held
freedBlocks[].branchstringThe registry key the block was filed under: a branch, or local:<path> for a checkout in detached HEAD
freedBlocks[].blocknumberThe block index, 0-based
freedBlocks[].basenumberThe first port in the block
freedBlocks[].sizenumberHow many ports the block spans
planobjectPresent only under --dry-run: one edit of the machine’s port registry — its absolute path, since it lives outside every project — with a change per block it would free. Empty when every block is held

Errors

A bad issue number, or a bad slug. Checked before the branch or worktree exists, so nothing is left behind.

Issue must be a number of at most 6 digits (got "sixty-nine").
Pass --issue <number>.

A slug too long for this project. The maximum is the least room any name the feature composes leaves, at this issue. Nothing is truncated, so nothing is created.

Slug "project-scope-resources-and-limits" is 34 characters. Feature slugs in acme stop at 31 characters at issue 95.
Name the branch feature/95-<slug of 31 or fewer>. Feature names are never truncated.

Credentials missing on destroy. Refused rather than silently skipped, because the alternative leaks every resource while reporting success.

Cloudflare credentials are missing, so the feature's resources cannot be deleted.
Run pithy cloudflare connect, or set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, to tear down the remote environment, or pass --local-only to remove just the worktree and its ports.

The project has no name. It is the first segment of every feature resource name and the only key teardown has to find them by, so it is required with no guessed fallback: a wrong guess means destroy computes names that match nothing, deletes nothing, and exits 0.

The branch is not a feature branch. sync and destroy derive the issue and slug from the checked-out branch, so they must be run from inside the worktree.

Not on a feature branch (HEAD).
Run this from inside a feature worktree, or create one with pithy feature create.

A --branch that is not a feature branch. The same parser, and refused before the project config is even opened, so nothing is deleted. An issue longer than six digits is one of these: feature names reserve six, so a branch carrying more is not one this command owns.

Not a feature branch (not-a-feature).
Pass --branch feature/<issue>-<slug>, e.g. --branch feature/69-media-cli.

A manifest belonging to another feature. The per-entry name check is the real control; a mismatched header means the file was written for something else, and a teardown that ignored it would look like a success that removed nothing. The refusal names the feature the file belongs to, and never advises deleting it: that file is the only record of what that feature provisioned.

The feature manifest in /repo/.worktrees/69-media-cli belongs to acme-f70-other, not to acme-f69-media-cli.
Tear that feature down from its own worktree, or pass --branch feature/70-other to tear it down from here. The file is the only record of what it provisioned, so keep it until it has been.

prune outside a git repository. It judges blocks by the repository’s branches and worktrees, and without them every block would look unused, so it refuses rather than freeing them.

Could not resolve the repo's git directory.
Run this from inside a git repository.

prune in a bare repository’s worktree or a submodule. The registry files a checkout under the directory that holds its git directory. For a bare repository that is the directory the repository sits in, beside any other; for a submodule it is the superproject’s .git/modules, the same for every submodule it has. Another repository’s blocks may be filed under the same key, and their branches are not this repository’s, so every one would look deleted.

This checkout is in a bare repository or a submodule, whose registry key other repositories can share.
Free these blocks from each feature's worktree, where tearing the feature down releases them. `pithy feature destroy` deletes the feature's worktree, its branch and every resource it provisioned. That is a person's decision, not a fix. Prune cannot judge blocks other repositories may hold.

A .dev.config.json that will not parse. It sits in a directory on disk holding some block, and nobody can say which, so prune refuses rather than guess. Fix or delete the file.

An illegal --env on destroy. Validated at the flag, before any Cloudflare client is built.

Examples

Cut a feature environment from the main checkout.

$ pithy feature create media-cli --issue 69
Worktree /repo/.worktrees/69-media-cli.
Branch feature/69-media-cli.
api: http://localhost:8807
Local backend migrated and seeded.
A package this worktree's node_modules lacks resolves from /repo/node_modules, so a dependency change can pass here and fail on a clean install. Verify one outside the checkout:
  dir="$(mktemp -d)" && cp -R /repo/.worktrees/69-media-cli "$dir" && cd "$dir/69-media-cli"
  bun install --frozen-lockfile
  Then run your typecheck, lint and tests there.
Done.

Pick up a colleague’s branch on your own machine, from inside the worktree.

$ pithy feature sync
api: http://localhost:8807 (new).
Migrated dev: 5 applied.
Generated .dev.vars for apps/api.
Seeded dev.
Done.

Stand up the live environment in CI, and tear it down on merge.

pithy provision --feature --json
pithy feature destroy --json

Neither leaves anything to commit: a feature’s ids are written to a git-ignored file, and the provision line says so.

$ pithy feature destroy --local-only
Remote teardown skipped. Cloudflare resources were left in place.
Worktree pruned.
Directory removed.
Done.

Tear a feature down from inside its worktree, Workers first.

$ pithy feature destroy
Deleted acme-f69-media-cli--api.
Deleted acme-f69-media-cli--db-d1.
Worktree pruned.
Directory removed.
Done.

Free the blocks of features whose worktree and branch are both gone, from the project directory of any checkout. Look first.

$ pithy feature prune --dry-run
feature/70-old-idea  block 2  8827–8846  would be freed.
$ pithy feature prune
feature/70-old-idea  block 2  8827–8846  freed.
Done.
ESC