@cliftonc/cfld 0.1.1 → 0.2.1

package/README.md

@@ -4,17 +4,44 @@
 
 `cfld` wraps [`cloudflared`](https://github.com/cloudflare/cloudflared) into a frictionless dev experience: the **same** custom URL every run (not a random `trycloudflare.com` one), authorized with a **browser login** (zero API tokens), reusing the same named tunnel and DNS record across restarts instead of churning them. It runs a **live dashboard** (URL, connection count, request/latency counters, tailing logs), **auto-reconnects** on edge blips, and **guards** against stealing a DNS record that belongs to another tunnel.
 
+## Getting started
+
+**New here? Just run this — it walks you through everything, no account or config needed to start:**
+
 ```bash
-# one-off, no install
-npx @cliftonc/cfld            # detect your dev port, reuse-or-create a tunnel, go live
+npx @cliftonc/cfld setup
+```
+
+`setup` is the front door. It checks `cloudflared` for you, then lets you pick:
+
+1. **A public URL right now** — free, no account, no domain (a temporary `trycloudflare.com` URL). Great for a webhook, a demo, or just trying it.
+2. **A persistent custom URL** — opens the browser to sign in (or **sign up** — it's free), then wires up the same URL for every future run.
+
+You don't even have to remember `setup`: the **first time you run bare `cfld`** in a fresh project, it drops you into this same guided flow so you're never stuck guessing.
+
+Already know what you want? Skip straight to it:
+
+```bash
+# instant public URL in seconds — no account, no config
+npx @cliftonc/cfld --quick 3000   # temporary trycloudflare.com URL
+
+# the everyday command — reuse-or-create your persistent tunnel and go live
+npx @cliftonc/cfld            # detect your dev port, go live on the same URL
 npx @cliftonc/cfld 3000       # explicit port
-npx @cliftonc/cfld --quick    # ephemeral trycloudflare.com URL — no domain needed
 
 # or install once and use the short `cfld` command everywhere
 npm i -g @cliftonc/cfld
-cfld
+cfld setup
 ```
 
+### What it costs
+
+`cfld` is built to get you going at zero → near-zero cost, and it's honest about the one thing it can't automate:
+
+- **Instant URL** — `cfld --quick`: **free**, no account, no domain. The URL is temporary and changes each run.
+- **Cloudflare account** — **free**. `cfld` opens the browser to sign in (the same page has a **Sign up** link); there's no API token to create. Account signup itself can't be scripted — Cloudflare requires a browser, terms acceptance, and email verification.
+- **Persistent custom URL** — needs a **domain on Cloudflare**. Free if you already own one (just add the site); otherwise a domain is a few dollars/year via [Cloudflare Registrar](https://dash.cloudflare.com/?to=/:account/domains/register). No account has a free permanent subdomain.
+
 ## Why not just `cloudflared`?
 
 The persistent-tunnel flow normally means: create an API token in the dashboard, find your zone/account IDs, `tunnel create`, hand-write a `config.yml`, `route dns`, and remember not to delete anything. `cfld` collapses all of that into one idempotent command and adds the dev niceties (auto port detection, deterministic hostname, `.env` write-back, a live status view).
@@ -46,10 +73,11 @@ A machine-wide registry at `~/.cfld/registry.json` indexes every tunnel, so you
 
 | Command | What it does |
 |---|---|
+| `cfld --quick [port]` | Instant `trycloudflare.com` URL — no account, no cert/domain (temporary). |
+| `cfld setup` | Guided first-run — pick the instant free URL or set up a persistent one. |
 | `cfld [port]` | Ensure + run a persistent tunnel (reuses the same URL). |
-| `cfld --quick [port]` | Ephemeral `trycloudflare.com` URL — no cert/domain. |
 | `cfld login [--reauth]` | Authorize with Cloudflare in your browser. `--reauth` adds another domain. |
-| `cfld init` | Interactive setup wizard — configure a project without running it. |
+| `cfld init` | Configure a persistent tunnel without running it. |
 | `cfld list` | List all tunnels across projects/domains. |
 | `cfld status [name]` | Show details for a tunnel. |
 | `cfld up <name>` | Run a registered tunnel by name from anywhere. |
@@ -113,6 +141,60 @@ cfld service uninstall    # stop + remove (tunnel + DNS preserved)
 
 Windows service management is not supported — run `cfld` in the foreground there.
 
+## Running alongside your dev server
+
+Give `cfld` your dev command after a `--` and it runs both as one managed unit:
+
+```bash
+cfld 3000 -- next dev
+```
+
+`cfld` will:
+
+- **boot your dev server** as a managed child, with `PUBLIC_URL` already in its environment (so it can read its own public URL for webhooks/OAuth callbacks — no `.env` round-trip needed);
+- **wait for `:3000` to actually listen** before flipping to `● LIVE`, so the URL never serves a 502 the moment you reveal it;
+- **stream your dev server's logs** into the same dashboard as the tunnel — one unified view;
+- **stop both on a single Ctrl-C**, gracefully, leaving the tunnel + DNS intact so the next run reuses the same URL;
+- **exit if your dev server exits**, propagating its exit code (the tunnel is still preserved).
+
+The pass-through form (`-- <cmd>`) runs your command directly. If you need shell features (pipes, `&&`, globs), use the string form instead:
+
+```bash
+cfld 5173 --exec "npm run dev"
+```
+
+This works with `--quick` too, when you don't have a domain set up yet:
+
+```bash
+cfld --quick 3000 -- next dev
+```
+
+Wire it into `package.json` so the whole team gets the same public URL:
+
+```jsonc
+{
+  "scripts": {
+    "dev": "next dev",
+    "dev:tunnel": "cfld 3000 -- next dev"
+  }
+}
+```
+
+> **Tip:** commit a `"cfld": { "zone": "example.com", "name": "myapp" }` block to `package.json` so the URL is deterministic for the whole team — everyone's `dev:tunnel` maps to `myapp.example.com`.
+
+<details>
+<summary>Prefer to keep the two processes separate?</summary>
+
+`cfld` also works fine standalone — it only needs the port, and tolerates the app not being up yet (502 until it starts, then recovers). Run them with [`concurrently`](https://www.npmjs.com/package/concurrently):
+
+```jsonc
+"dev:tunnel": "concurrently -k -n app,cfld -c blue,magenta \"npm:dev\" \"cfld 3000\""
+```
+
+or plain shell: `cfld 3000 & next dev`.
+
+</details>
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -2,6 +2,9 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
+import { readFileSync as readFileSync7, realpathSync } from "fs";
+import { dirname, join as join7 } from "path";
+import { fileURLToPath } from "url";
 import pc7 from "picocolors";
 
 // src/commands/run.ts
@@ -476,6 +479,20 @@ async function detectDevPorts() {
   );
   return checks.filter((p) => p !== null);
 }
+async function waitForPort(port, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const intervalMs = opts.intervalMs ?? 300;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) return false;
+    if (await isPortListening(port)) return true;
+    await sleep(intervalMs);
+  }
+  return false;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
 function findFreePort() {
   return new Promise((resolve, reject) => {
     const server = createServer();
@@ -662,6 +679,144 @@ function wireLines(child, stream, onLine) {
   });
 }
 
+// src/process/child.ts
+import { spawn as spawn3, execSync } from "child_process";
+function describeCommand(cmd) {
+  return cmd.shell ? cmd.command : cmd.argv.join(" ");
+}
+function startChild(options) {
+  const [command, args, useShell] = options.command.shell ? [options.command.command, [], true] : [options.command.argv[0], options.command.argv.slice(1), false];
+  let stopped = false;
+  const child = spawn3(command, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env },
+    // New process group so a terminal Ctrl-C doesn't race us to the child; we
+    // stop the whole group ourselves.
+    detached: true,
+    shell: useShell,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let markExited;
+  const exited = new Promise((resolve) => {
+    markExited = resolve;
+  });
+  wireLines2(child, "stdout", options.onLine);
+  wireLines2(child, "stderr", options.onLine);
+  child.on("error", (err) => {
+    markExited();
+    if (stopped) return;
+    stopped = true;
+    options.onExit?.(null, null);
+    options.onLine?.(String(err.message ?? err), "stderr");
+  });
+  child.on("exit", (code, signal) => {
+    markExited();
+    if (stopped) return;
+    stopped = true;
+    options.onExit?.(code, signal);
+  });
+  return {
+    exited,
+    get pid() {
+      return child.pid;
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      killGroup(child, "SIGINT");
+      const t = setTimeout(() => {
+        if (child.exitCode === null && !child.signalCode) killGroup(child, "SIGKILL");
+      }, 4e3);
+      t.unref();
+    },
+    kill() {
+      killGroup(child, "SIGKILL");
+    }
+  };
+}
+function descendantPids(pid) {
+  let out = "";
+  try {
+    out = execSync("ps -A -o pid=,ppid=", { encoding: "utf8" });
+  } catch {
+    return [];
+  }
+  const childrenOf = /* @__PURE__ */ new Map();
+  for (const line of out.split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)$/);
+    if (!m) continue;
+    const child = Number(m[1]);
+    const parent = Number(m[2]);
+    const list = childrenOf.get(parent);
+    if (list) list.push(child);
+    else childrenOf.set(parent, [child]);
+  }
+  const found = [];
+  const stack = [pid];
+  while (stack.length) {
+    for (const child of childrenOf.get(stack.pop()) ?? []) {
+      if (!found.includes(child)) {
+        found.push(child);
+        stack.push(child);
+      }
+    }
+  }
+  return found;
+}
+function signalPids(pids, signal) {
+  for (const pid of pids) {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+function reapChild(child, graceMs = 3e3) {
+  const tree = child.pid ? descendantPids(child.pid) : [];
+  child.stop();
+  signalPids(tree, "SIGINT");
+  return new Promise((resolve) => {
+    const done2 = () => {
+      clearTimeout(grace);
+      child.kill();
+      signalPids(tree, "SIGKILL");
+      resolve();
+    };
+    const grace = setTimeout(done2, graceMs);
+    grace.unref();
+    child.exited.then(done2);
+  });
+}
+function killGroup(child, signal) {
+  const pid = child.pid;
+  if (pid === void 0) return;
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+    }
+  }
+}
+function wireLines2(child, stream, onLine) {
+  const source = stream === "stdout" ? child.stdout : child.stderr;
+  if (!source || !onLine) return;
+  let buffer = "";
+  source.setEncoding("utf8");
+  source.on("data", (chunk) => {
+    buffer += chunk;
+    let idx;
+    while ((idx = buffer.indexOf("\n")) !== -1) {
+      onLine(buffer.slice(0, idx).replace(/\r$/, ""), stream);
+      buffer = buffer.slice(idx + 1);
+    }
+  });
+  source.on("end", () => {
+    if (buffer.length > 0) onLine(buffer.replace(/\r$/, ""), stream);
+  });
+}
+
 // src/process/ready.ts
 async function getReady(metricsPort) {
   try {
@@ -681,7 +836,7 @@ async function waitForReady(metricsPort, opts = {}) {
     if (opts.signal?.aborted) throw new Error("aborted");
     const state = await getReady(metricsPort);
     if (state?.ready) return state;
-    await sleep(intervalMs);
+    await sleep2(intervalMs);
   }
   throw new Error("Timed out waiting for the tunnel to connect to Cloudflare.");
 }
@@ -715,7 +870,7 @@ function sumMetric(text, name) {
   }
   return total;
 }
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
@@ -755,7 +910,7 @@ function colorLevel(level) {
 }
 
 // src/commands/login.ts
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn4 } from "child_process";
 import { existsSync as existsSync8 } from "fs";
 
 // src/ui/prompts.ts
