@vellumai/cli 0.10.2-dev.202606241743.799fce7 → 0.10.2-dev.202606241938.e233a07

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.2-dev.202606241743.799fce7",
+  "version": "0.10.2-dev.202606241938.e233a07",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/client-token.test.ts

@@ -84,4 +84,31 @@ describe("client --token (ephemeral)", () => {
     expect(parsed.assistantId).toBe("remote-xyz");
     expect(parsed.bearerToken).toBe("tok");
   });
+
+  test("auto-opens the browser by default", () => {
+    process.argv = [
+      "bun",
+      "vellum",
+      "client",
+      "--url",
+      REMOTE_URL,
+      "--token",
+      "tok",
+    ];
+    expect(parseArgs().openBrowser).toBe(true);
+  });
+
+  test("--no-open opts out of auto-opening the browser", () => {
+    process.argv = [
+      "bun",
+      "vellum",
+      "client",
+      "--url",
+      REMOTE_URL,
+      "--token",
+      "tok",
+      "--no-open",
+    ];
+    expect(parseArgs().openBrowser).toBe(false);
+  });
 });

package/src/commands/client.ts

@@ -60,6 +60,7 @@ import {
 import { tuiLog } from "../lib/tui-log";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import { probePort } from "../lib/port-probe.js";
+import { openBrowser } from "../lib/open-browser";
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
@@ -90,6 +91,8 @@ interface ParsedArgs {
   /** Parsed --flag overrides: kebab-case key -> typed value (for web injection). */
   parsedFlagOverrides: Record<string, boolean | string>;
   disablePlatform: boolean;
+  /** Auto-open the web interface in the default browser (--interface web only). */
+  openBrowser: boolean;
 }
 
 function readAssistantName(entry: AssistantEntry | null): string | undefined {
@@ -136,6 +139,8 @@ export function parseArgs(): ParsedArgs {
     "--token",
     "-t",
   ]);
+  // Auto-open the web interface in the browser by default; --no-open opts out.
+  let openBrowserPref = true;
   const flagArgs: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -144,6 +149,8 @@ export function parseArgs(): ParsedArgs {
       process.exit(0);
     } else if (arg === "--disable-platform") {
       disablePlatform = true;
+    } else if (arg === "--no-open") {
+      openBrowserPref = false;
     } else if (
       (arg === "--url" ||
         arg === "-u" ||
@@ -264,6 +271,7 @@ export function parseArgs(): ParsedArgs {
     flagEnvVars,
     parsedFlagOverrides,
     disablePlatform,
+    openBrowser: openBrowserPref,
   };
 }
 
@@ -283,6 +291,7 @@ ${ANSI.bold}OPTIONS:${ANSI.reset}
                               not persisted.
     -a, --assistant-id <id>    Assistant ID
     -i, --interface <id>       Interface identifier: cli (default) or web
+    --no-open                  Don't auto-open the browser (--interface web)
     --flag <key=value>         Feature flag override (repeatable, kebab-case key)
     --disable-platform         Suppress all outbound platform API calls
     -h, --help                 Show this help message
@@ -816,10 +825,26 @@ async function findFreeDualLoopbackPort(preferred: number): Promise<number> {
   return preferred;
 }
 
+/**
+ * Open `url` in the browser once `port` is accepting connections, polling for
+ * up to ~10s. Used for the Vite dev server, which binds the port asynchronously
+ * after spawn — opening immediately would load the tab before Vite is ready.
+ */
+async function openBrowserWhenReady(url: string, port: number): Promise<void> {
+  for (let attempt = 0; attempt < 50; attempt++) {
+    if (await probePort(port, "127.0.0.1")) {
+      openBrowser(url);
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+}
+
 async function runWebInterface(
   flagEnvVars: Record<string, string>,
   parsedFlagOverrides: Record<string, boolean | string>,
   disablePlatform: boolean,
+  openInBrowser: boolean,
 ): Promise<void> {
   // Propagate flag env vars so child processes (e.g. hatch from the web UI) inherit them.
   Object.assign(process.env, flagEnvVars);
@@ -828,7 +853,12 @@ async function runWebInterface(
   // (HMR, __local endpoints, gateway proxy).
   const webSourceDir = findWebSourceDir();
   if (webSourceDir) {
-    return runViteDevServer(webSourceDir, flagEnvVars, disablePlatform);
+    return runViteDevServer(
+      webSourceDir,
+      flagEnvVars,
+      disablePlatform,
+      openInBrowser,
+    );
   }
 
   const distDir = findWebDistDir();
@@ -978,7 +1008,9 @@ async function runWebInterface(
   // Advertise `localhost` (not `127.0.0.1`) so the app origin matches the host
   // the platform hardcodes in its loopback callback. We bind both loopback
   // families above so `localhost` reaches us whichever one it resolves to.
-  console.log(`Vellum web interface: http://localhost:${port}${SPA_BASE}`);
+  const webInterfaceUrl = `http://localhost:${port}${SPA_BASE}`;
+  console.log(`Vellum web interface: ${webInterfaceUrl}`);
+  if (openInBrowser) openBrowser(webInterfaceUrl);
 
   const shutdown = (): void => {
     for (const server of servers) server.stop();
@@ -994,6 +1026,7 @@ async function runViteDevServer(
   webSourceDir: string,
   flagEnvVars: Record<string, string>,
   disablePlatform: boolean,
+  openInBrowser: boolean,
 ): Promise<void> {
   const platformUrl = getPlatformUrl();
 
@@ -1027,6 +1060,12 @@ async function runViteDevServer(
     },
   });
 
+  // Vite binds the port itself, so wait until it's listening before opening the
+  // browser — otherwise the tab loads before the dev server is ready.
+  if (openInBrowser) {
+    void openBrowserWhenReady(`http://localhost:${port}${SPA_BASE}`, port);
+  }
+
   const shutdown = (): void => {
     child.kill();
     process.exit(0);
@@ -1099,6 +1138,7 @@ export async function client(): Promise<void> {
     flagEnvVars,
     parsedFlagOverrides,
     disablePlatform,
+    openBrowser: openInBrowser,
   } = parseArgs();
 
   if (disablePlatform) {
@@ -1106,7 +1146,12 @@ export async function client(): Promise<void> {
   }
 
   if (interfaceId === WEB_INTERFACE_ID) {
-    await runWebInterface(flagEnvVars, parsedFlagOverrides, disablePlatform);
+    await runWebInterface(
+      flagEnvVars,
+      parsedFlagOverrides,
+      disablePlatform,
+      openInBrowser,
+    );
     return;
   }
 

package/src/commands/login.ts

@@ -1,4 +1,3 @@
-import { spawn } from "child_process";
 import { randomBytes } from "crypto";
 import { createServer } from "http";
 import type { AddressInfo } from "net";
@@ -11,6 +10,7 @@ import {
   setActiveAssistant,
 } from "../lib/assistant-config";
 import { computeDeviceId } from "../lib/guardian-token";
+import { openBrowser } from "../lib/open-browser";
 import {
   clearPlatformToken,
   ensureSelfHostedLocalRegistration,
@@ -169,24 +169,6 @@ function renderLoginPage(
 </html>`;
 }
 
-/**
- * Open a URL in the user's default browser.
- */
-function openBrowser(url: string): void {
-  const platform = process.platform;
-  const cmd =
-    platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-  const args =
-    platform === "win32"
-      ? ["/c", "start", '""', url.replace(/&/g, "^&")]
-      : [url];
-  const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-  child.on("error", () => {
-    // Silently ignore — the user can still copy the URL from the console
-  });
-  child.unref();
-}
-
 export interface LoopbackListener {
   /** The full `http://127.0.0.1:<port>/auth/callback` redirect URI. */
   redirectUri: string;

package/src/lib/open-browser.ts

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Open a URL in the user's default browser. Best-effort: a failure to launch is
+ * swallowed so the caller can still surface the URL for the user to copy.
+ */
+export function openBrowser(url: string): void {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args =
+    platform === "win32"
+      ? ["/c", "start", '""', url.replace(/&/g, "^&")]
+      : [url];
+  const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+  child.on("error", () => {
+    // Silently ignore — the user can still copy the URL from the console.
+  });
+  child.unref();
+}