Local dev event stream

wd dev is a long-running interactive process. For human users it prints a persistent summary table and tails colourful logs. For agents that doesn’t work — they need a structured stream.

wd dev --json (or --ndjson) switches to one JSON object per line on stdout.

Event schema

Live schema:

wd schema outputs --command devEvent --json

Each event has at minimum:

{ "ts": "2026-05-14T20:30:00.123Z", "type": "worker.ready" }

Additional fields depend on type.

Event types

| type | When it fires | Notable extra fields | | --- | --- | --- | | dev.starting | First event after parsing the dev plan, before any worker spawns. | mode ("workers" or "session"), workers, companions | | worker.ready | One per worker, once its dev server is reachable. | workerPath, port, url | | dev.ready | All planned workers are up. | workerCount, ports (map), mode, logDir | | worker.log | Captured stdout/stderr line from a running worker. ANSI-stripped, trimmed. | workerPath, message | | worker.error | Same as worker.log but the line matched an error heuristic (case-insensitive error, ✗, or ✘). | workerPath, message | | dev.stopping | Sent on SIGINT/SIGTERM, before teardown. | — | | dev.stopped | Final event before exit. | — |

Note

Human-formatted log output (with worker labels and ANSI colors) is redirected to stderr when in event mode, so the NDJSON stream on stdout stays parseable. You can still see colourful logs by reading stderr separately. Subscribers should also handle unknown event types gracefully (forward-compatible).

Example transcript

$ wd dev --json
{"ts":"...","type":"dev.starting","mode":"workers","workers":[{"workerPath":"workers/api"},{"workerPath":"workers/auth"}],"companions":[]}
{"ts":"...","type":"worker.log","workerPath":"workers/api","message":"⛅️ wrangler 4.88.0"}
{"ts":"...","type":"worker.log","workerPath":"workers/api","message":"[wrangler:info] Ready on http://localhost:8787"}
{"ts":"...","type":"worker.ready","workerPath":"workers/api","port":8787,"url":"http://127.0.0.1:8787"}
{"ts":"...","type":"worker.ready","workerPath":"workers/auth","port":8788,"url":"http://127.0.0.1:8788"}
{"ts":"...","type":"dev.ready","workerCount":2,"ports":{"workers/api":8787,"workers/auth":8788},"mode":"workers","logDir":"/your/project/.wrangler-deploy/dev-logs"}
{"ts":"...","type":"worker.log","workerPath":"workers/api","message":"[wrangler:info] GET /health 200 OK (3ms)"}
{"ts":"...","type":"worker.error","workerPath":"workers/api","message":"TypeError: Cannot read properties of undefined (reading 'foo')"}
^C
{"ts":"...","type":"dev.stopping"}
{"ts":"...","type":"dev.stopped"}

Subscribing from a script

Bash:

wd dev --json | while IFS= read -r line; do
  type=$(echo "$line" | jq -r .type)
  case "$type" in
    worker.ready) echo "ready: $(echo "$line" | jq -r .url)";;
    dev.ready)    echo "all up";;
    dev.stopped)  echo "done"; break;;
  esac
done

Node:

import { spawn } from "node:child_process";
import { createInterface } from "node:readline";

const dev = spawn("wd", ["dev", "--json"], { stdio: ["ignore", "pipe", "inherit"] });
const rl = createInterface({ input: dev.stdout });

for await (const line of rl) {
  const event = JSON.parse(line);
  switch (event.type) {
    case "dev.starting":
      console.log("planning", event.workers.length, "workers");
      break;
    case "worker.ready":
      console.log("ready", event.workerPath, "→", event.url);
      break;
    case "dev.ready":
      // all workers up; safe to start probing
      break;
    case "dev.stopped":
      process.exit(0);
  }
}

Errors during start-up

If wd dev --json can’t even start (missing config, missing deps, port conflict that the port-finder couldn’t resolve), it falls back to the standard error envelope on stdout — not an event line. Always check exit code first:

$ wd dev --json
{
  "ok": false,
  "command": "wd dev",
  "error": {
    "type": "config",
    "code": "WD_E_CONFIG_MISSING",
    "message": "No wrangler-deploy.config.ts or wrangler-deploy.config.js found in the current directory.",
    "retryable": false,
    "fix": "Run `wd init` to scaffold a config, or `cd` to a project that has one."
  }
}

Stopping the dev server programmatically

Send SIGINT or SIGTERM to the wd dev process. The CLI emits dev.stopping, tears down workers and tunnels, then emits dev.stopped before exiting.