@vellumai/cli 0.10.11-dev.202607220140.207f77d → 0.10.11-dev.202607220509.38c4eff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607220140.207f77d",
+  "version": "0.10.11-dev.202607220509.38c4eff",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -34,6 +34,7 @@
     "chalk": "5.6.2",
     "ink": "6.8.0",
     "nanoid": "5.1.7",
+    "qrcode-terminal": "0.12.0",
     "react": "19.2.4"
   },
   "bundledDependencies": [
@@ -42,6 +43,7 @@
   ],
   "devDependencies": {
     "@types/bun": "1.3.11",
+    "@types/qrcode-terminal": "0.12.2",
     "@types/react": "19.2.14",
     "eslint": "10.1.0",
     "knip": "5.88.1",

package/src/__tests__/pair.test.ts

@@ -467,4 +467,337 @@ describe("pair command", () => {
       expiresAt: "2026-06-04T00:10:00.000Z",
     });
   });
+
+  test("--qr mints a challenge, auto-approves it, and emits a device-code link", async () => {
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-challenge`) {
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri: "https://pair.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-verification`) {
+        return new Response(
+          JSON.stringify({
+            status: "approved",
+            verificationUri: "https://pair.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "https://pair.example.ts.net",
+      "--json",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Flag check → create challenge → approve it, all over loopback. The
+    // approval is the whole point: running the CLI on the host IS the approval,
+    // so the scan alone completes pairing.
+    expect(calls.map((c) => c[0])).toEqual([
+      `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`,
+      `${LOCAL_URL}/v1/remote-web/pairing-challenge`,
+      `${LOCAL_URL}/v1/remote-web/pairing-verification`,
+    ]);
+    expect(JSON.parse(calls[1][1]?.body as string)).toEqual({
+      publicBaseUrl: "https://pair.example.ts.net",
+    });
+    expect(JSON.parse(calls[2][1]?.body as string)).toEqual({
+      userCode: "ABCD-EFGH",
+    });
+
+    const out = JSON.parse(logs.join("\n"));
+    expect(out).toEqual({
+      pairUrl:
+        "https://pair.example.ts.net/assistant/pair#device_code=device-code",
+      deviceCode: "device-code",
+      expiresAt: "2026-06-04T00:10:00.000Z",
+      expiresInSeconds: 600,
+    });
+    // The device code rides the fragment only — never the path or query.
+    const parsed = new URL(out.pairUrl);
+    expect(parsed.search).toBe("");
+    expect(parsed.hash).toBe("#device_code=device-code");
+  });
+
+  test("--qr renders a QR and prints the fallback URL and expiry", async () => {
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string) => {
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-challenge`) {
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri: "https://pair.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response(
+        JSON.stringify({
+          status: "approved",
+          verificationUri: "https://pair.example.ts.net/assistant/pair",
+          expiresAt: "2026-06-04T00:10:00.000Z",
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "https://pair.example.ts.net",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    const output = logs.join("\n");
+    expect(output).toContain(
+      "https://pair.example.ts.net/assistant/pair#device_code=device-code",
+    );
+    expect(output).toContain("Expires: 2026-06-04T00:10:00.000Z");
+  });
+
+  test("--qr refuses a non-https --url without minting", async () => {
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "http://pair.example.com",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Validation is local and fails fast — no challenge minted for a dead link.
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("https");
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("--qr refuses a loopback --url without minting", async () => {
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "http://127.0.0.1:7830",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("loopback");
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("--qr refuses an unparseable --url with an accurate error, not a non-https mislabel", async () => {
+    let fetchCalled = false;
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = ["bun", "vellum", "pair", "--qr", "--url", "not-a-url"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Unparseable input reports its own reason — not the loopback/non-https
+    // messages the reason-blind version reconstructed.
+    expect(exited).toBe(true);
+    const joined = errors.join("\n");
+    expect(joined).toContain("isn't a valid URL");
+    expect(joined).not.toContain("is not https");
+    expect(joined).not.toContain("loopback");
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("--qr refuses when the web remote ingress feature flag is off", async () => {
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      return new Response(
+        JSON.stringify({
+          flags: [{ key: "web-remote-ingress", enabled: false }],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "https://pair.example.ts.net",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    // Only the flag check runs; no challenge is minted when the flag is off.
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("web-remote-ingress");
+    expect(calls).toHaveLength(1);
+    expect(calls[0][0]).toBe(
+      `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`,
+    );
+  });
 });

package/src/commands/pair.ts

@@ -11,6 +11,9 @@
  */
 
 import { nanoid } from "nanoid";
+// Call `qrcodeTerminal.generate` as a method — the library reads its default
+// error-correction level off `this`, so a destructured import renders nothing.
+import qrcodeTerminal from "qrcode-terminal";
 
 import { extractFlag } from "../lib/arg-utils.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
@@ -31,15 +34,10 @@ import {
   WEB_REMOTE_INGRESS_FLAG,
 } from "../lib/feature-flags.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
-import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { isLoopbackUrl, loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
-function isLoopbackHost(url: string): boolean {
-  try {
-    const host = new URL(url).hostname.toLowerCase();
-    return host === "localhost" || host === "::1" || host.startsWith("127.");
-  } catch {
-    return false;
-  }
+function assistantDisplayName(entry: AssistantEntry): string {
+  return entry.name || entry.assistantName || entry.assistantId;
 }
 
 function printUsage(): void {
@@ -58,7 +56,13 @@ OPTIONS:
     --web            Create a browser pairing URL for remote web access
     --web-approve <code>
                     Approve a browser pairing code shown by /assistant/pair
-    --json           Output the raw bundle as JSON
+    --qr             Render a QR code that pairs a device in one scan. Mints a
+                    remote-web pairing challenge and approves it locally, so the
+                    scan alone completes pairing. Needs a public https URL
+                    (--url, else the assistant's runtime URL); refuses
+                    loopback or non-https URLs.
+    --json           Output the result as JSON. With --qr: {pairUrl, deviceCode,
+                    expiresAt, expiresInSeconds}
 
 EXAMPLES:
     vellum pair
@@ -66,7 +70,8 @@ EXAMPLES:
     vellum pair --url https://abc123.ngrok.app
     vellum pair --web --url https://abc123.ngrok.app
     vellum pair --web-approve ABCD-EFGH
-    vellum pair --json
+    vellum pair --qr --url https://your-assistant.ts.net
+    vellum pair --qr --json
 `);
 }
 
@@ -119,6 +124,107 @@ function buildRemoteWebPairingUrl(
   return url.toString();
 }
 
+type QrPublicBaseUrlFailureReason = "unparseable" | "loopback" | "non-https";
+
+type QrPublicBaseUrlResult =
+  | { ok: true; url: string }
+  | { ok: false; reason: QrPublicBaseUrlFailureReason };
+
+/**
+ * Normalize the advertised URL to the public https origin a scanning phone can
+ * open, or report why it isn't internet-reachable. Stricter than the copy-paste
+ * bundle path's loopback guard: a QR that encodes a loopback or plain-http link
+ * is unusable from another device, so both are refused. The failure reason is
+ * returned so the caller can emit an accurate message per case.
+ */
+function resolveQrPublicBaseUrl(advertisedUrl: string): QrPublicBaseUrlResult {
+  let normalized: string;
+  try {
+    normalized = normalizePublicBaseUrl(advertisedUrl);
+  } catch {
+    return { ok: false, reason: "unparseable" };
+  }
+  if (isLoopbackUrl(normalized)) {
+    return { ok: false, reason: "loopback" };
+  }
+  if (new URL(normalized).protocol !== "https:") {
+    return { ok: false, reason: "non-https" };
+  }
+  return { ok: true, url: normalized };
+}
+
+/**
+ * POST a JSON body to a loopback gateway route, exiting with a clear message
+ * when the gateway is unreachable or answers non-2xx. Every pairing subcommand
+ * talks to the gateway this way, so the reachability + HTTP-error handling has
+ * a single home.
+ */
+async function gatewayPostOrExit(
+  gatewayUrl: string,
+  path: string,
+  body: unknown,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  let response: Response;
+  try {
+    response = await loopbackSafeFetch(`${gatewayUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    console.error(
+      `Error: could not reach the gateway at ${gatewayUrl} ` +
+        `(${err instanceof Error ? err.message : String(err)}).`,
+    );
+    console.error("Is the assistant running? Try `vellum wake`.");
+    process.exit(1);
+  }
+
+  if (!response.ok) {
+    const errorBody = await response.text().catch(() => "");
+    console.error(
+      `Error: HTTP ${response.status}: ${errorBody || response.statusText}`,
+    );
+    process.exit(1);
+  }
+
+  return response;
+}
+
+/**
+ * Create a remote-web pairing challenge (RFC 8628 device-code flow). Shared by
+ * `--web` and `--qr`, which differ only in how they present the same result.
+ */
+async function createRemoteWebPairingChallenge(
+  gatewayUrl: string,
+  publicBaseUrl: string,
+): Promise<RemoteWebPairingChallengeResponse> {
+  const response = await gatewayPostOrExit(
+    gatewayUrl,
+    "/v1/remote-web/pairing-challenge",
+    { publicBaseUrl },
+  );
+  return (await response.json()) as RemoteWebPairingChallengeResponse;
+}
+
+/**
+ * Approve a pending pairing challenge by its user code — the local-presence
+ * proof for the device-code flow. Shared by `--web-approve` and `--qr` (which
+ * approves the challenge it just minted so one scan completes pairing).
+ */
+async function approveRemoteWebPairing(
+  gatewayUrl: string,
+  userCode: string,
+): Promise<RemoteWebPairingApprovalResponse> {
+  const response = await gatewayPostOrExit(
+    gatewayUrl,
+    "/v1/remote-web/pairing-verification",
+    { userCode },
+  );
+  return (await response.json()) as RemoteWebPairingApprovalResponse;
+}
+
 async function assertWebRemoteIngressEnabled(
   assistantId: string,
   runtimeUrl: string,
@@ -158,7 +264,10 @@ export async function pair(): Promise<void> {
   const jsonOutput = rawArgs.includes("--json");
   const webPairing = rawArgs.includes("--web");
   const webApproval = rawArgs.includes("--web-approve");
-  let args = rawArgs.filter((a) => a !== "--json" && a !== "--web");
+  const qrPairing = rawArgs.includes("--qr");
+  let args = rawArgs.filter(
+    (a) => a !== "--json" && a !== "--web" && a !== "--qr",
+  );
 
   const [label, afterLabel] = extractFlag(args, "--label");
   const [webApproveCode, afterWebApprove] = extractFlag(
@@ -176,6 +285,10 @@ export async function pair(): Promise<void> {
     console.error("Error: --web-approve requires a pairing code.");
     process.exit(1);
   }
+  if (qrPairing && (webPairing || webApproveCode)) {
+    console.error("Error: --qr can't be combined with --web or --web-approve.");
+    process.exit(1);
+  }
 
   // Resolve the target. An explicit argument is matched by display name OR id
   // (with the standard ambiguity error); no argument falls back to the active
@@ -216,7 +329,12 @@ export async function pair(): Promise<void> {
   // so without an explicit --url the bundle would point the other machine at
   // its own localhost. Refuse to advertise a loopback URL unless the user
   // explicitly passed one. (An explicit --url is trusted as-is.)
-  if (!urlOverride && !webApproveCode && isLoopbackHost(advertisedUrl)) {
+  if (
+    !urlOverride &&
+    !webApproveCode &&
+    !qrPairing &&
+    isLoopbackUrl(advertisedUrl)
+  ) {
     const lan = getLocalLanIPv4();
     // Use THIS assistant's gateway port (not the global default) — second
     // local instances listen on a different port.
@@ -242,34 +360,7 @@ export async function pair(): Promise<void> {
   if (webApproveCode) {
     await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
 
-    let response: Response;
-    try {
-      response = await loopbackSafeFetch(
-        `${mintUrl}/v1/remote-web/pairing-verification`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ userCode: webApproveCode }),
-        },
-      );
-    } catch (err) {
-      console.error(
-        `Error: could not reach the gateway at ${mintUrl} ` +
-          `(${err instanceof Error ? err.message : String(err)}).`,
-      );
-      console.error("Is the assistant running? Try `vellum wake`.");
-      process.exit(1);
-    }
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      console.error(
-        `Error: HTTP ${response.status}: ${body || response.statusText}`,
-      );
-      process.exit(1);
-    }
-
-    const result = (await response.json()) as RemoteWebPairingApprovalResponse;
+    const result = await approveRemoteWebPairing(mintUrl, webApproveCode);
     if (jsonOutput) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -290,35 +381,10 @@ export async function pair(): Promise<void> {
       process.exit(1);
     }
 
-    let response: Response;
-    try {
-      response = await loopbackSafeFetch(
-        `${mintUrl}/v1/remote-web/pairing-challenge`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ publicBaseUrl }),
-        },
-      );
-    } catch (err) {
-      console.error(
-        `Error: could not reach the gateway at ${mintUrl} ` +
-          `(${err instanceof Error ? err.message : String(err)}).`,
-      );
-      console.error("Is the assistant running? Try `vellum wake`.");
-      process.exit(1);
-    }
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      console.error(
-        `Error: HTTP ${response.status}: ${body || response.statusText}`,
-      );
-      process.exit(1);
-    }
-
-    const challenge =
-      (await response.json()) as RemoteWebPairingChallengeResponse;
+    const challenge = await createRemoteWebPairingChallenge(
+      mintUrl,
+      publicBaseUrl,
+    );
     const pairUrl = buildRemoteWebPairingUrl(challenge);
 
     if (jsonOutput) {
@@ -338,7 +404,7 @@ export async function pair(): Promise<void> {
       return;
     }
 
-    const displayName = entry.name || entry.assistantName || entry.assistantId;
+    const displayName = assistantDisplayName(entry);
     console.log(`Created remote web pairing for ${displayName}.`);
     console.log("");
     console.log("Open this URL in the browser:");
@@ -359,36 +425,78 @@ export async function pair(): Promise<void> {
     return;
   }
 
-  // Fresh per-pairing device identity — each `vellum pair` is independently
-  // revocable.
-  const deviceId = nanoid();
+  if (qrPairing) {
+    // Validate the public URL before any network call — a QR that encodes a
+    // loopback or plain-http link is unscannable from another device.
+    const qrResult = resolveQrPublicBaseUrl(advertisedUrl);
+    if (!qrResult.ok) {
+      const detailByReason: Record<QrPublicBaseUrlFailureReason, string> = {
+        unparseable: `${advertisedUrl} isn't a valid URL`,
+        loopback: `${advertisedUrl} is a loopback address`,
+        "non-https": `${advertisedUrl} is not https`,
+      };
+      console.error(
+        "Error: --qr needs a public https URL the phone can open — " +
+          `${detailByReason[qrResult.reason]}.`,
+      );
+      console.error(
+        "Re-run with your assistant's public URL, e.g.:\n" +
+          "  vellum pair --qr --url https://your-assistant.ts.net",
+      );
+      process.exit(1);
+    }
+    const qrBaseUrl = qrResult.url;
 
-  let response: Response;
-  try {
-    response = await loopbackSafeFetch(`${mintUrl}/v1/pair`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...getClientRegistrationHeaders(CLI_INTERFACE_ID),
-      },
-      body: JSON.stringify({ deviceId, platform: "cli" }),
+    await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
+
+    // Mint a challenge and immediately approve it: running this CLI on the host
+    // IS the local-presence proof, so the scanning device completes pairing in
+    // one step. Reuses the `--web` + `--web-approve` code paths.
+    const challenge = await createRemoteWebPairingChallenge(mintUrl, qrBaseUrl);
+    await approveRemoteWebPairing(mintUrl, challenge.userCode);
+    const pairUrl = buildRemoteWebPairingUrl(challenge);
+
+    if (jsonOutput) {
+      console.log(
+        JSON.stringify(
+          {
+            pairUrl,
+            deviceCode: challenge.deviceCode,
+            expiresAt: challenge.expiresAt,
+            expiresInSeconds: challenge.expiresInSeconds,
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    const displayName = assistantDisplayName(entry);
+    console.log(`Scan to pair a device with ${displayName}:`);
+    console.log("");
+    qrcodeTerminal.generate(pairUrl, { small: true }, (qr) => {
+      console.log(qr);
     });
-  } catch (err) {
-    console.error(
-      `Error: could not reach the gateway at ${mintUrl} ` +
-        `(${err instanceof Error ? err.message : String(err)}).`,
-    );
-    console.error("Is the assistant running? Try `vellum wake`.");
-    process.exit(1);
+    console.log("");
+    console.log("Or open this URL on the device:");
+    console.log("");
+    console.log(`  ${pairUrl}`);
+    console.log("");
+    console.log(`Expires: ${challenge.expiresAt}`);
+    return;
   }
 
-  if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    console.error(
-      `Error: HTTP ${response.status}: ${body || response.statusText}`,
-    );
-    process.exit(1);
-  }
+  // Fresh per-pairing device identity — each `vellum pair` is independently
+  // revocable.
+  const deviceId = nanoid();
+
+  const response = await gatewayPostOrExit(
+    mintUrl,
+    "/v1/pair",
+    { deviceId, platform: "cli" },
+    getClientRegistrationHeaders(CLI_INTERFACE_ID),
+  );
 
   const result = (await response.json()) as PairResponse;
 
@@ -419,7 +527,7 @@ export async function pair(): Promise<void> {
     return;
   }
 
-  const displayName = entry.name || entry.assistantName || entry.assistantId;
+  const displayName = assistantDisplayName(entry);
   console.log(`Paired ${label ? `"${label}" ` : ""}with ${displayName}.`);
   console.log("");
   console.log(`  Gateway:   ${advertisedUrl}`);

package/src/lib/loopback-fetch.ts

@@ -6,7 +6,7 @@
  * connection per request; remote hosts are unaffected.
  */
 
-function isLoopbackUrl(url: string): boolean {
+export function isLoopbackUrl(url: string): boolean {
   try {
     // WHATWG URL canonicalizes hostnames, so IPv6 loopback is always "[::1]".
     const h = new URL(url).hostname;