Start the local development environment: every Worker in apps/, plus each composed capability’s host Worker and any front end, under one supervising process.
Synopsis
pithy dev [--app <name>...] [--disable-autostart | --enable-autostart] [--tui | --no-tui] [--json]
pithy dev --list [--app <name>...] [--json]
pithy dev logs [--app <name>...] [-n <count>] [--since <when>] [--branch <name>] [--follow] [--timestamps] [--json]Flags
| Flag | Meaning |
|---|---|
--list | Print the set a run would start, and start nothing. Default false |
--app <name> | Start exactly the Workers named. Repeatable. Default: everything |
--disable-autostart | With --app, stop those Workers starting on this branch. Writes, and starts nothing |
--enable-autostart | With --app, let them start again. Writes, and starts nothing |
--tui / --no-tui | Render the live roster at a terminal, or don’t. Default true. Neither form overrides a pipe, --json, CI or TERM=dumb, which are always plain. PITHY_NO_TUI set to any non-blank value is the same as --no-tui, as a standing preference, and a typed --tui beats it for one run |
--json | Machine-readable output, one object per line. Default false |
Subcommands
| Command | Meaning |
|---|---|
pithy dev logs | Read a session back, by Worker and by time. See Reading a session back |
A bare pithy dev still starts a session. It takes no positionals, so nothing is shadowed, and a first word that is not logs is still an unknown command rather than a Worker name.
What it does
One command runs the whole backend, so you never hand-juggle terminals or ports.
It discovers your Workers from apps/
apps/ is the registry. pithy dev enumerates apps/* — there is no hand-maintained list — and reads each Worker’s co-located pithy.worker.jsonc, a file you own sitting beside wrangler.jsonc, which stays wrangler’s. Its dev block carries:
| Key | Meaning |
|---|---|
dev.readySignal | The regex marking “ready” in its output. Default /Ready on https?:\/\// |
dev.preferredPort | Optional |
dev.command | Optional. Run a non-Worker process — a Vite front end with no wrangler.jsonc — instead of wrangler dev |
Discovery keys on pithy.worker.jsonc, so such a process can join the dev set. Add, remove or rename a Worker with pithy worker and the dev set follows automatically.
It runs each composed capability’s host Worker too
apps/ is the app Worker registry. A capability that owns Workflows ships a prebuilt host Worker that pithy <capability> provision deploys, and none of them lives in apps/. pithy dev starts those as well: it reads each app Worker’s pithy.config.ts, and for every composed capability that owns a host it resolves that capability’s committed wrangler.jsonc template into a local config under .wrangler/pithy/hosts/<capability>/ — git-ignored, regenerated every run — and starts it.
A host is an ordinary member of the dev set. Its own pinned port, its own label and color in the terminal, its own session log, its own entry in .dev-state.json, reaped with everything else. It is registered under the capability’s own name, so its siblings reach it at EMAIL_ORIGIN, MEDIA_ORIGIN and so on; an apps/ Worker already using that name is refused rather than silently shadowed.
A Worker that owns a binding a host binds runs a host of its own. apps/two owning DB and composing email gets two---email beside the shared email, generated under .wrangler/pithy/hosts/two---email/ with its own pinned port. It is built from two’s own composition, opens the local database two’s top-level stanza names, and builds its links against two’s origin. two is handed that host as its EMAIL_ORIGIN, and its own hosts reach each other; every other Worker, and every shared host, reaches the shared ones and never another Worker’s own (naming).
Locally a host binds its databases by binding name — the same names pithy migrate --env dev filled — so a first pithy dev boots rather than erroring on a missing table. This is why mail sent from localhost now goes somewhere: the app Worker’s EMAIL_SENDER Workflow named a Worker pithy dev did not run, so every enqueued message sat pending while the UI reported success.
It sends real mail from your machine, and says when it cannot
The email host’s send_email binding runs with remote: true in dev by default, so a magic link you trigger from localhost is delivered through Cloudflare Email Service for real — the same pipeline, the same DKIM, the same delivery logs as production.
That needs a Cloudflare login and a sending domain already onboarded. pithy dev checks what it cheaply can before spawning anything: with no credentials, or a from address on a domain nobody can onboard, it resolves the host for its local simulator instead, says so with the command that fixes it, and starts the session anyway. The simulator logs the sender, recipient and subject, and writes the rendered HTML and text bodies to disk.
The verdict is said once, in the ready banner, where you actually look. Each email host is decided from its own composition: a Worker that owns its database runs its own host, sending from that Worker’s address in the mode that Worker chose, and the banner names each verdict when they differ.
The preflight is not the guarantee. A failure that only appears when the binding starts, or at the first send, is caught in the host’s own output, rendered as a problem line and an action line, and never kills the session: the host is re-resolved for its simulator on the spot, so the sends that follow are logged and written to disk rather than lost. email({ devDelivery: "simulator" }) selects the simulator deliberately, and every deployed environment always sends for real.
It runs a front end as part of the set
A Worker scaffolded by pithy ui add does not get a second process. Its dev.command replaces wrangler dev with Vite, and Vite serves the SPA and the Worker on that Worker’s one pinned port.
An Expo app is its own entry. pithy ui add react-native writes the app into an apps/<name>/ with a pithy.worker.jsonc and no wrangler.jsonc, so it joins the set as a process rather than a Worker: its dev.command runs expo start --port {port} on a port of its own, and it is ready at Expo’s Waiting on line. The expo start gets the same *_ORIGIN values a Worker does, and the app calls the one for the Worker its ui.worker names: Metro passes the web build’s calls to the Worker’s paths on to it, and a dev build on a phone calls it too. So in a feature worktree the app reaches that worktree’s Worker, not the main checkout’s port committed in its origins.dev.
The command is argv, and the token {port} in any argument is substituted at spawn time — ["bun", "x", "vite", "dev", "--strictPort", "--port", "{port}"] runs with the real port. {port} is the only token substituted.
It supervises, labels, and says when something never arrived
Every autostart Worker is spawned, its output labeled and colorized, and everything teed to the terminal and to that Worker’s own session log. One ready banner prints when every started Worker has matched its dev.readySignal. At a real terminal, the live roster holds the same facts under the output and keeps them current.
A Worker that starts and never becomes ready is a live child. wrangler dev does not exit when a build fails — it prints the error and keeps running — and the same shape covers a startup that hangs, a port that never binds, and a dev.command process that comes up wrong. The banner waits on the whole set, so it never fires, and the session used to proceed looking healthy with the real error forty lines up the scrollback.
So: 90 seconds after the last Worker is spawned, pithy dev says Still waiting on: support. — every Worker still missing, by name — and repeats it every 30 seconds while it stays true. The clock starts at the spawn rather than at the command, because everything before it is tens of seconds on a cold project and none of it is a Worker being slow.
It is still waiting, not failed: the first wrangler dev of a session pays for a cold bundle, and a slow Worker is not a broken one. A Worker that arrives late drops out of the next line on its own.
The deadline outlives the banner. A Worker restarted with r has started and is not ready, so it is named on the same schedule; a session that had been ready once used to fall silent instead. One restarted while the session is still coming up inherits the clock already running, so pressing r never restarts the clock for the siblings still waiting.
A Worker that never arrives is reported, never killed. One child exiting tears the whole session down, and stopping every healthy Worker over one Worker’s typo is a worse trade than a line naming it. The report names a restart, because a wrangler dev whose first build fails never rebuilds — fixing the file and waiting is the one thing that cannot work.
It resolves ports safely, and wires the Workers to each other
Each Worker’s start port is the one pinned in this worktree’s port block, verified rather than probed. A port is used only if free on both 127.0.0.1 and ::1 — Vite binds IPv6-only, wrangler binds both. If a pinned port is taken, the run reports a conflict and stops rather than drifting: a Worker that quietly moves breaks every sibling that was told its address ahead of time.
Resolved ports are exported as env, and the cross-Worker URLs are baked in as *_ORIGIN dev vars, so Workers call each other directly instead of relying on wrangler’s cross-process service registry.
A service binding takes the same route. An app that binds another Worker with pithy worker bind gets one PITHY_SERVICE_ORIGINS dev var, mapping each of its bindings to its target’s pinned address, and env.<BINDING>.fetch() goes there — never an edge address. That holds with --app too, for a target running in another session. 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.
It generates every Worker’s .dev.vars
wrangler loads a .dev.vars from the directory it runs in and merges nothing, so each apps/<worker>/ needs its own — and each one is written here, from sources that never leave your machine: every cf-secrets-store secret your registry declares, read straight from <config>/<project>/secrets.jsonc, plus whatever in <config>/<project>/dev.json no registry declares, overridden by the repo’s root .dev.vars.local, overridden in turn by that Worker’s own.
The dev secrets file is the source, not a file something copies out of. Edit a value there and the next pithy dev hands the Worker the new one, with no pithy seed in between; delete one and it is gone from every generated file, with no stale copy anywhere to fall back to.
pithy init writes no .dev.vars at all and a clone has none. pithy setup writes them through this same generator, and pithy dev is the command that runs every time — unlike a postinstall, which runs before the values exist.
Each generated file opens with a marker, and a .dev.vars Pithy did not write is never overwritten and never merged: it is named, .dev.vars.local is offered as the place for local values, and that Worker starts without one rather than with somebody else’s file replaced underneath it. Writing is idempotent by content rather than mtime, so a second run writes no bytes and wrangler’s watcher has nothing to react to.
Listing the set
pithy dev --list prints the set a run right now would start, and starts nothing.
- Every member, both halves. The
apps/Workers and each composed capability’s host Worker, each marked by kind.pithy worker listcannot answer this: it enumeratesapps/, which is the registry, and a host is resolved from the composition rather than from a directory. Two commands, two questions — the registry view and the run view. - Each carrying the port it would be pinned to. Read from
.dev.config.json, and for a Worker added since the last run, computed the way the next run computes it rather than guessed. A checkout whose ports nothing has pinned yet — nopithy setup,pithy devorpithy feature create— shows—for every port: assigning one is a run’s job, and a listing that invented an address nothing had reserved would be a lie. - It honors
--app.pithy dev --list --app boardstill lists everything and marks what that selection would start, so it answers what would that actually give me before you commit to it. - It writes nothing. No
.dev.config.json, no.dev.vars, no host config under.wrangler/pithy/hosts/, no session log, no.dev-state.json. Opening a session log truncates it merely by being opened, so--listopens none. Nothing is spawned, and no port is bound to test it. - What it cannot know. Which hosts actually come up is settled only once their configs are written, which is a run’s work — so a host whose template will not resolve is listed here and dropped by the run, which says so at the time.
Starting part of it: --app
pithy dev --app <name> starts exactly the Workers it names, whatever this branch has turned off. Naming a Worker is the more specific act, and that is the flag’s whole purpose.
- Repeatable.
pithy dev --app api --app web. The raw argv is read, because citty keeps only the last occurrence of a repeated string flag. - Three name forms. The deployed name, the
apps/<dir>basename, or a capability name for a host — sopithy dev --app emailruns the email host on its own. The deployed name is tried first: a Worker inapps/email/deployed asacme-emailcan sit beside theemailcapability host, and thereemailmeans the host whileacme-emailmeans the Worker. The deployed name leads because it is the key.dev.config.json,.dev-state.jsonand<CAPABILITY>_ORIGINare all written under. - Literal. No composed host comes along for the ride.
--app boardgives youboard, withEMAIL_ORIGINpointing at something that is not running, and that is the answer you asked for: a developer narrowing the dev set knows what they are narrowing. - Validated before anything spawns. One unknown name refuses the whole run and names the valid set. So does a
--appwith nothing after it — an empty selection means start everything, so a forgotten name would spawn the estate. Nothing half-starts and then dies. - It never changes what a Worker’s port is. Ports are pinned per Worker for the life of the feature and are computed over every discovered member, not over what happens to be running — so a run of one hands that Worker exactly the port a run of all of them would, and the run after it finds every address where it left it.
Keeping a Worker out of your dev set
pithy dev --app payments --disable-autostart # stop it starting on this branch
pithy dev --app payments --enable-autostart # let it start againBoth write, and start nothing.
Whether a Worker starts locally is not a fact about the project. pithy.worker.jsonc is committed and the same for everyone: it says a Worker exists and how it is run. Which Workers you are exercising this week is yours. So the answer lives beside your port block in dev-ports.json, keyed on the same three things the block is — this checkout, this branch, this machine — and nothing about it is committed or shared. dev.autostart was removed from the manifest for exactly this reason.
- Every Worker autostarts. No entry, no
autostartmap, or no name in the map all mean the same thing: it starts. There is no state where the file’s silence has to be interpreted. --appis above it.pithy dev --app paymentsstill starts a Worker you have turned off, for that one run, without turning it back on.- Per branch, inherited once.
pithy feature createcopies the branch it cut from, so a Worker you parked onmainstays parked in the new feature rather than quietly coming back. It is a copy, so from then on the two disagree freely.pithy feature syncnever reimposesmain’s answer on a feature that has since changed its own, andpithy feature destroytakes the feature’s answer with the branch. --enable-autostartremoves the key rather than storingtrue, so the file never grows a row per Worker per branch for every Worker somebody turned off and on again.- Names resolve exactly as a run resolves them. An unknown name is refused before anything is written. A capability host can be turned off too: that is an explicit act by somebody who knows its Workflows will not run.
- Ports are untouched. Turning a Worker off changes nothing about what any Worker is pinned to.
pithy dev --list marks such a Worker skipped off here, and pithy worker list reports it separately from the manifest, so you are never sent to a committed file to undo something that is not written there.
Move the checkout and the answer is left behind — and pithy dev says so. The key is the checkout’s absolute path, so renaming or moving it orphans everything written under the old one: every Worker starts again, which is also what you never said anything looks like. So a session names a root that is gone, on stderr, and --json adds an autostart-stale line. pithy dev --list says the same thing. Because dev-ports.json is machine-wide, the root may be another project’s deleted clone rather than this project’s old path, and the wording leaves that open. Re-set the answer with --disable-autostart here; pithy doctor lists every root in the registry.
A leftover dev.autostart in a manifest. true is accepted and ignored — pithy worker add wrote it into every manifest it ever scaffolded, and it agrees with the answer. false is refused, naming the command above, because it is the one value somebody chose and silently dropping it would start a Worker its owner had turned off.
The live roster
At a real terminal, pithy dev pins a roster under the session’s output and keeps it current. Every Worker, its kind, its port, its state, and how long it took.
──────────────────────────────────────────────────────────────────
worker kind port state time autostart
▸ api app 8787 ready 1.9s on
web app 8788 ready 2.4s on
email worker 8789 ⠋ building 14s on
support worker 8790 waiting 2m14s on
payments worker 8791 skipped off
──────────────────────────────────────────────────────────────────
↑↓ select r restart o open f logs (F all) a autostart off l login q quit- Worker output is hidden until you ask for it. The roster is the point — five Workers’ startup chatter is what used to bury it — so by default the stream carries the session’s own narration and nothing else. Press
ffor the selected Worker’s output, orFfor all of it. Everything goes to that Worker’s session log either way. - A Worker in trouble reveals itself. A Worker that exits, or that is still missing at the ready deadline, has its output shown without being asked — along with the last 200 lines it produced while hidden. Quiet when healthy, loud when not.
- The output above the roster is unchanged. Each line is written once and never redrawn, so your scrollback, selection and copy work exactly as they always did. Only the roster repaints, and it stops repainting once nothing is still building — except to redraw itself after a resize. The one exception is a drag across several sizes, below: the lines still on screen are written once more at the new width. Lines already in scrollback are never touched.
- A resize redraws the roster once the size settles. A window drag arrives as dozens of resize events, and a terminal that rewraps on resize — Windows Terminal does — moves the rows the roster is about to erase. So during a drag the roster is erased on every event and not redrawn for it, and once the size has held still for 150 ms it is drawn once, at the final width. A drag that crossed more than one size also rebuilds the screen under it: the visible screen is erased and the tail of your output that fits is restated at the new width, colors and links kept, with any stray erase or cursor move a Worker printed stripped out. A single resize skips the rebuild. The first rebuild erases the shell output on screen above
pithy dev— the command that started it, and whatever was there before — and that does not come back into scrollback. A line at the edge of the screen can show up as many as three times in scrollback. Accepted limits records why. - The ready banner shrinks to what the roster cannot say. The address list,
Starting …,Ready.and theDev login:line are all facts the table and its key bar hold a line below, so none of them is printed. What remains is the delivery verdict and the log directory. - A parked Worker still gets a row, marked
skippedwithautostartreadingoff.ron that row starts it. - The kind column says
apporworker.appis one of yours, fromapps/;workeris a capability’s own host Worker. - A ready Worker reports how long it took, not how long it has been up. A Worker still coming up reports elapsed time.
exited (1)is a row, not a silence. One Worker exiting still tears the session down, but the roster names which one, and its last frame stays on screen afterwards.
The keys. ↑↓ moves the marker; the verbs act on the marked row. A key that does nothing on that row is dimmed rather than hidden, so the bar never moves under you.
| Key | Does | Dimmed on |
|---|---|---|
r | Restart that Worker, in place, on the same pinned port. This is the answer to the one failure nothing else fixes: a wrangler dev whose first build fails never rebuilds, so fixing the file and waiting cannot work | — |
o | Open its origin in your own browser | a capability Worker |
f / F | f shows that Worker’s output, replaying the last 200 lines it produced while hidden; press it again to stop. F shows every running Worker’s output, or goes back to quiet | — |
l | Sign in on that Worker. Gated on the Worker being a ready app Worker, never on a seed: pressing it re-reads the seed, opens the only identity, offers the picker, or names pithy seed. A Worker with no dev-login route is refused by name | a capability Worker |
a | Turn this branch’s autostart for the Worker off, or back on — whether the next pithy dev starts it. It writes the same key as --disable-autostart. It does not stop the Worker | — |
q | Stop the session. The same path as Ctrl-C | — |
? | The key list, when the terminal is too narrow to show it | — |
Ctrl-C still stops the session the same way: SIGTERM to every child’s process group, a grace window, then SIGKILL — or, on Windows, taskkill /T /F on each child’s tree. The roster is unmounted after that, never instead of it. Press Ctrl-C again and it stops waiting on a child that will not die.
Where you get the plain stream instead. The roster is for a person at a terminal; everything else reads the output.
| Condition | Why |
|---|---|
--json | A machine reads one object per line |
| stdout is not a terminal | A pipe or a redirect gets text, with no cursor movement in it |
CI is set | A build log is the thing plain output exists for |
TERM=dumb | The terminal has said it cannot do this |
--no-tui | Asked for, for one run |
PITHY_NO_TUI set to any non-blank value | The same, as a standing preference. A typed --tui overrides it |
A terminal whose stdin is redirected (pithy dev < /dev/null) still gets the roster, with no key bar — and the dev-login line prints the URL instead of offering l.
Choosing who to sign in as
With more than one seeded identity, l replaces the roster with a picker:
────────────────────────────────────────────────────────
Sign in as tide█ 2 of 29
▸ jonas.villumsen@tidewater.test
keziah.mbeki@tidewater.test
────────────────────────────────────────────────────────
↑↓ select ⏎ sign in esc clear- Type to filter. Any printable character narrows the list, matching anywhere in the email or the user id, case-insensitively. A query matching nobody says
no match of 29. ↑↓moves,⏎signs in,escclears the query and then closes.- Ten rows at a time, and the marked row is always visible.
- The roster’s own keys are inert while it is open, so
qcannot tear the session down in answer to a question about signing in. Ctrl-C still stops the session. - Emails only, never a claim.
Without a roster — piped, --json, CI — l keeps the behavior it always had: up to nine identities on the digit keys, and a prompt past that.
Signing in: press l
pithy seed mints a dev login for every user it seeds. pithy dev is where you use them.
The ready banner names the user, or how many there are. With one seeded identity: Dev login: ada@example.com — press l to open a signed-in browser. With several: Dev login: 4 identities — press l to choose who to be and open a signed-in browser. No claim and no session cookie is ever printed on a run where pithy dev can open the browser itself, to the terminal or to any session log. It used to be — a document.cookie = "…" line to paste into a browser console — and a working session token rendered as text is a working session token at rest in a scrollback, a log and a screenshot. The value now travels from the Worker to the browser over HTTP and lands nowhere else.
l asks who, then does what it always did. One identity opens straight away. With several, the roster offers the picker. Without a roster, two to nine are numbered and one keypress picks; ten or more get a filterable prompt.
An expired claim takes one name out of the list. Each entry carries its own expiry, so a stale one is absent and the rest stay usable. When every one has expired, l says so and names pithy seed.
The seed is read when you press l, not when the session started. So pithy seed in another terminal is picked up by the next keypress, and an identity that expires during a long session stops being offered.
l opens the browser you already use. It opens http://localhost:<port>/__pithy/dev-login with the platform’s own opener — xdg-open, open, start — so it works in whatever browser is default, from a second profile, and from an incognito window. That route sets the cookie and redirects to /. Reload nothing; you are signed in.
The route exists only in a dev composition, and never under CI. @pithy-sh/auth registers GET /__pithy/dev-login behind two independent gates, both at registration rather than inside the handler: the composition’s ENVIRONMENT must be dev, and CI must be unset or blank. A staging or prod Worker does not carry the route at all, and neither does a dev Worker started by a CI job. It mints an authenticated session with no credential presented, so neither gate is allowed to imply the other.
Which Worker. The candidates are the started Workers that compose auth — a cookie is scoped to the origin that set it, so no other origin can be signed in by opening it. With one candidate, l opens it. With several, the one carrying a front end wins; if that does not decide, pithy dev prints the choices rather than guessing.
No seeded session, or an expired one, gets a line naming pithy seed rather than a URL that 404s. A piped run and any run in CI never enter raw mode and never wait for input — the banner prints the URL instead. --json starts no key handling at all.
Bound today: l. Nothing else.
Session state and cleanup
- A git-ignored
.dev-state.jsonrecords the pid, the resolved ports and the child pids. - A re-run stops the previous session first, then reaps orphaned
workerdandwranglerprocesses still holding the default ports, so a crashed session cannot block startup. The sweep finds a port’s holder withlsof; on Windows it asksGet-NetTCPConnection, then reads the holder’s command line through CIM. - Children are spawned via
setsid, so one signal to the process group tears down the wholewrangler → workerdsubtree. Teardown is a gracefulSIGTERM, thenSIGKILLafter a short grace window. - Windows has no
setsid, so teardown walks the child tree instead, withtaskkill /T /Fand the pid passed as an argument, never through a shell./Fis on every signal there: a windowless console process refuses a politetaskkill /T, and Node’s own WindowsSIGTERMends the process outright anyway. So on Windows there is no graceful step, and the grace window is POSIX’s alone.
The session log
One JSONL file per Worker, outside every checkout, at <config>/<project>/logs/dev.<branch>.<worker>.jsonl, in the Pithy config directory.
It was logs/dev.log in the project directory: one plain-text file, every Worker interleaved, no timestamps, and nothing that read it back. pithy feature destroy deleted the worktree and took that log with it — precisely the session you then want to read back. So the log moved, split by Worker, and every record carries a timestamp.
The branch segment is the branch name with every path separator replaced by -, so feature/671-dev-logs-reader files under dev.feature-671-dev-logs-reader.<worker>.jsonl. A detached HEAD files under detached. The directory is 0700 and every file is owner-only.
| Record | Shape |
|---|---|
| Output | {"ts": …, "stream": "stdout" | "stderr", "text": …} — one line the child wrote, ANSI stripped |
| Spawned | {"ts": …, "event": "spawned", "port": …} |
| Ready | {"ts": …, "event": "ready"} |
| Exited | {"ts": …, "event": "exited", "code": …} — null for a signaled child or a spawn that failed |
A Worker restarted with r reads as exited followed by spawned, in the same file. A new session truncates each Worker’s file, so one file is one session, and there is no size cap and no rotation. pithy dev logs reports each file’s size so growth stays visible.
A session-wide fact is never written into a Worker’s file. The roster, Still waiting on:, the dev-login line and Stopping — … are about the session, not about one Worker. They still reach the terminal, and under --json stderr.
A stale logs/dev.log in your checkout is left alone. Nothing deletes it, and nothing pithy dev writes lands there any more. A project whose root pithy.config.ts states no name gets no session log, and one line saying why.
Reading a session back
pithy dev logs reads those files. It is pithy dev logs, not pithy logs: that name is reserved for tailing deployed Workers, which is a different source with a different shape.
pithy dev logs # what is readable
pithy dev logs --app email -n 200 # that Worker's session
pithy dev logs --app email --follow
pithy dev logs --since 5m --app api --json| Flag | Meaning |
|---|---|
--app <name> | Render this Worker’s session. Repeatable; several Workers merge by ts. Omitted, the command lists what is readable instead |
-n, --lines <count> | How many records to render, newest last. Default 200. It bounds the merge, not each file |
--since <duration|instant> | Only records at or after this point — 30s, 5m, 2h, 1d, or an instant such as 2026-07-27T09:00:00Z |
--follow | Keep reading as the session writes. Ctrl-C ends it |
--timestamps | Prefix each rendered line with the record’s ts |
--branch <name> | Read another branch’s files. Default: the checked-out branch |
--json | One compact object per line. Default false |
- With no flags it lists what is readable, across every branch — branch, Worker, record count, size and last write. The files outlive the worktrees, so a branch whose worktree is long gone still has a row.
--app <name>renders that Worker’s session as[name] text, colorized, exactly as it read live. A lifecycle record reads as a sentence:[api] spawned on port 8787.,[api] ready.,[api] exited (0).- A trailing partial line is tolerated, because a live session is mid-append. A malformed line in the middle is skipped, and the count is reported once on stderr.
--followtails; it never refuses. When a new session truncates the file, the tail says so and follows it from the start.- A Worker or branch with no file is an error naming both, with the listing as the remedy.
Ports, and running several checkouts at once
Port collisions are the one thing that stops two feature worktrees running simultaneously — and, since every project starts at the same base port, two projects as readily as two worktrees.
The fix is a registry every checkout reads before it assigns, held once per machine rather than once per checkout: dev-ports.json in the Pithy config directory. It is keyed by main-checkout root, then by branch, each value the contiguous block that branch owns.
{
"/home/jo/code/acme": {
"main": { "block": 0, "base": 8787, "size": 20 },
"feature/12-auth": { "block": 1, "base": 8807, "size": 20 }
},
"/home/jo/code/other-app": {
"main": { "block": 2, "base": 8827, "size": 20 }
}
}It used to sit at the repo root, which meant every project on a machine kept its own, every one of them started empty, and every one of them handed out block 0 — so two projects on their default branch pinned the same twenty ports.
Each worktree also gets a git-ignored .dev.config.json recording its reserved block and pinning one port per Worker. pithy dev reads it as its start ports, which is why every Worker’s address is known ahead of time and the Workers can auto-wire to each other.
Ports are assigned at creation, never probed at startup. Probing when a Worker boots is a time-of-check/time-of-use race: two pithy dev processes in two worktrees can both observe the same port free and both try to bind it. Pre-assigning removes the race by construction.
Adding a Worker is additive. Assignment is sticky: a Worker that already holds a port keeps it, and only genuinely new Workers are assigned. Discovery is alphabetical, so purely positional assignment would renumber every later Worker the moment somebody added one that sorts earlier — moving addresses out from under a running session.
Worktree development is the whole story, including pithy feature sync and how the registry heals after a wiped config directory.
--json
Every line on stdout is one object, and every one carries schemaVersion, the version of its shape. The session keeps running, so a script reads pithy dev --json line by line rather than waiting for it to end. Those lines stay compact and uncolored even at a terminal, because a consumer reading line by line cannot take an indented document. pithy dev --list --json writes one line and exits.
Everything said to a person moves to stderr under --json — the Starting … line, the delivery verdict, a .dev.vars refusal, and the Workers’ own output, which is the bulk of the stream. It used to share stdout with the JSON, so pithy dev --json | jq choked on the first thing wrangler said. Splitting by descriptor costs a person nothing: both halves still reach the terminal, and each Worker’s session log carries its own output in either mode.
The session line
Written as soon as every Worker is started. It is what tells a script where the Workers are.
{"command":"dev","schemaVersion":1,"workers":{"api":{"port":8787,"origin":"http://localhost:8787"},"web":{"port":8788,"origin":"http://localhost:8788"}},"identities":[{"userId":"example-ada","email":"ada@example.com","expiresAt":"2027-07-27T00:00:00.000Z"}]}| Key | Type | Meaning |
|---|---|---|
command | string | "dev" |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
workers | object | One entry per started Worker, keyed by its name |
workers.<name>.port | number | The port that Worker was assigned in .dev.config.json, verified free before it started |
workers.<name>.origin | string | The localhost address its siblings were told to call it on |
identities | array | One entry per seeded user this session can sign in as. Empty when nothing is seeded, and empty when every claim has expired |
identities[].userId | string | The seeded user’s id |
identities[].email | string | The seeded user’s address |
identities[].expiresAt | string | ISO-8601. When that identity’s claim stops being accepted |
identities names who, and never how. There is no claim key on the line and there is not going to be one: a claim mints a session for whoever presents it, and a machine-readable line is as public as a printed one. The line says which identities exist so a script can pick one; signing in is the browser’s half, through l or through /__pithy/dev-login.
The still-waiting line
Written 90 seconds after the last Worker is spawned, and every 30 seconds after that, while any Worker has started and not become ready. Not written while every Worker is ready — and written again, on the same schedule, once a restart leaves one of them not ready.
{"command":"dev","schemaVersion":1,"event":"still-waiting","waiting":["support"]}| Key | Type | Meaning |
|---|---|---|
event | string | "still-waiting". What distinguishes this line from the session line |
waiting | string[] | The Workers that have started and not matched their dev.readySignal yet, in start order. Read afresh at every report, so a Worker that arrives late is gone from the next one |
The session line cannot carry this: it is written the moment the children are spawned, and readiness is decided after it. A run whose support Worker cannot build emits exactly the same session line as a healthy one.
The autostart-stale line
Written once at the top of a session when the registry holds autostart answers under a checkout root that is gone from disk (Keeping a Worker out of your dev set). pithy dev --list --json carries the same list as staleAutostart, empty when nothing has moved. Not written at all when every root is on disk.
{"command":"dev","schemaVersion":1,"event":"autostart-stale","roots":[{"root":"/home/you/Projects/app","branches":[{"branch":"main","workers":["payments"]}]}]}| Key | Type | Meaning |
|---|---|---|
event | string | "autostart-stale" |
roots | object[] | Every checkout root that is gone and still holds answers, sorted by path |
roots[].root | string | The absolute checkout root the answers are filed under — a path no longer on disk |
roots[].branches | object[] | The branches under that root that said something |
roots[].branches[].branch | string | The branch key. It may be local:<path>, which is why nothing here can match it to a branch name |
roots[].branches[].workers | string[] | The Workers that branch named |
It is a report, never a guarantee it will be there next run: pithy feature create, a first pithy dev, and --disable-autostart itself each prune roots that are gone.
The reader’s lines
pithy dev logs --json writes one compact object per line, uncolored, whether or not --follow is passed, so a consumer’s parse never changes with a flag it did not pass.
With no --app, one line describing what is readable:
{"command":"dev","schemaVersion":1,"event":"logs","logs":[{"branch":"main","worker":"api","lines":412,"bytes":38104,"lastWrite":"2026-07-27T09:14:02.881Z"}]}| Key | Type | Meaning |
|---|---|---|
event | string | "logs" |
logs | object[] | One entry per readable file, across every branch, sorted by filename |
logs[].branch | string | The branch segment of the filename — what --branch takes |
logs[].worker | string | The Worker segment of the filename — what --app takes |
logs[].lines | number | How many records parsed out of the file |
logs[].bytes | number | The file’s size on disk |
logs[].lastWrite | string | ISO-8601. When the file was last written |
With --app, the records themselves, one per line, as they sit in the file with schemaVersion added first:
{"schemaVersion":1,"ts":"2026-07-27T09:12:00.004Z","event":"spawned","port":8787}
{"schemaVersion":1,"ts":"2026-07-27T09:12:03.411Z","stream":"stdout","text":"Ready on http://localhost:8787"}
{"schemaVersion":1,"ts":"2026-07-27T09:12:03.418Z","event":"ready"}
{"schemaVersion":1,"ts":"2026-07-27T09:14:02.881Z","event":"exited","code":0}| Key | Type | Meaning |
|---|---|---|
schemaVersion | integer | The same number as the listing line’s. Not in the file: it is added as the record is written out |
ts | string | ISO-8601. What --since bounds against, and what merges two Workers’ files |
stream | string | "stdout" or "stderr", on an output record only |
text | string | The line the child wrote, ANSI stripped, with no [name] prefix |
event | string | "spawned", "ready" or "exited", on a lifecycle record only |
port | number | On spawned: the port that Worker was pinned to |
code | number or null | On exited: the exit status, or null for a signaled child and for a spawn that failed |
There is no worker key: the filename carries it. A refusal is the one {"error": …} line on stderr, with nothing on stdout.
Errors
pithy dev supervises, so most of what can go wrong is reported and survived rather than thrown.
- A pinned port is taken. The run reports the conflict and stops. It never drifts to another port.
- An unknown
--appname. The whole run is refused before anything spawns, and the valid set is named. An empty--appis refused the same way, because an empty selection would otherwise mean start everything. - A
.dev.varsPithy did not write. Never overwritten and never merged. The file is named, and that Worker starts without one. - A Worker whose
.dev.varscould not be written. Named, and every other Worker still starts. - A session log that could not be opened. Named, and every other Worker still starts.
- A Worker exits. The rest come down with it.
SIGINTorSIGTERMtears the session down the same way. lwith no browser to open. One line naming the URL to open by hand. The session keeps running — no browser is not a reason to stop supervising Workers.pithy dev logs --app <name>for a Worker with no file. Refused, naming the Worker and the branch, withpithy dev logsoffered as the way to see what there is.pithy dev logs --sincewith a value that is neither shape. Refused, naming both: a duration (30s,5m,2h,1d) or an absolute instant.pithy dev logsin a project whosepithy.config.tsstates noname. Refused: the log directory is keyed on that name.
Examples
pithy dev
pithy dev --list
pithy dev --app api --app web
pithy dev --app payments --disable-autostart
pithy dev --json
# What sessions are readable — every branch, every Worker, with size and last write.
pithy dev logs
# Follow one Worker as it writes.
pithy dev logs --app email --follow
# The last five minutes of two Workers, merged by time, one object per line.
pithy dev logs --app api --app web --since 5m --json
# A branch whose worktree pithy feature destroy already removed.
pithy dev logs --branch feature/671-dev-logs-reader --app api