pithy dev

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

FlagMeaning
--listPrint the set a run would start, and start nothing. Default false
--app <name>Start exactly the Workers named. Repeatable. Default: everything
--disable-autostartWith --app, stop those Workers starting on this branch. Writes, and starts nothing
--enable-autostartWith --app, let them start again. Writes, and starts nothing
--tui / --no-tuiRender 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
--jsonMachine-readable output, one object per line. Default false

Subcommands

CommandMeaning
pithy dev logsRead 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:

KeyMeaning
dev.readySignalThe regex marking “ready” in its output. Default /Ready on https?:\/\//
dev.preferredPortOptional
dev.commandOptional. 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 list cannot answer this: it enumerates apps/, 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 — no pithy setup, pithy dev or pithy 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 board still 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 --list opens 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 — so pithy dev --app email runs the email host on its own. The deployed name is tried first: a Worker in apps/email/ deployed as acme-email can sit beside the email capability host, and there email means the host while acme-email means the Worker. The deployed name leads because it is the key .dev.config.json, .dev-state.json and <CAPABILITY>_ORIGIN are all written under.
  • Literal. No composed host comes along for the ride. --app board gives you board, with EMAIL_ORIGIN pointing 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 --app with 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 again

Both 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 autostart map, 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.
  • --app is above it. pithy dev --app payments still starts a Worker you have turned off, for that one run, without turning it back on.
  • Per branch, inherited once. pithy feature create copies the branch it cut from, so a Worker you parked on main stays parked in the new feature rather than quietly coming back. It is a copy, so from then on the two disagree freely. pithy feature sync never reimposes main’s answer on a feature that has since changed its own, and pithy feature destroy takes the feature’s answer with the branch.
  • --enable-autostart removes the key rather than storing true, 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 f for the selected Worker’s output, or F for 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 the Dev 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 skipped with autostart reading off. r on that row starts it.
  • The kind column says app or worker. app is one of yours, from apps/; worker is 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.

KeyDoesDimmed on
rRestart 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—
oOpen its origin in your own browsera capability Worker
f / Ff 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—
lSign 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 namea capability Worker
aTurn 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—
qStop 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.

ConditionWhy
--jsonA machine reads one object per line
stdout is not a terminalA pipe or a redirect gets text, with no cursor movement in it
CI is setA build log is the thing plain output exists for
TERM=dumbThe terminal has said it cannot do this
--no-tuiAsked for, for one run
PITHY_NO_TUI set to any non-blank valueThe 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, esc clears 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 q cannot 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.json records the pid, the resolved ports and the child pids.
  • A re-run stops the previous session first, then reaps orphaned workerd and wrangler processes still holding the default ports, so a crashed session cannot block startup. The sweep finds a port’s holder with lsof; on Windows it asks Get-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 whole wrangler → workerd subtree. Teardown is a graceful SIGTERM, then SIGKILL after a short grace window.
  • Windows has no setsid, so teardown walks the child tree instead, with taskkill /T /F and the pid passed as an argument, never through a shell. /F is on every signal there: a windowless console process refuses a polite taskkill /T, and Node’s own Windows SIGTERM ends 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.

RecordShape
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
FlagMeaning
--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
--followKeep reading as the session writes. Ctrl-C ends it
--timestampsPrefix each rendered line with the record’s ts
--branch <name>Read another branch’s files. Default: the checked-out branch
--jsonOne 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.
  • --follow tails; 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"}]}
KeyTypeMeaning
commandstring"dev"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
workersobjectOne entry per started Worker, keyed by its name
workers.<name>.portnumberThe port that Worker was assigned in .dev.config.json, verified free before it started
workers.<name>.originstringThe localhost address its siblings were told to call it on
identitiesarrayOne entry per seeded user this session can sign in as. Empty when nothing is seeded, and empty when every claim has expired
identities[].userIdstringThe seeded user’s id
identities[].emailstringThe seeded user’s address
identities[].expiresAtstringISO-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"]}
KeyTypeMeaning
eventstring"still-waiting". What distinguishes this line from the session line
waitingstring[]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"]}]}]}
KeyTypeMeaning
eventstring"autostart-stale"
rootsobject[]Every checkout root that is gone and still holds answers, sorted by path
roots[].rootstringThe absolute checkout root the answers are filed under — a path no longer on disk
roots[].branchesobject[]The branches under that root that said something
roots[].branches[].branchstringThe branch key. It may be local:<path>, which is why nothing here can match it to a branch name
roots[].branches[].workersstring[]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"}]}
KeyTypeMeaning
eventstring"logs"
logsobject[]One entry per readable file, across every branch, sorted by filename
logs[].branchstringThe branch segment of the filename — what --branch takes
logs[].workerstringThe Worker segment of the filename — what --app takes
logs[].linesnumberHow many records parsed out of the file
logs[].bytesnumberThe file’s size on disk
logs[].lastWritestringISO-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}
KeyTypeMeaning
schemaVersionintegerThe same number as the listing line’s. Not in the file: it is added as the record is written out
tsstringISO-8601. What --since bounds against, and what merges two Workers’ files
streamstring"stdout" or "stderr", on an output record only
textstringThe line the child wrote, ANSI stripped, with no [name] prefix
eventstring"spawned", "ready" or "exited", on a lifecycle record only
portnumberOn spawned: the port that Worker was pinned to
codenumber or nullOn 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 --app name. The whole run is refused before anything spawns, and the valid set is named. An empty --app is refused the same way, because an empty selection would otherwise mean start everything.
  • A .dev.vars Pithy did not write. Never overwritten and never merged. The file is named, and that Worker starts without one.
  • A Worker whose .dev.vars could 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. SIGINT or SIGTERM tears the session down the same way.
  • l with 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, with pithy dev logs offered as the way to see what there is.
  • pithy dev logs --since with a value that is neither shape. Refused, naming both: a duration (30s, 5m, 2h, 1d) or an absolute instant.
  • pithy dev logs in a project whose pithy.config.ts states no name. 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
ESC