@mycadet/cli 0.12.8 → 0.12.9

package/src/lib/cloud-releases.ts

@@ -85,7 +85,9 @@ export async function fetchLatestStableVersion(): Promise<string | null> {
 }
 
 /**
- * Image refs for a target version: the tag is the target version, the repo
+ * Image refs for a target version: the tag is the target version exactly as
+ * the release workflows push it — bare ("0.12.8", "0.12.8-dev…"); a
+ * git-tag-style "v" prefix on the input is tolerated and stripped. The repo
  * follows the CLI's own version shape (dev CLI → `-dev` repos).
  */
 export function resolveImageRefs(
@@ -93,8 +95,8 @@ export function resolveImageRefs(
   cliVersion: string,
 ): Record<ServiceName, string> {
   const versionTag = targetVersion.startsWith("v")
-    ? targetVersion
-    : `v${targetVersion}`;
+    ? targetVersion.slice(1)
+    : targetVersion;
   const images = dockerhubImages(cliVersion);
   return {
     assistant: `${images.assistant}:${versionTag}`,
@@ -107,5 +109,5 @@ export function resolveImageRefs(
 export function resolveOwnImageRefs(
   cliVersion: string,
 ): Record<ServiceName, string> {
-  return resolveImageRefs(cliVersion ? `v${cliVersion}` : "latest", cliVersion);
+  return resolveImageRefs(cliVersion || "latest", cliVersion);
 }

package/src/lib/docker.ts

@@ -40,6 +40,7 @@ import {
 import { resolveOwnImageRefs } from "./cloud-releases.js";
 import { isDevVersion } from "./version-compat.js";
 import {
+  collectProviderApiKey,
   configureHatchProviderApiKey,
   formatProviderName,
   promptProviderChoice,
@@ -340,14 +341,96 @@ export function resolveDockerProviderCredentialSetupAction(options: {
   provider: string | null | undefined;
   guardianAccessToken?: string;
   detached: boolean;
+  /**
+   * Key — or an explicit skip ("") — collected from the user right after
+   * they picked the provider. When present (even empty), the user already
+   * answered at the prompt, so detached hatches configure (or report the
+   * missing key) instead of deferring to a second `cadet setup` run.
+   */
+  precollectedKey?: string;
 }): DockerProviderCredentialSetupAction {
   if (options.provider === undefined) return "skip";
   if (options.provider === null) return options.detached ? "skip" : "configure";
-  if (options.detached) return "defer";
+  if (options.detached) {
+    if (options.precollectedKey !== undefined) {
+      return options.guardianAccessToken ? "configure" : "missing-token";
+    }
+    return "defer";
+  }
   if (!options.guardianAccessToken) return "missing-token";
   return "configure";
 }
 
+/** Time to wait for the Docker daemon to answer `docker info` after a Colima start. */
+const COLIMA_SETTLE_TIMEOUT_MS = 15_000;
+
+/** Poll `docker info` until the daemon answers or the timeout elapses. */
+async function waitForDockerDaemon(
+  execFn: typeof exec,
+  timeoutMs: number,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      await execFn("docker", ["info"]);
+      return true;
+    } catch {
+      if (Date.now() >= deadline) return false;
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+}
+
+/**
+ * Start Colima and wait for the Docker daemon to actually answer.
+ *
+ * `colima start` exiting 0 only means Colima's own state file says the VM is
+ * up — that state can be stale (zombie VM after a host sleep or crash), in
+ * which case start is a no-op ("already running, ignoring") while the daemon
+ * inside stays dead. So success is decided by re-probing `docker info`, and a
+ * failed probe triggers the manual-fix cycle: force-stop and start fresh.
+ * Never `colima delete` — the VM disk holds every container image and volume.
+ * `startArgs` carries extra flags (e.g. `--memory`) for a first start; the
+ * wake path starts an existing instance bare.
+ */
+async function startColimaAndAwaitDaemon(
+  execFn: typeof exec,
+  log: (msg: string) => void,
+  opts: { startArgs?: string[]; settleTimeoutMs?: number } = {},
+): Promise<void> {
+  const startArgs = opts.startArgs ?? [];
+  const settleTimeoutMs = opts.settleTimeoutMs ?? COLIMA_SETTLE_TIMEOUT_MS;
+
+  try {
+    await execFn("colima", ["start", ...startArgs]);
+  } catch (err) {
+    // exec captures the child's output and only surfaces it in the error —
+    // print it so a failed start is never silent.
+    log(`⚠️  colima start failed: ${err instanceof Error ? err.message : err}`);
+  }
+
+  if (await waitForDockerDaemon(execFn, settleTimeoutMs)) return;
+
+  log(
+    "🔄 Colima state looks stale — restarting the VM (colima stop --force, then start)...",
+  );
+  await execFn("colima", ["stop", "--force"]).catch(() => {});
+  try {
+    await execFn("colima", ["start", ...startArgs]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to restart Colima. Please run 'colima stop --force && colima start' manually.\n${message}`,
+    );
+  }
+  if (!(await waitForDockerDaemon(execFn, settleTimeoutMs))) {
+    throw new Error(
+      "Docker daemon is still not reachable after restarting Colima. " +
+        "Check `colima status` and `docker info`, then try again.",
+    );
+  }
+}
+
 /**
  * Checks whether the `docker` CLI and daemon are available on the system.
  * Installs Colima and Docker via direct binary download if missing (no sudo
@@ -418,41 +501,9 @@ async function ensureDockerInstalled(): Promise<void> {
     }
 
     console.log("🚀 Docker daemon not running. Starting Colima...");
-    try {
-      await exec("colima", [
-        "start",
-        "--memory",
-        String(COLIMA_DEFAULT_MEMORY_GIB),
-      ]);
-    } catch {
-      // Colima may fail if a previous VM instance is in a corrupt state.
-      // Attempt to delete the stale instance and retry once.
-      console.log(
-        "⚠️  Colima start failed — attempting to reset stale VM state...",
-      );
-      try {
-        await exec("colima", ["stop", "--force"]).catch(() => {});
-        await exec("colima", ["delete", "--force"]);
-      } catch {
-        // If delete also fails, fall through to the retry which will
-        // produce a clear error message.
-      }
-
-      try {
-        console.log("🔄 Retrying colima start...");
-        await exec("colima", [
-          "start",
-          "--memory",
-          String(COLIMA_DEFAULT_MEMORY_GIB),
-        ]);
-      } catch (retryErr) {
-        const message =
-          retryErr instanceof Error ? retryErr.message : String(retryErr);
-        throw new Error(
-          `Failed to start Colima after resetting stale VM state. Please run 'colima start' manually.\n${message}`,
-        );
-      }
-    }
+    await startColimaAndAwaitDaemon(exec, console.log, {
+      startArgs: ["--memory", String(COLIMA_DEFAULT_MEMORY_GIB)],
+    });
   }
 }
 
@@ -486,6 +537,56 @@ export async function removeContainer(containerName: string): Promise<void> {
   }
 }
 
+/**
+ * Error signatures Docker Hub returns when the host has STALE Docker Hub
+ * credentials: an expired personal access token saved by a past
+ * `docker login` gets attached to the pull, and Hub rejects the request
+ * instead of falling back to anonymous access for a public image.
+ */
+export function isExpiredDockerHubCredentialError(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  return /personal access token is expired|authentication required|unauthorized/i.test(
+    message,
+  );
+}
+
+/**
+ * Pull an image, retrying once without stale credentials when Docker Hub
+ * rejects the pull with an expired-token/auth error — public pulls need no
+ * login, so `docker logout` (clears the stored Docker Hub credentials the
+ * docker CLI attaches to pulls) costs nothing. Other failures propagate raw;
+ * a still-failing auth retry is rethrown with actionable copy.
+ */
+export async function pullImage(
+  ref: string,
+  log: (msg: string) => void = console.log,
+  execFn: typeof exec = exec,
+): Promise<void> {
+  try {
+    await execFn("docker", ["pull", ref]);
+    return;
+  } catch (err) {
+    if (!isExpiredDockerHubCredentialError(err)) throw err;
+    log(
+      `⚠️  Docker Hub rejected the pull of ${ref} with an expired-credential ` +
+        `error — clearing stale Docker Hub login and retrying (public images ` +
+        `need no credentials)...`,
+    );
+    await execFn("docker", ["logout"]).catch(() => {});
+  }
+  try {
+    await execFn("docker", ["pull", ref]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to pull ${ref}.\n${message}\n` +
+        `If the Docker daemon is not running, start it, e.g. 'colima start' on macOS. ` +
+        `If the error mentions authentication, run 'docker logout' and check your ` +
+        `Docker Hub credentials — public image pulls need none.`,
+    );
+  }
+}
+
 export async function retireDocker(name: string): Promise<void> {
   console.log(`\u{1F5D1}\ufe0f  Stopping Docker containers for '${name}'...\n`);
 
@@ -846,7 +947,7 @@ export async function recreateDockerContainers(entry: AssistantEntry): Promise<v
   // already-present image is a cheap no-op.
   for (const image of [info.assistantImage, info.gatewayImage, info.cesImage]) {
     log(`📦 Pulling ${image}...`);
-    await exec("docker", ["pull", image]);
+    await pullImage(image, log);
   }
 
   const gatewayPort = parseGatewayPort(entry.runtimeUrl) ??
@@ -912,6 +1013,7 @@ function parseGatewayPort(runtimeUrl: string): number | null {
  */
 export async function ensureDockerDaemonRunning(
   execFn: typeof exec = exec,
+  opts: { settleTimeoutMs?: number } = {},
 ): Promise<void> {
   ensureLocalBinOnPath();
 
@@ -924,12 +1026,10 @@ export async function ensureDockerDaemonRunning(
     // No daemon reachable — fall through to the Colima fallback below.
   }
 
-  try {
-    await execFn("colima", ["status"]);
-  } catch {
-    console.log("🚀 Docker daemon not running. Starting Colima...");
-    await execFn("colima", ["start"]);
-  }
+  // Deliberately no `colima status` probe: it trusts Colima's own state file,
+  // which can be stale (zombie VM) — daemon reachability is the oracle.
+  console.log("🚀 Docker daemon not running. Starting Colima...");
+  await startColimaAndAwaitDaemon(execFn, console.log, opts);
 }
 
 /**
@@ -1234,6 +1334,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
   let provider = setupProviderCredentials
     ? resolveHatchProvider(configValues)
     : undefined;
+  let precollectedApiKey: string | undefined;
 
   if (
     shouldPromptForHatchProvider({
@@ -1246,6 +1347,9 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
     const picked = await promptProviderChoice();
     if (picked) {
       provider = picked;
+      // Collect the key immediately, while the choice is fresh — the
+      // startup logs are quiet now, so nothing separates the two prompts.
+      precollectedApiKey = await collectProviderApiKey(picked);
     }
   }
 
@@ -1427,7 +1531,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
           const MAX_PULL_RETRIES = 3;
           for (let attempt = 1; attempt <= MAX_PULL_RETRIES; attempt++) {
             try {
-              await exec("docker", ["pull", ref]);
+              await pullImage(ref, log);
               break;
             } catch (err) {
               if (attempt === MAX_PULL_RETRIES) throw err;
@@ -1631,6 +1735,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         provider,
         guardianAccessToken,
         detached: waitDetached,
+        precollectedKey: precollectedApiKey,
       });
 
       if (providerSetupAction === "defer" && provider !== null) {
@@ -1657,6 +1762,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
           provider,
           bearerToken: guardianAccessToken,
           env: process.env,
+          precollectedKey: precollectedApiKey,
           log,
         });
       }

package/src/lib/ensure-binary.ts

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+
+/**
+ * Consolidated missing-dependency flow for interactive commands: probe for a
+ * binary, and when it is absent, offer to install it — naming no commands —
+ * then run the right package manager for the platform and verify. Callers
+ * supply the recipes; everything else (prompt, package-manager discovery,
+ * fallback copy) lives here so every command behaves the same.
+ */
+
+export interface EnsureBinaryOptions {
+  /** The binary as invoked on PATH, e.g. "nginx". */
+  binary: string;
+  /** What the running command needs it for, e.g. "the tunnel edge". */
+  purpose: string;
+  /**
+   * Package-manager name → full install argv (sudo included where needed),
+   * e.g. `{ brew: ["brew", "install", "nginx"] }`. The first entry whose
+   * package manager is available wins. Leave out a platform rather than
+   * guessing at an unreliable package ID — the manual hint covers it.
+   */
+  packages: Record<string, string[]>;
+  /** Shown when the user declines or auto-install fails. */
+  manualHint: string;
+  /** Probe: a version-ish string when the binary is usable, null otherwise. */
+  probe: () => string | null;
+  /** Check that a package manager exists. Default: `<pm> --version` probe. */
+  pmAvailable?: (pm: string) => boolean;
+  /** Run an install argv; true on success. Default: inherit-stdio spawnSync. */
+  runInstall?: (argv: string[]) => boolean;
+  /** Confirm the install. Default: promptLine "[Y/n]" on Enter-as-yes. */
+  confirmInstall?: () => Promise<boolean>;
+  streams?: {
+    input?: NodeJS.ReadStream | Readable;
+    output?: NodeJS.WriteStream | Writable;
+  };
+}
+
+/**
+ * Prompt-then-install a missing binary. Returns the probe result — the
+ * existing version when the binary was already present, the fresh one after a
+ * successful install — or null when the binary is missing and the user
+ * declines, no package manager matches, or the install fails. Non-interactive
+ * callers (no TTY) never hang: they get the manual hint and null.
+ */
+export async function ensureBinaryInstalled(
+  opts: EnsureBinaryOptions,
+): Promise<string | null> {
+  const output = opts.streams?.output ?? process.stdout;
+
+  const existing = opts.probe();
+  if (existing) return existing;
+
+  output.write(
+    `\n${opts.binary} is required for ${opts.purpose}, but it isn't installed.\n`,
+  );
+
+  const confirm = opts.confirmInstall ?? defaultConfirm(opts);
+  let install = false;
+  try {
+    install = await confirm();
+  } catch {
+    install = false;
+  }
+  if (!install) {
+    output.write(`Skipping install. ${opts.manualHint}\n`);
+    return null;
+  }
+
+  const pmAvailable = opts.pmAvailable ?? probePackageManager;
+  const argv = Object.entries(opts.packages).find(([pm]) =>
+    pmAvailable(pm),
+  )?.[1];
+  if (!argv) {
+    output.write(`⚠ No supported package manager found. ${opts.manualHint}\n`);
+    return null;
+  }
+
+  const ok = opts.runInstall ? opts.runInstall(argv) : runInstallArgv(argv);
+  const version = ok ? opts.probe() : null;
+  if (!version) {
+    output.write(
+      `⚠ Couldn't install ${opts.binary} automatically. ${opts.manualHint}\n`,
+    );
+    return null;
+  }
+  output.write(`✅ Installed ${opts.binary} (${version}).\n`);
+  return version;
+}
+
+/** Default confirm: visible prompt, Enter = yes, non-TTY throws. */
+function defaultConfirm(opts: EnsureBinaryOptions): () => Promise<boolean> {
+  return async () => {
+    const input = opts.streams?.input ?? process.stdin;
+    const output = opts.streams?.output ?? process.stdout;
+    // Readable has no isTTY; only a real terminal answers the prompt.
+    if (!("isTTY" in input) || !input.isTTY) {
+      throw new Error("Install confirm requires an interactive terminal.");
+    }
+    const answer = (
+      await readLineText(`Install ${opts.binary} now? [Y/n] `, {
+        input,
+        output,
+      })
+    )
+      .trim()
+      .toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  };
+}
+
+/** Default installer: blocking spawn with inherited stdio (passwords flow). */
+function runInstallArgv(argv: string[]): boolean {
+  const [command, ...args] = argv;
+  if (!command) return false;
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  return !result.error && result.status === 0;
+}
+
+/** Default package-manager check: the manager answers `--version`. */
+function probePackageManager(pm: string): boolean {
+  const result = spawnSync(pm, ["--version"], {
+    stdio: "ignore",
+    shell: process.platform === "win32",
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+/**
+ * Read one visible line from stdin (Enter submits). Shared by the binary
+ * install confirm and the ngrok authtoken paste-in, so both degrade the same
+ * way on a non-interactive terminal (the caller decides what empty means).
+ */
+export async function readLineText(
+  prompt: string,
+  streams: { input?: Readable; output?: Writable } = {},
+): Promise<string> {
+  const input = streams.input ?? process.stdin;
+  const output = streams.output ?? process.stdout;
+
+  output.write(prompt);
+
+  return new Promise((resolve, reject) => {
+    let line = "";
+    const onData = (chunk: Buffer | string): void => {
+      line += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+      const newline = line.indexOf("\n");
+      if (newline !== -1) {
+        done(line.slice(0, newline).replace(/\r$/, ""));
+      }
+    };
+    const cleanup = (): void => {
+      input.removeListener("data", onData);
+      input.removeListener("error", onError);
+      input.pause();
+    };
+    const done = (value: string): void => {
+      cleanup();
+      resolve(value);
+    };
+    const onError = (err: Error): void => {
+      cleanup();
+      reject(err);
+    };
+    input.resume();
+    input.on("data", onData);
+    input.on("error", onError);
+  });
+}

package/src/lib/flag-args.test.ts

@@ -75,7 +75,7 @@ describe("parseFeatureFlagArgs", () => {
       "process.exit",
     );
     expect(errorSpy).toHaveBeenCalledWith(
-      'Error: invalid flag key "UPPER". Keys must be kebab-case (e.g. "browser")',
+      'Error: invalid flag key "UPPER". Keys must be kebab-case, e.g. "browser"',
     );
 
     exitSpy.mockRestore();

package/src/lib/flag-args.ts

@@ -38,7 +38,7 @@ export function parseFeatureFlagArgs(args: string[]): {
 
       if (!ALLOWED_KEY_RE.test(key)) {
         console.error(
-          `Error: invalid flag key "${key}". Keys must be kebab-case (e.g. "browser")`,
+          `Error: invalid flag key "${key}". Keys must be kebab-case, e.g. "browser"`,
         );
         process.exit(1);
       }

package/src/lib/guardian-token.ts

@@ -429,7 +429,7 @@ export async function refreshGuardianTokenResult(
     console.warn(
       `Refusing to refresh the guardian token over an insecure URL (${gatewayUrl}). ` +
         "The refresh token is only sent over https or a loopback address: " +
-        "use an https URL (e.g. a tunnel) or connect over loopback.",
+        "use an https URL, e.g. a tunnel, or connect over loopback.",
     );
     return {
       ok: false,

package/src/lib/hatch-local.ts

@@ -384,7 +384,7 @@ export async function hatchLocal(
         await new Promise((r) => setTimeout(r, delayMs));
       } else {
         reporter.error(
-          `⚠️  Guardian token lease failed${err instanceof GuardianLeasePermanentError ? " (not retrying — a malformed 200 will not fix itself)" : ` after ${maxLeaseAttempts} attempts`}: ${err}\n` +
+          `⚠️  Guardian token lease failed${err instanceof GuardianLeasePermanentError ? ", not retrying — a malformed 200 will not fix itself" : ` after ${maxLeaseAttempts} attempts`}: ${err}\n` +
             `   The assistant is running but guardian-token.json was not written.\n` +
             `   Run \`cadet restart ${JSON.stringify(instanceName)} --repair-guardian\` to re-lease a token.`,
         );

package/src/lib/job-polling.ts

@@ -166,7 +166,7 @@ export async function pollJobUntilDone(
         throw err;
       }
       const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`${options.label} polling failed, retrying... (${msg})`);
+      console.warn(`${options.label} polling failed: ${msg}. Retrying...`);
       if (Date.now() >= deadline) {
         throw new Error(
           `Timed out waiting for ${options.label} after ${Math.round(

package/src/lib/local.ts

@@ -937,7 +937,7 @@ async function startDaemonWatchFromSource(
   }
   writeFileSync(pidFile, String(daemonPid), "utf-8");
 
-  console.log("   Assistant started in watch mode (bun --watch)");
+  console.log("   Assistant started in watch mode with bun --watch");
   return trackDaemonSpawn(child);
 }
 

package/src/lib/nginx-ingress.ts

@@ -1162,13 +1162,13 @@ export async function ensureTunnelEdge(opts: {
     case "nginx-missing":
       throw new Error(
         "nginx is not installed, so the tunnel edge cannot start. " +
-          "Install it (macOS: `brew install nginx`, Linux: `sudo apt install nginx`) " +
+          "See https://nginx.org/en/docs/install.html for how to install, " +
           "or point NGINX_BIN at an existing binary.",
       );
     case "web-dist-missing":
       throw new Error(
         "Unable to locate built web assets for the remote web edge. " +
-          "Build the SPA (`cd clients/web && VITE_CLOUD_MODE=false bun run build`) " +
+          "Build the SPA with `cd clients/web && VITE_CLOUD_MODE=false bun run build`, " +
           "or install @mycadet/web so its packaged dist directory is available.",
       );
     case "unreachable":

package/src/lib/pair.ts

@@ -50,6 +50,6 @@ export function formatWebApproveFailure(
   return [
     `${rejection} ${gatewayUrl} (assistant "${assistantReference}", environment "${envName}").`,
     `Codes are minted by the gateway that serves the pair page, expire after ${CODE_TTL_MINUTES} minutes, and are single-use.`,
-    "If the pair page came from a different assistant or environment (e.g. the desktop app's), re-run with that environment's CADET_ENVIRONMENT and that assistant's name.",
+    "If the pair page came from a different assistant or environment, such as the desktop app's, re-run with that environment's CADET_ENVIRONMENT and that assistant's name.",
   ].join("\n");
 }

package/src/lib/sync-cloud-assistants.ts

@@ -88,7 +88,7 @@ export async function syncCloudAssistants(
     log?.("Fetching Cadet Cloud assistants…");
     cloudAssistants = await fetchCloudAssistants(token);
     log?.(
-      `Cadet Cloud returned ${cloudAssistants.length} assistant(s): ${cloudAssistants.map((a) => a.name || a.id).join(", ") || "(none)"}`,
+      `Cadet Cloud returned ${cloudAssistants.length} ${cloudAssistants.length === 1 ? "assistant" : "assistants"}: ${cloudAssistants.map((a) => a.name || a.id).join(", ") || "(none)"}`,
     );
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -118,7 +118,7 @@ export async function syncCloudAssistants(
   );
   const existingCloudIds = new Set(existingCloudById.keys());
   log?.(
-    `Lockfile has ${existingCloudIds.size} cloud assistant(s): ${[...existingCloudIds].join(", ") || "(none)"}`,
+    `Lockfile has ${existingCloudIds.size} ${existingCloudIds.size === 1 ? "cloud assistant" : "cloud assistants"}: ${[...existingCloudIds].join(", ") || "(none)"}`,
   );
 
   let added = 0;

package/src/lib/tunnels/cloudflare.ts

@@ -2,6 +2,8 @@ import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
 
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 
+import { ensureBinaryInstalled } from "../ensure-binary.js";
+
 import { GATEWAY_PORT } from "../constants.js";
 import {
   clearIngressUrl,
@@ -138,18 +140,26 @@ export interface RunCloudflareTunnelOptions {
 export async function runCloudflareTunnel(
   opts: RunCloudflareTunnelOptions = {},
 ): Promise<ProviderTunnelResult> {
-  const version = getCloudflareTunnelVersion();
+  const version = await ensureBinaryInstalled({
+    binary: "cloudflared",
+    purpose: "the cloudflare tunnel",
+    packages: {
+      brew: ["brew", "install", "cloudflare/cloudflare/cloudflared"],
+      winget: [
+        "winget",
+        "install",
+        "--silent",
+        "--accept-package-agreements",
+        "--accept-source-agreements",
+        "Cloudflare.cloudflared",
+      ],
+      choco: ["choco", "install", "-y", "cloudflared"],
+    },
+    manualHint:
+      "See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ for how to install",
+    probe: getCloudflareTunnelVersion,
+  });
   if (!version) {
-    console.error("Error: cloudflared is not installed.");
-    console.error("");
-    console.error("Install cloudflared:");
-    console.error("  macOS:   brew install cloudflare/cloudflare/cloudflared");
-    console.error("  Linux:   https://pkg.cloudflare.com/index.html");
-    console.error(
-      "  Windows: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
-    );
-    console.error("");
-    console.error("No Cloudflare account is required for quick tunnels.");
     process.exit(1);
   }