@@ -883,7 +1038,7 @@ async function runLogin() {
   step("Opening your browser to authorize with Cloudflare (no API token needed)\u2026");
   note("  Pick the domain you want to use. Waiting for you to finish\u2026");
   await new Promise((resolve, reject) => {
-    const child = spawn3(bin, ["tunnel", "login"], { stdio: "inherit" });
+    const child = spawn4(bin, ["tunnel", "login"], { stdio: "inherit" });
     child.on("error", reject);
     child.on("exit", (code) => {
       if (code === 0 || existsSync8(defaultCertPath())) resolve();
@@ -966,6 +1121,12 @@ async function runCommand(flags) {
   const cwd = process.cwd();
   const interactive = isInteractive();
   const config = readProjectConfig(cwd);
+  if (flags.exec && flags.port === void 0 && config?.port === void 0 && !config?.routes?.length) {
+    throw new CfldError(
+      "Specify the port your dev command will listen on.",
+      "e.g. `cfld 3000 -- next dev`"
+    );
+  }
   const slug = deriveSlug(cwd, flags.name ?? config?.name);
   const tunnelName = tunnelNameForSlug(slug);
   const knownZones = Array.from(
@@ -1005,7 +1166,13 @@ async function runCommand(flags) {
     envKey
   });
   if (ensureGitignored(cwd, ".cfld.json")) info("Added .cfld.json to .gitignore.");
-  await launch(result, { cwd, envKey, noEnv: flags.noEnv, port: primary.port });
+  await launch(result, {
+    cwd,
+    envKey,
+    noEnv: flags.noEnv,
+    port: primary.port,
+    exec: flags.exec
+  });
 }
 async function launch(result, ctx) {
   const metricsPort = await findFreePort();
@@ -1014,7 +1181,7 @@ async function launch(result, ctx) {
   const interactive = isInteractive();
   let dashboard;
   if (interactive) {
-    const { startDashboard } = await import("./dashboard-QUPY25QT.js");
+    const { startDashboard } = await import("./dashboard-Q6WI32AK.js");
     dashboard = startDashboard({
       url,
       target,
@@ -1022,7 +1189,10 @@ async function launch(result, ctx) {
       status: "connecting",
       connections: 0,
       requests: 0,
-      logs: []
+      split: Boolean(ctx.exec),
+      devLabel: ctx.exec ? describeCommand(ctx.exec) : void 0,
+      tunnelLogs: [],
+      devLogs: []
     });
   } else {
     step("Connecting to Cloudflare edge\u2026");
@@ -1030,11 +1200,32 @@ async function launch(result, ctx) {
   const emitLine = (line) => {
     const formatted = formatLogLine(line);
     if (!formatted) return;
-    if (dashboard) dashboard.log(formatted);
+    if (dashboard) dashboard.log(formatted, "tunnel");
     else process.stderr.write(formatted + "\n");
   };
-  let stopping = false;
-  const runner = await startRunner({
+  const emitDevLine = (line) => {
+    if (line.trim() === "") return;
+    if (dashboard) dashboard.log(line, "dev");
+    else process.stderr.write(line + "\n");
+  };
+  let runner;
+  let child;
+  let poll;
+  let shuttingDown = false;
+  const childAbort = new AbortController();
+  const shutdown = (opts = {}) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (poll) clearInterval(poll);
+    runner?.stop();
+    dashboard?.stop();
+    if (opts.reason) note(`
+${opts.reason}`);
+    const exit = () => setTimeout(() => process.exit(opts.code ?? 0), 100).unref();
+    if (child) reapChild(child).then(exit);
+    else exit();
+  };
+  runner = await startRunner({
     configPath: result.configPath,
     tunnelName: result.tunnelName,
     certPath: result.certPath,
@@ -1045,32 +1236,53 @@ async function launch(result, ctx) {
       else if (status === "connecting" && !dashboard) note("Reconnecting\u2026");
     },
     onFatal: (message) => {
-      dashboard?.stop();
       warn(message);
-      process.exit(1);
+      shutdown({ code: 1 });
     }
   });
-  const stop = (reason) => {
-    if (stopping) return;
-    stopping = true;
-    runner.stop();
-    dashboard?.stop();
-    note(`
-${reason}`);
-    setTimeout(() => process.exit(0), 100).unref();
-  };
+  if (ctx.exec) {
+    if (!dashboard) step(`Starting \`${describeCommand(ctx.exec)}\`\u2026`);
+    child = startChild({
+      command: ctx.exec,
+      cwd: ctx.cwd,
+      env: ctx.noEnv ? void 0 : { [ctx.envKey]: url },
+      onLine: (line) => emitDevLine(line),
+      onExit: (code, signal) => {
+        childAbort.abort();
+        const how = code !== null ? `exited (code ${code})` : `was terminated${signal ? ` (${signal})` : ""}`;
+        shutdown({
+          reason: `Your dev command ${how} \u2014 stopping. Your tunnel URL is preserved.`,
+          code: code ?? 1
+        });
+      }
+    });
+  }
   if (!dashboard) {
-    process.once("SIGINT", () => stop("Stopping \u2014 your URL is preserved. Re-run `cfld`."));
-    process.once("SIGTERM", () => stop("Stopping \u2014 your URL is preserved."));
+    process.once(
+      "SIGINT",
+      () => shutdown({ reason: "Stopping \u2014 your URL is preserved. Re-run `cfld`." })
+    );
+    process.once(
+      "SIGTERM",
+      () => shutdown({ reason: "Stopping \u2014 your URL is preserved." })
+    );
   }
   const ready = await waitForReady(metricsPort).catch((err) => {
-    runner.stop();
+    child?.stop();
+    runner?.stop();
     dashboard?.stop();
     throw new CfldError(
       "The tunnel did not connect.",
       err instanceof Error ? err.message : void 0
     );
   });
+  if (child && !shuttingDown) {
+    if (dashboard) dashboard.update({ status: "waiting", connections: ready.connections });
+    else step(`Waiting for your dev server on :${ctx.port}\u2026`);
+    const up = await waitForPort(ctx.port, { signal: childAbort.signal });
+    if (shuttingDown) return;
+    if (!up) warn(`Nothing is listening on :${ctx.port} yet \u2014 going live anyway.`);
+  }
   if (!ctx.noEnv) {
     const { changed } = upsertEnv(join5(ctx.cwd, ".env"), ctx.envKey, url);
     if (changed && !dashboard) info(`Wrote ${ctx.envKey}=${url} to .env`);
@@ -1080,7 +1292,7 @@ ${reason}`);
   } else {
     summaryBox({ url, target, tunnelName: result.tunnelName, connections: ready.connections });
   }
-  const poll = setInterval(async () => {
+  poll = setInterval(async () => {
     const m = await scrapeMetrics(metricsPort);
     if (m && dashboard) {
       dashboard.update({
@@ -1093,8 +1305,7 @@ ${reason}`);
   poll.unref();
   if (dashboard) {
     await dashboard.waitUntilExit();
-    clearInterval(poll);
-    stop("Stopping \u2014 your URL is preserved. Re-run `cfld` to resume.");
+    shutdown({ reason: "Stopping \u2014 your URL is preserved. Re-run `cfld` to resume." });
   }
 }
 async function resolveZone(flags, configZone, knownZones, interactive) {
@@ -1142,13 +1353,13 @@ async function resolvePort(flags, configPort, interactive) {
 }
 
 // src/process/quick.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn5 } from "child_process";
 var QUICK_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
 async function startQuickTunnel(port, opts = {}) {
   const bin = await resolveBinary();
   const args = ["tunnel", "--url", `http://localhost:${port}`, "--no-autoupdate"];
   if (opts.metricsPort) args.push("--metrics", `127.0.0.1:${opts.metricsPort}`);
-  const child = spawn4(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+  const child = spawn5(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
       child.kill("SIGKILL");
@@ -1195,39 +1406,98 @@ async function quickCommand(flags) {
   const target = `localhost:${port}`;
   const interactive = isInteractive();
   const metricsPort = await findFreePort();
+  const envKey = flags.envKey ?? "PUBLIC_URL";
   if (!interactive) step(`Starting an ephemeral tunnel to ${target}\u2026`);
   let dashboard;
-  const logBuffer = [];
+  let tunnel;
+  let child;
+  let poll;
+  let shuttingDown = false;
+  const childAbort = new AbortController();
+  const tunnelBuffer = [];
+  const devBuffer = [];
   const emitLine = (line) => {
     const formatted = formatLogLine(line);
     if (!formatted) return;
-    logBuffer.push(formatted);
-    if (dashboard) dashboard.log(formatted);
+    tunnelBuffer.push(formatted);
+    if (dashboard) dashboard.log(formatted, "tunnel");
     else if (!interactive) process.stderr.write(formatted + "\n");
   };
-  const tunnel = await startQuickTunnel(port, { metricsPort, onLine: emitLine });
+  const emitDevLine = (line) => {
+    if (line.trim() === "") return;
+    devBuffer.push(line);
+    if (dashboard) dashboard.log(line, "dev");
+    else if (!interactive) process.stderr.write(line + "\n");
+  };
+  const shutdown = (opts = {}) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (poll) clearInterval(poll);
+    tunnel?.stop();
+    dashboard?.stop();
+    note(`
+${opts.reason ?? "Stopped ephemeral tunnel."}`);
+    const exit = () => setTimeout(() => process.exit(opts.code ?? 0), 100).unref();
+    if (child) reapChild(child).then(exit);
+    else exit();
+  };
+  tunnel = await startQuickTunnel(port, { metricsPort, onLine: emitLine });
+  const url = tunnel.url;
+  if (flags.exec) {
+    if (!interactive) step(`Starting \`${describeCommand(flags.exec)}\`\u2026`);
+    child = startChild({
+      command: flags.exec,
+      cwd: process.cwd(),
+      env: flags.noEnv ? void 0 : { [envKey]: url },
+      onLine: (line) => emitDevLine(line),
+      onExit: (code, signal) => {
+        childAbort.abort();
+        const how = code !== null ? `exited (code ${code})` : `was terminated${signal ? ` (${signal})` : ""}`;
+        shutdown({
+          reason: `Your dev command ${how} \u2014 stopping the ephemeral tunnel.`,
+          code: code ?? 1
+        });
+      }
+    });
+  }
   if (interactive) {
-    const { startDashboard } = await import("./dashboard-QUPY25QT.js");
+    const { startDashboard } = await import("./dashboard-Q6WI32AK.js");
     dashboard = startDashboard({
-      url: tunnel.url,
+      url,
       target,
       tunnelName: "quick (ephemeral)",
-      status: "live",
-      connections: 1,
+      // Hold at WAITING until the dev server opens the port (if we're running one).
+      status: child ? "waiting" : "live",
+      connections: child ? 0 : 1,
       requests: 0,
-      logs: logBuffer.slice(-12),
+      split: Boolean(flags.exec),
+      devLabel: flags.exec ? describeCommand(flags.exec) : void 0,
+      tunnelLogs: tunnelBuffer.slice(-200),
+      devLogs: devBuffer.slice(-200),
       ephemeral: true
     });
-  } else {
+  }
+  if (!dashboard) {
+    process.once("SIGINT", () => shutdown());
+    process.once("SIGTERM", () => shutdown());
+  }
+  if (child) {
+    if (!dashboard) step(`Waiting for your dev server on :${port}\u2026`);
+    const up = await waitForPort(port, { signal: childAbort.signal });
+    if (shuttingDown) return;
+    if (!up) warn(`Nothing is listening on :${port} yet \u2014 going live anyway.`);
+    dashboard?.update({ status: "live", connections: 1 });
+  }
+  if (!dashboard) {
     summaryBox({
-      url: tunnel.url,
+      url,
       target,
       tunnelName: "quick (ephemeral)",
       connections: 1,
       ephemeral: true
     });
   }
-  const poll = setInterval(async () => {
+  poll = setInterval(async () => {
     const m = await scrapeMetrics(metricsPort);
     if (m && dashboard) {
       dashboard.update({
@@ -1238,23 +1508,19 @@ async function quickCommand(flags) {
     }
   }, dashboard ? 1e3 : 15e3);
   poll.unref();
-  const stop = () => {
-    clearInterval(poll);
-    tunnel.stop();
-    dashboard?.stop();
-    note("\nStopped ephemeral tunnel.");
-    setTimeout(() => process.exit(0), 100).unref();
-  };
   if (dashboard) {
     await dashboard.waitUntilExit();
-    stop();
-  } else {
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
+    shutdown();
   }
 }
 async function resolvePort2(flags) {
   if (flags.port) return flags.port;
+  if (flags.exec) {
+    throw new CfldError(
+      "Specify the port your dev command will listen on.",
+      "e.g. `cfld --quick 3000 -- next dev`"
+    );
+  }
   const detected = await detectDevPorts();
   if (detected.length >= 1) {
     info(`Detected a local server on port ${detected[0]}.`);
@@ -1289,6 +1555,11 @@ async function initCommand(flags) {
     zone = normalizeZone(await askText("Domain (zone) on Cloudflare?", "example.com"));
   }
   const certPath = await ensureCert(zone, { interactive: true });
+  await configureProject(flags, { zone, certPath, cwd });
+  note("Run `cfld` to go live.");
+}
+async function configureProject(flags, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
   const defaultSlug = deriveSlug(cwd, flags.name);
   const name = slugify(await askText("Project name (used in the URL)", defaultSlug) || defaultSlug);
   const detected = await detectDevPorts();
@@ -1300,13 +1571,13 @@ async function initCommand(flags) {
   if (!Number.isInteger(port) || port <= 0) {
     throw new CfldError(`"${portStr}" is not a valid port.`);
   }
-  const hostname = flags.host ?? buildHostname(name, zone);
+  const hostname = flags.host ?? buildHostname(name, ctx.zone);
   const result = await reconcile(
     {
       slug: name,
       tunnelName: tunnelNameForSlug(name),
-      zone,
-      certPath,
+      zone: ctx.zone,
+      certPath: ctx.certPath,
       routes: [{ hostname, port }],
       projectDir: cwd,
       force: flags.force
@@ -1318,7 +1589,7 @@ async function initCommand(flags) {
   );
   writeProjectConfig(cwd, {
     name,
-    zone,
+    zone: ctx.zone,
     uuid: result.uuid,
     hostname,
     port,
@@ -1326,7 +1597,138 @@ async function initCommand(flags) {
   });
   if (ensureGitignored(cwd, ".cfld.json")) info("Added .cfld.json to .gitignore.");
   done(`Configured https://${hostname} \u2192 localhost:${port}`);
-  note("Run `cfld` to go live.");
+  return { name, hostname, port };
+}
+
+// src/commands/setup.ts
+async function setupCommand(flags) {
+  if (!isInteractive()) {
+    throw new CfldError(
+      "`cfld setup` is interactive.",
+      "In scripts, use `cfld --quick`, or `cfld` with --zone/--host/--name flags."
+    );
+  }
+  step("Let's get cfld set up.");
+  await preflightCloudflared();
+  const cwd = process.cwd();
+  const knownZones = Array.from(
+    /* @__PURE__ */ new Set([...listStoredZones(), ...listEntries().map((e) => e.zone)])
+  );
+  const alreadyAuthorized = knownZones.length > 0 || certHasZone(defaultCertPath());
+  if (alreadyAuthorized) {
+    const config = readProjectConfig(cwd);
+    if (config?.uuid || config?.zone) {
+      done("You're already set up \u2014 run `cfld` to go live.");
+      return;
+    }
+    info("You're already authorized with Cloudflare. Let's configure this project.");
+    const zone2 = await askAuthorizedZone(knownZones);
+    const certPath2 = await ensureCert(zone2, { interactive: true });
+    await configureProject(flags, { zone: zone2, certPath: certPath2, cwd });
+    await offerGoLive(flags, zone2);
+    return;
+  }
+  const path = await askSelect("How do you want to start?", [
+    {
+      value: "quick",
+      label: "Get a public URL right now \u2014 free, no account (temporary URL)"
+    },
+    {
+      value: "persistent",
+      label: "Set up a persistent URL \u2014 free Cloudflare account + a domain"
+    }
+  ]);
+  if (path === "quick") {
+    note(
+      "  Starting a temporary tunnel. Run `cfld setup` again anytime to set up a persistent URL."
+    );
+    await quickCommand(flags);
+    return;
+  }
+  note(
+    [
+      "",
+      "  A browser window will open to authorize cfld with Cloudflare.",
+      `    \u2022 No account yet? Click "Sign up" on that page \u2014 it's free.`,
+      "    \u2022 Then pick (or add) the domain you want to use.",
+      "  Prefer to create the account first? Open:",
+      "      https://dash.cloudflare.com/sign-up",
+      ""
+    ].join("\n")
+  );
+  if (!await askConfirm("Open the browser to authorize now?")) {
+    note(
+      "No problem \u2014 run `cfld setup` again when you're ready, or `cfld --quick` for a temporary URL."
+    );
+    return;
+  }
+  await runLogin();
+  if (!certHasZone(defaultCertPath())) {
+    printZeroZoneGuidance();
+    if (await askConfirm("Start a temporary quick tunnel now instead?")) {
+      await quickCommand(flags);
+      return;
+    }
+    throw new CfldError(
+      "Your Cloudflare account has no domain yet, so a persistent URL isn't possible.",
+      "Add a domain (see above), then run `cfld setup` again."
+    );
+  }
+  const zone = await askAuthorizedZone(knownZones);
+  const certPath = importCert(zone);
+  info(`Saved cert for ${zone}.`);
+  await configureProject(flags, { zone, certPath, cwd });
+  await offerGoLive(flags, zone);
+}
+async function preflightCloudflared() {
+  try {
+    const bin = await resolveBinary();
+    const res = await exec(bin, ["--version"]);
+    const version = (res.stdout.trim() || res.stderr.trim()).split("\n")[0];
+    done(`cloudflared ready${version ? ` \u2014 ${version}` : ""}`);
+  } catch {
+    warn("cloudflared isn't installed, and the bundled binary couldn't load.");
+    note(
+      [
+        "",
+        "  Install it, then run `cfld setup` again:",
+        "    macOS     brew install cloudflared",
+        "    Linux     apt / dnf / pacman install cloudflared",
+        "    Windows   winget install --id Cloudflare.cloudflared",
+        "    Any OS    https://developers.cloudflare.com/tunnel/downloads/",
+        ""
+      ].join("\n")
+    );
+    throw new CfldError(
+      "cloudflared is required to continue.",
+      "Install it (see above), or set CFLD_CLOUDFLARED to its path."
+    );
+  }
+}
+function isBlankFirstRun(flags, cwd, interactive = isInteractive()) {
+  if (!interactive) return false;
+  if (flags.zone || flags.host || flags.quick) return false;
+  if (readProjectConfig(cwd)) return false;
+  if (listStoredZones().length > 0) return false;
+  if (certHasZone(defaultCertPath())) return false;
+  return true;
+}
+async function askAuthorizedZone(knownZones) {
+  if (knownZones.length) {
+    const picked = await askSelect("Which domain did you authorize?", [
+      ...knownZones.map((z) => ({ value: z, label: z })),
+      { value: "__new__", label: "A different domain\u2026" }
+    ]);
+    if (picked !== "__new__") return picked;
+  }
+  return normalizeZone(await askText("Which domain did you authorize?", "example.com"));
+}
+async function offerGoLive(flags, zone) {
+  if (await askConfirm("Go live now?")) {
+    await runCommand({ ...flags, zone });
+  } else {
+    note("Run `cfld` to go live.");
+  }
 }
 
 // src/commands/list.ts
@@ -1770,7 +2172,32 @@ async function doctorCommand() {
 }
 
 // src/cli.ts
+function readVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync7(join7(here, "../package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function splitAtDoubleDash(rawArgv) {
+  const i = rawArgv.indexOf("--");
+  if (i === -1) return { argv: rawArgv, afterDash: [] };
+  return { argv: rawArgv.slice(0, i), afterDash: rawArgv.slice(i + 1) };
+}
+function resolveExec(afterDash, execFlag) {
+  const hasArgv = afterDash.length > 0;
+  const hasShell = execFlag !== void 0 && execFlag.trim() !== "";
+  if (hasArgv && hasShell) {
+    throw new Error('Use either `-- <cmd>` or `--exec "<cmd>"`, not both.');
+  }
+  if (hasArgv) return { shell: false, argv: afterDash };
+  if (hasShell) return { shell: true, command: execFlag.trim() };
+  return void 0;
+}
 var SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "setup",
   "login",
   "init",
   "list",
@@ -1784,10 +2211,12 @@ var SUBCOMMANDS = /* @__PURE__ */ new Set([
 var HELP = `${pc7.bold("cfld")} \u2014 persistent Cloudflare tunnels for local dev
 
 ${pc7.bold("Usage")}
+  cfld --quick [port]      Instant public URL, no account needed (temporary)
+  cfld setup               Guided first-run: free instant URL, or persistent setup
   cfld [port]              Ensure + run a persistent tunnel (reuses the same URL)
-  cfld --quick [port]      Ephemeral trycloudflare.com URL (no domain needed)
+  cfld [port] -- <cmd>     Run + supervise your dev server too (one lifecycle)
   cfld login [--reauth]    Authorize with Cloudflare in your browser
-  cfld init                Interactive setup wizard (configure, don't run)
+  cfld init                Configure a persistent tunnel (don't run)
   cfld list                List all tunnels across projects/domains
   cfld status [name]       Show details for a tunnel
   cfld up <name>           Run a registered tunnel by name from anywhere
@@ -1801,11 +2230,17 @@ ${pc7.bold("Options")}
   --zone <domain>   Cloudflare domain to use (e.g. example.com)
   --env <KEY>       .env key to write the URL to (default: PUBLIC_URL)
   --no-env          Don't write the URL to .env
+  --exec <cmd>      Dev command to run + supervise (shell form of \`-- <cmd>\`)
   --force           Skip confirmation (destroy)
   -h, --help        Show this help
   -v, --version     Show version
+
+${pc7.bold("Examples")}
+  cfld 3000 -- next dev            Start Next.js + the tunnel; one Ctrl-C stops both
+  cfld 5173 --exec "npm run dev"   Same, via a shell command string
 `;
-async function main(argv) {
+async function main(rawArgv) {
+  const { argv, afterDash } = splitAtDoubleDash(rawArgv);
   const { values, positionals } = parseArgs({
     args: argv,
     allowPositionals: true,
@@ -1815,6 +2250,7 @@ async function main(argv) {
       zone: { type: "string" },
       env: { type: "string" },
       "no-env": { type: "boolean" },
+      exec: { type: "string" },
       quick: { type: "boolean" },
       force: { type: "boolean" },
       reauth: { type: "boolean" },
@@ -1823,7 +2259,8 @@ async function main(argv) {
     }
   });
   if (values.version) {
-    process.stdout.write("cfld 0.1.0\n");
+    process.stdout.write(`cfld ${readVersion()}
+`);
     return;
   }
   if (values.help) {
@@ -1838,14 +2275,23 @@ async function main(argv) {
     noEnv: values["no-env"],
     quick: values.quick,
     force: values.force,
-    reauth: values.reauth
+    reauth: values.reauth,
+    exec: resolveExec(afterDash, values.exec)
   };
   const [first, ...rest] = positionals;
+  if (flags.exec && first && SUBCOMMANDS.has(first)) {
+    throw new Error(
+      `A dev command (\`-- \u2026\` / --exec) can't be combined with \`cfld ${first}\`. Use \`cfld [port] -- <cmd>\`.`
+    );
+  }
   if (first && SUBCOMMANDS.has(first)) {
     switch (first) {
       case "help":
         process.stdout.write(HELP);
         return;
+      case "setup":
+        await setupCommand(flags);
+        return;
       case "login":
         await loginCommand(flags);
         return;
@@ -1880,11 +2326,28 @@ async function main(argv) {
   }
   if (flags.quick) {
     await quickCommand(flags);
+  } else if (isBlankFirstRun(flags, process.cwd())) {
+    await setupCommand(flags);
   } else {
     await runCommand(flags);
   }
 }
-main(process.argv.slice(2)).catch((err) => {
-  printError(err);
-  process.exit(1);
-});
+function invokedDirectly() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (invokedDirectly()) {
+  main(process.argv.slice(2)).catch((err) => {
+    printError(err);
+    process.exit(1);
+  });
+}
+export {
+  resolveExec,
+  splitAtDoubleDash
+};

package/dist/dashboard-Q6WI32AK.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+// src/ui/dashboard.tsx
+import "react";
+import { Box, render, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+var MAX_BUFFER = 1e3;
+var HEADER_ROWS = 5;
+function statusDot(status) {
+  switch (status) {
+    case "live":
+      return /* @__PURE__ */ jsx(Text, { color: "green", children: "\u25CF LIVE" });
+    case "waiting":
+      return /* @__PURE__ */ jsx(Text, { color: "yellow", children: "\u25CC WAITING" });
+    case "reconnecting":
+      return /* @__PURE__ */ jsx(Text, { color: "yellow", children: "\u25CC RECONNECTING" });
+    default:
+      return /* @__PURE__ */ jsx(Text, { color: "cyan", children: "\u25CC CONNECTING" });
+  }
+}
+function Header(state) {
+  const latency = state.avgLatencyMs !== void 0 ? `  \u26A1 ${state.avgLatencyMs}ms avg` : "";
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [
+    /* @__PURE__ */ jsxs(Box, { children: [
+      statusDot(state.status),
+      /* @__PURE__ */ jsx(Text, { children: " " }),
+      /* @__PURE__ */ jsx(Text, { color: "cyan", bold: true, children: state.url })
+    ] }),
+    /* @__PURE__ */ jsxs(Box, { children: [
+      /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+        "\u2192 ",
+        state.target
+      ] }),
+      /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+        "   ",
+        state.connections,
+        " edge conns"
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxs(Box, { children: [
+      /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+        "\u2191 ",
+        state.requests,
+        " reqs",
+        latency
+      ] }),
+      /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+        "   ",
+        state.ephemeral ? "ephemeral \xB7 Ctrl-C stops" : "Ctrl-C stops \xB7 URL preserved"
+      ] })
+    ] })
+  ] });
+}
+function LogColumn({
+  title,
+  titleColor,
+  lines,
+  rows,
+  placeholder,
+  divider
+}) {
+  return /* @__PURE__ */ jsxs(
+    Box,
+    {
+      flexDirection: "column",
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: 0,
+      paddingLeft: divider ? 1 : 0,
+      borderStyle: divider ? "single" : void 0,
+      borderColor: "gray",
+      borderTop: false,
+      borderBottom: false,
+      borderRight: false,
+      borderLeft: Boolean(divider),
+      children: [
+        title ? /* @__PURE__ */ jsx(Text, { color: titleColor, bold: true, wrap: "truncate-end", children: title }) : null,
+        /* @__PURE__ */ jsx(Box, { flexDirection: "column", flexGrow: 1, justifyContent: "flex-end", overflow: "hidden", children: lines.length === 0 ? /* @__PURE__ */ jsx(Text, { dimColor: true, children: placeholder }) : lines.slice(-rows).map((line, i) => /* @__PURE__ */ jsx(Text, { wrap: "truncate-end", children: line }, i)) })
+      ]
+    }
+  );
+}
+function Dashboard(state) {
+  const termRows = process.stdout.rows || 24;
+  const titleRows = state.split ? 1 : 0;
+  const logRows = Math.max(3, termRows - HEADER_ROWS - titleRows - 1);
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", height: termRows, overflow: "hidden", children: [
+    /* @__PURE__ */ jsx(Header, { ...state }),
+    state.split ? /* @__PURE__ */ jsxs(Box, { flexGrow: 1, flexDirection: "row", paddingX: 1, paddingTop: 1, children: [
+      /* @__PURE__ */ jsx(
+        LogColumn,
+        {
+          title: state.devLabel ?? "dev server",
+          titleColor: "cyan",
+          lines: state.devLogs,
+          rows: logRows,
+          placeholder: "waiting for dev-server output\u2026"
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        LogColumn,
+        {
+          title: "tunnel",
+          titleColor: "blue",
+          lines: state.tunnelLogs,
+          rows: logRows,
+          placeholder: "waiting for tunnel activity\u2026",
+          divider: true
+        }
+      )
+    ] }) : /* @__PURE__ */ jsx(Box, { flexGrow: 1, paddingX: 1, paddingTop: 1, children: /* @__PURE__ */ jsx(
+      LogColumn,
+      {
+        lines: state.tunnelLogs,
+        rows: logRows,
+        placeholder: state.ephemeral ? "waiting for traffic\u2026 (Ctrl-C stops; this URL is temporary)" : "waiting for traffic\u2026 (Ctrl-C stops; your URL is preserved)"
+      }
+    ) })
+  ] });
+}
+var ENTER_ALT_SCREEN = "\x1B[?1049h";
+var LEAVE_ALT_SCREEN = "\x1B[?1049l";
+function startDashboard(initial) {
+  const state = {
+    ...initial,
+    tunnelLogs: [...initial.tunnelLogs],
+    devLogs: [...initial.devLogs]
+  };
+  process.stdout.write(ENTER_ALT_SCREEN);
+  const instance = render(/* @__PURE__ */ jsx(Dashboard, { ...state }), {
+    stdout: process.stdout,
+    // We drive graceful shutdown ourselves; ink's Ctrl-C simply resolves
+    // waitUntilExit, and the caller then stops the runner (preserving state).
+    exitOnCtrlC: true
+  });
+  const rerender = () => instance.rerender(/* @__PURE__ */ jsx(Dashboard, { ...state }));
+  let altActive = true;
+  const leaveAltScreen = () => {
+    if (!altActive) return;
+    altActive = false;
+    process.stdout.write(LEAVE_ALT_SCREEN);
+  };
+  const onResize = () => {
+    instance.clear();
+    rerender();
+  };
+  process.stdout.on("resize", onResize);
+  process.once("exit", leaveAltScreen);
+  return {
+    update(partial) {
+      Object.assign(state, partial);
+      rerender();
+    },
+    log(line, source = "tunnel") {
+      if (source === "dev") {
+        state.devLogs = [...state.devLogs, line].slice(-MAX_BUFFER);
+      } else {
+        state.tunnelLogs = [...state.tunnelLogs, line].slice(-MAX_BUFFER);
+      }
+      rerender();
+    },
+    waitUntilExit() {
+      return instance.waitUntilExit();
+    },
+    stop() {
+      process.stdout.off("resize", onResize);
+      process.removeListener("exit", leaveAltScreen);
+      instance.unmount();
+      leaveAltScreen();
+    }
+  };
+}
+export {
+  startDashboard
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliftonc/cfld",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Zero-token, persistent Cloudflare tunnel CLI for local dev — same public HTTPS URL every run.",
   "type": "module",
   "bin": {

package/dist/dashboard-QUPY25QT.js

@@ -1,85 +0,0 @@
-#!/usr/bin/env node
-
-// src/ui/dashboard.tsx
-import "react";
-import { Box, render, Text } from "ink";
-import { jsx, jsxs } from "react/jsx-runtime";
-var MAX_LOGS = 12;
-function statusDot(status) {
-  switch (status) {
-    case "live":
-      return /* @__PURE__ */ jsx(Text, { color: "green", children: "\u25CF LIVE" });
-    case "reconnecting":
-      return /* @__PURE__ */ jsx(Text, { color: "yellow", children: "\u25CC RECONNECTING" });
-    default:
-      return /* @__PURE__ */ jsx(Text, { color: "cyan", children: "\u25CC CONNECTING" });
-  }
-}
-function Dashboard(state) {
-  const latency = state.avgLatencyMs !== void 0 ? `  \u26A1 ${state.avgLatencyMs}ms avg` : "";
-  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
-    /* @__PURE__ */ jsxs(
-      Box,
-      {
-        flexDirection: "column",
-        borderStyle: "round",
-        borderColor: "cyan",
-        paddingX: 1,
-        children: [
-          /* @__PURE__ */ jsxs(Box, { children: [
-            statusDot(state.status),
-            /* @__PURE__ */ jsx(Text, { children: " " }),
-            /* @__PURE__ */ jsx(Text, { color: "cyan", bold: true, children: state.url })
-          ] }),
-          /* @__PURE__ */ jsxs(Box, { children: [
-            /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
-              "\u2192 ",
-              state.target
-            ] }),
-            /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
-              "   ",
-              state.connections,
-              " edge conns"
-            ] })
-          ] }),
-          /* @__PURE__ */ jsx(Box, { children: /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
-            "\u2191 ",
-            state.requests,
-            " reqs",
-            latency
-          ] }) })
-        ]
-      }
-    ),
-    /* @__PURE__ */ jsx(Box, { flexDirection: "column", paddingX: 1, children: state.logs.length === 0 ? /* @__PURE__ */ jsx(Text, { dimColor: true, children: state.ephemeral ? "waiting for traffic\u2026 (Ctrl-C stops; this URL is temporary)" : "waiting for traffic\u2026 (Ctrl-C stops; your URL is preserved)" }) : state.logs.map((line, i) => /* @__PURE__ */ jsx(Text, { dimColor: true, wrap: "truncate-end", children: line }, i)) })
-  ] });
-}
-function startDashboard(initial) {
-  const state = { ...initial, logs: [...initial.logs] };
-  const instance = render(/* @__PURE__ */ jsx(Dashboard, { ...state }), {
-    stdout: process.stdout,
-    // We drive graceful shutdown ourselves; ink's Ctrl-C simply resolves
-    // waitUntilExit, and the caller then stops the runner (preserving state).
-    exitOnCtrlC: true
-  });
-  const rerender = () => instance.rerender(/* @__PURE__ */ jsx(Dashboard, { ...state }));
-  return {
-    update(partial) {
-      Object.assign(state, partial);
-      rerender();
-    },
-    log(line) {
-      state.logs = [...state.logs, line].slice(-MAX_LOGS);
-      rerender();
-    },
-    waitUntilExit() {
-      return instance.waitUntilExit();
-    },
-    stop() {
-      instance.unmount();
-    }
-  };
-}
-export {
-  startDashboard
-};