@browserbasehq/browse-cli 0.3.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Browserbase Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -173,11 +173,47 @@ browse env
 # Switch current session to Browserbase (restarts daemon if needed)
 browse env remote
 
-# Switch back to local Chrome
+# Switch back to local Chrome (auto-discovers existing Chrome, falls back to isolated)
 browse env local
 ```
 
-Behavior details:
+#### Local Browser Strategies
+
+By default, `browse env local` auto-discovers an already-running Chrome with remote
+debugging enabled. This lets agents use your existing cookies, logins, and browser state.
+If no debuggable Chrome is found, it falls back to launching an isolated browser.
+
+```bash
+# Auto-discover local Chrome, fallback to isolated (default)
+browse env local
+
+# Force a clean isolated browser (no auto-discovery)
+browse env local --isolated
+
+# Attach to a specific CDP target (port or URL)
+browse env local 9222
+browse env local ws://localhost:9222/devtools/browser/...
+```
+
+Auto-discovery checks:
+1. `DevToolsActivePort` files in well-known Chrome/Chromium/Brave user-data directories
+2. Common debugging ports (9222, 9229)
+
+To make your Chrome discoverable:
+
+1. Open `chrome://inspect/#remote-debugging`
+2. Check the box **"Allow remote debugging for this browser instance"**
+
+For more information, see the [Chrome DevTools docs](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session).
+
+Use `browse status` to see which strategy was resolved:
+
+```bash
+browse status
+# {"running":true,"session":"default","mode":"local","localStrategy":"auto","localSource":"attached-existing","resolvedCdpUrl":"ws://..."}
+```
+
+#### General Behavior
 
 - Environment is scoped per `--session`
 - `browse env <target>` persists an override and restarts the daemon
@@ -193,7 +229,7 @@ Behavior details:
 | `--session <name>` | Session name for multiple browsers (default: "default") |
 | `--headless` | Run Chrome in headless mode |
 | `--headed` | Run Chrome with visible window (default) |
-| `--ws <url>` | Connect to existing Chrome via CDP WebSocket |
+| `--ws <url\|port>` | One-shot CDP connection (bypasses daemon) |
 | `--json` | Output as JSON |
 
 ## Environment Variables
@@ -249,11 +285,21 @@ browse --session personal open https://twitter.com
 
 Connect to an existing Chrome instance:
 
+To make your Chrome discoverable:
+
+1. Open `chrome://inspect/#remote-debugging`
+2. Check the box **"Allow remote debugging for this browser instance"**
+3. Re-run the CLI and it will auto-connect!
+
+For more information, see the [Chrome DevTools docs](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session).
+
 ```bash
-# Start Chrome with remote debugging
-google-chrome --remote-debugging-port=9222
+# Auto-discover Chrome with remote debugging enabled
+browse env local
+browse open https://example.com
 
-# Connect via WebSocket
+# Or target a specific port / WebSocket URL
+browse env local 9222
 browse --ws ws://localhost:9222/devtools/browser/... open https://example.com
 ```
 

package/dist/index.js

@@ -34,9 +34,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.19.4_typescript@5.8.3_yaml@2.7.1/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_tsx@4.19.4_typescript@5.8.3_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js
 var init_cjs_shims = __esm({
-  "../../node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.19.4_typescript@5.8.3_yaml@2.7.1/node_modules/tsup/assets/cjs_shims.js"() {
+  "../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_tsx@4.19.4_typescript@5.8.3_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
   }
 });
@@ -94180,7 +94180,7 @@ var init_page2 = __esm({
           });
           try {
             if (this.apiClient) {
-              const result = await this.apiClient.goto(url2, { waitUntil: options?.waitUntil }, this.mainFrameId());
+              const result = await this.apiClient.goto(url2, { waitUntil: options?.waitUntil, timeout: options?.timeoutMs }, this.mainFrameId());
               this._currentUrl = url2;
               if (isSerializableResponse(result)) {
                 return Response2.fromSerializable(result, {
@@ -100088,6 +100088,18 @@ Return the element that matches the instruction if it exists. Otherwise, return
     content: [content, buildUserInstructionsString(userProvidedInstructions)].filter(Boolean).join("\n\n")
   };
 }
+function buildActVariablesPrompt(variables) {
+  if (!variables || Object.keys(variables).length === 0) {
+    return "";
+  }
+  const variableNames = Object.keys(variables).map((key) => `%${key}%`).join(", ");
+  return ` The user has provided the following variables to be used in the action: ${variableNames} 
+
+    Note that these are the variable names/keys, and not the actual variable values. 
+
+    To use the variables in the action, you must respond with the variable name inside the 'arguments' array. The variable name must be wrapped in percentage signs (eg, %variableNameHere%) so that it can be replaced with the actual variable value before the action is taken. 
+`;
+}
 function buildActPrompt(action, supportedActions, variables) {
   let instruction = `Find the most relevant element to perform an action on given the following action: ${action}.  
   IF AND ONLY IF the action EXPLICITLY includes the word 'dropdown' and implies choosing/selecting an option from a dropdown, ignore the 'General Instructions' section, and follow the 'Dropdown Specific Instructions' section carefully.
@@ -100114,11 +100126,7 @@ function buildActPrompt(action, supportedActions, variables) {
         - choose the 'click' method
         - set twoStep to true.
   `;
-  if (variables && Object.keys(variables).length > 0) {
-    const variableNames = Object.keys(variables).map((key) => `%${key}%`).join(", ");
-    const variablesPrompt = `The following variables are available to use in the action: ${variableNames}. Fill the argument variables with the variable name.`;
-    instruction += ` ${variablesPrompt}`;
-  }
+  instruction += buildActVariablesPrompt(variables);
   return instruction;
 }
 function buildStepTwoPrompt(originalUserAction, previousAction, supportedActions, variables) {
@@ -100136,11 +100144,7 @@ function buildStepTwoPrompt(originalUserAction, previousAction, supportedActions
   If the user is asking to scroll to the next chunk/previous chunk, choose the nextChunk/prevChunk method. No arguments are required here.
   If the action implies a key press, e.g., 'press enter', 'press a', 'press space', etc., always choose the press method with the appropriate key as argument \u2014 e.g. 'a', 'Enter', 'Space'. Do not choose a click action on an on-screen keyboard. Capitalize the first character like 'Enter', 'Tab', 'Escape' only for special keys. 
   `;
-  if (variables && Object.keys(variables).length > 0) {
-    const variableNames = Object.keys(variables).map((key) => `%${key}%`).join(", ");
-    const variablesPrompt = `The following variables are available to use in the action: ${variableNames}. Fill the argument variables with the variable name.`;
-    instruction += ` ${variablesPrompt}`;
-  }
+  instruction += buildActVariablesPrompt(variables);
   return instruction;
 }
 function buildGoogleCUASystemPrompt() {
@@ -100448,7 +100452,7 @@ async function observe({ instruction, domElements, llmClient, userProvidedInstru
 async function act({ instruction, domElements, llmClient, userProvidedInstructions, logger, logInferenceToFile = false }) {
   const isGPT5 = llmClient.modelName.includes("gpt-5");
   const actSchema = external_exports.object({
-    elementId: external_exports.string().regex(/^\d+-\d+$/).describe("the ID string associated with the element. Never include surrounding square brackets. This field must follow the format of 'number-number'."),
+    elementId: external_exports.string().regex(/^\d+-\d+$/).describe("the ID string associated with the element. Never include surrounding square brackets. This field must follow the format of 'number-number'. for example, '0-76' or '16-21'"),
     description: external_exports.string().describe("a description of the accessible element and its purpose"),
     method: external_exports.enum(
       // Use Object.values() for Zod v3 compatibility - z.enum() in v3 doesn't accept TypeScript enums directly
@@ -160612,7 +160616,9 @@ function hasInjectableDOM(url2) {
   return false;
 }
 function isNonWebTarget(info) {
-  return info.type !== "page" && info.type !== "iframe" || !hasInjectableDOM(info.url);
+  if (info.type === "page")
+    return false;
+  return info.type !== "iframe" || !hasInjectableDOM(info.url);
 }
 function isTopLevelPage(info) {
   const ti = info;
@@ -164620,7 +164626,29 @@ var import_child_process4 = require("child_process");
 var readline = __toESM(require("readline"));
 
 // package.json
-var version3 = "0.3.0";
+var version3 = "0.4.1";
+
+// src/resolve-ws.ts
+init_cjs_shims();
+async function resolveWsTarget(input) {
+  if (/^\d+$/.test(input)) {
+    const port = input;
+    const url2 = `http://127.0.0.1:${port}/json/version`;
+    try {
+      const res = await fetch(url2);
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} from ${url2}`);
+      }
+      const json2 = await res.json();
+      if (json2.webSocketDebuggerUrl) {
+        return json2.webSocketDebuggerUrl;
+      }
+    } catch {
+    }
+    return `ws://127.0.0.1:${port}/devtools/browser`;
+  }
+  return input;
+}
 
 // src/index.ts
 var program = new import_commander.Command();
@@ -164717,6 +164745,34 @@ function getContextPath(session) {
 function getConnectPath(session) {
   return path11.join(SOCKET_DIR, `browse-${session}.connect`);
 }
+function getLocalConfigPath(session) {
+  return path11.join(SOCKET_DIR, `browse-${session}.local-config`);
+}
+function getLocalInfoPath(session) {
+  return path11.join(SOCKET_DIR, `browse-${session}.local-info`);
+}
+async function readLocalConfig(session) {
+  try {
+    const raw = await import_fs11.promises.readFile(getLocalConfigPath(session), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return { strategy: "auto" };
+  }
+}
+async function writeLocalConfig(session, config3) {
+  await import_fs11.promises.writeFile(getLocalConfigPath(session), JSON.stringify(config3));
+}
+async function writeLocalInfo(session, info) {
+  await import_fs11.promises.writeFile(getLocalInfoPath(session), JSON.stringify(info));
+}
+async function readLocalInfo(session) {
+  try {
+    const raw = await import_fs11.promises.readFile(getLocalInfoPath(session), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 function hasBrowserbaseCredentials() {
   return Boolean(process.env.BROWSERBASE_API_KEY);
 }
@@ -164748,6 +164804,165 @@ async function getDesiredMode(session) {
   }
   return hasBrowserbaseCredentials() ? "browserbase" : "local";
 }
+function getChromeUserDataDirs() {
+  const home = os3.homedir();
+  const dirs = [];
+  if (process.platform === "darwin") {
+    const base = path11.join(home, "Library", "Application Support");
+    for (const name18 of [
+      "Google/Chrome",
+      "Google/Chrome Canary",
+      "Chromium",
+      "BraveSoftware/Brave-Browser"
+    ]) {
+      dirs.push(path11.join(base, name18));
+    }
+  } else if (process.platform === "linux") {
+    const config3 = path11.join(home, ".config");
+    for (const name18 of [
+      "google-chrome",
+      "google-chrome-unstable",
+      "chromium",
+      "BraveSoftware/Brave-Browser"
+    ]) {
+      dirs.push(path11.join(config3, name18));
+    }
+  }
+  return dirs;
+}
+async function readDevToolsActivePort(userDataDir) {
+  try {
+    const content = await import_fs11.promises.readFile(
+      path11.join(userDataDir, "DevToolsActivePort"),
+      "utf-8"
+    );
+    const lines = content.trim().split("\n");
+    const port = parseInt(lines[0]?.trim(), 10);
+    if (isNaN(port) || port <= 0 || port > 65535) return null;
+    const wsPath = lines[1]?.trim() || "/devtools/browser";
+    return { port, wsPath };
+  } catch {
+    return null;
+  }
+}
+function isPortReachable(port, timeoutMs = 500) {
+  return new Promise((resolve4) => {
+    const sock = net2.createConnection({ host: "127.0.0.1", port });
+    const timer = setTimeout(() => {
+      sock.destroy();
+      resolve4(false);
+    }, timeoutMs);
+    sock.on("connect", () => {
+      clearTimeout(timer);
+      sock.destroy();
+      resolve4(true);
+    });
+    sock.on("error", () => {
+      clearTimeout(timer);
+      resolve4(false);
+    });
+  });
+}
+async function probeCdpEndpoint(port) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2e3);
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    if (res.ok) {
+      const json2 = await res.json();
+      if (json2.webSocketDebuggerUrl) {
+        return json2.webSocketDebuggerUrl;
+      }
+    }
+  } catch {
+  }
+  const wsUrl = `ws://127.0.0.1:${port}/devtools/browser`;
+  try {
+    const verified = await verifyCdpWebSocket(wsUrl);
+    if (verified) return wsUrl;
+  } catch {
+  }
+  return null;
+}
+function verifyCdpWebSocket(wsUrl) {
+  return new Promise((resolve4) => {
+    const url2 = new URL(wsUrl);
+    const port = parseInt(url2.port) || 80;
+    const wsKey = Buffer.from(
+      Array.from({ length: 16 }, () => Math.floor(Math.random() * 256))
+    ).toString("base64");
+    const sock = net2.createConnection({ host: url2.hostname, port });
+    let response = "";
+    const timer = setTimeout(() => {
+      sock.destroy();
+      resolve4(false);
+    }, 2e3);
+    sock.on("connect", () => {
+      sock.write(
+        `GET ${url2.pathname} HTTP/1.1\r
+Host: ${url2.hostname}:${port}\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Key: ${wsKey}\r
+Sec-WebSocket-Version: 13\r
+\r
+`
+      );
+    });
+    sock.on("data", (data) => {
+      response += data.toString();
+      if (/^HTTP\/1\.[01] 101(?:\s|$)/.test(response)) {
+        clearTimeout(timer);
+        sock.destroy();
+        resolve4(true);
+      } else if (response.includes("\r\n\r\n")) {
+        clearTimeout(timer);
+        sock.destroy();
+        resolve4(false);
+      }
+    });
+    sock.on("error", () => {
+      clearTimeout(timer);
+      resolve4(false);
+    });
+  });
+}
+async function discoverLocalCdp() {
+  const candidates = [];
+  const userDataDirs = getChromeUserDataDirs();
+  for (const dir of userDataDirs) {
+    const info = await readDevToolsActivePort(dir);
+    if (!info) continue;
+    if (!await isPortReachable(info.port)) {
+      try {
+        await import_fs11.promises.unlink(path11.join(dir, "DevToolsActivePort"));
+      } catch {
+      }
+      continue;
+    }
+    const wsUrl = await probeCdpEndpoint(info.port);
+    if (wsUrl) {
+      const name18 = path11.basename(dir);
+      candidates.push({ wsUrl, source: `DevToolsActivePort (${name18})` });
+    }
+  }
+  if (candidates.length === 0) {
+    for (const port of [9222, 9229]) {
+      if (!await isPortReachable(port)) continue;
+      const wsUrl = await probeCdpEndpoint(port);
+      if (wsUrl) {
+        candidates.push({ wsUrl, source: `port ${port}` });
+      }
+    }
+  }
+  if (candidates.length > 1) {
+    return null;
+  }
+  return candidates[0] ?? null;
+}
 async function isDaemonRunning(session) {
   try {
     const pidFile = getPidPath(session);
@@ -164766,14 +164981,16 @@ var DAEMON_STATE_FILES = (session) => [
   getWsPath(session),
   getChromePidPath(session),
   getLockPath(session),
-  getModePath(session)
+  getModePath(session),
+  getLocalInfoPath(session)
 ];
 async function cleanupStaleFiles(session) {
   const files = [
     ...DAEMON_STATE_FILES(session),
     // Client-written config, only cleaned on full shutdown
     getContextPath(session),
-    getConnectPath(session)
+    getConnectPath(session),
+    getLocalConfigPath(session)
   ];
   for (const file2 of files) {
     try {
@@ -164850,6 +165067,37 @@ async function runDaemon(session, headless) {
         connectSessionId = (await import_fs11.promises.readFile(getConnectPath(session), "utf-8")).trim();
       } catch {
       }
+      let localLaunchOptions;
+      let localInfo;
+      if (!useBrowserbase) {
+        const localConfig = await readLocalConfig(session);
+        if (localConfig.strategy === "isolated") {
+          localLaunchOptions = { headless, viewport: DEFAULT_VIEWPORT2 };
+          localInfo = { localSource: "isolated" };
+        } else if (localConfig.strategy === "cdp") {
+          const cdpUrl = await resolveWsTarget(localConfig.cdpTarget);
+          localLaunchOptions = { cdpUrl };
+          localInfo = {
+            localSource: "attached-explicit",
+            resolvedCdpUrl: cdpUrl
+          };
+        } else {
+          const discovered = await discoverLocalCdp();
+          if (discovered) {
+            localLaunchOptions = { cdpUrl: discovered.wsUrl };
+            localInfo = {
+              localSource: "attached-existing",
+              resolvedCdpUrl: discovered.wsUrl
+            };
+          } else {
+            localLaunchOptions = { headless, viewport: DEFAULT_VIEWPORT2 };
+            localInfo = {
+              localSource: "isolated-fallback",
+              fallbackReason: "no debuggable local browser found"
+            };
+          }
+        }
+      }
       stagehand = new V3({
         env: useBrowserbase ? "BROWSERBASE" : "LOCAL",
         verbose: 0,
@@ -164862,7 +165110,7 @@ async function runDaemon(session, headless) {
           } : {},
           ...!connectSessionId ? {
             browserbaseSessionCreateParams: {
-              userMetadata: { "browse-cli": "true" },
+              userMetadata: { browse_cli: "true" },
               ...contextConfig ? {
                 browserSettings: {
                   context: contextConfig
@@ -164871,13 +165119,13 @@ async function runDaemon(session, headless) {
             }
           } : {}
         } : {
-          localBrowserLaunchOptions: {
-            headless,
-            viewport: DEFAULT_VIEWPORT2
-          }
+          localBrowserLaunchOptions: localLaunchOptions
         }
       });
       await import_fs11.promises.writeFile(getModePath(session), desiredMode);
+      if (localInfo) {
+        await writeLocalInfo(session, localInfo);
+      }
       await stagehand.init();
       context = stagehand.context;
       context.conn.onTransportClosed(() => {
@@ -164935,7 +165183,7 @@ async function runDaemon(session, headless) {
       }
     } catch {
     }
-    await cleanupStaleFiles(session);
+    await cleanupDaemonStateFiles(session);
     process.exit(0);
   };
   process.on("SIGTERM", () => shutdown());
@@ -165602,7 +165850,7 @@ async function stopDaemonAndCleanup(session) {
   } catch {
   }
   await new Promise((r3) => setTimeout(r3, 500));
-  await cleanupStaleFiles(session);
+  await cleanupDaemonStateFiles(session);
 }
 async function ensureDaemon(session, headless) {
   const wantMode = await getDesiredMode(session);
@@ -165689,12 +165937,13 @@ async function runCommand(command, args) {
   const session = getSession(opts);
   const headless = isHeadless(opts);
   if (opts.ws) {
+    const cdpUrl = await resolveWsTarget(opts.ws);
     const stagehand = new V3({
       env: "LOCAL",
       verbose: 0,
       disablePino: true,
       localBrowserLaunchOptions: {
-        cdpUrl: opts.ws
+        cdpUrl
       }
     });
     await stagehand.init();
@@ -165732,8 +165981,8 @@ async function runCommand(command, args) {
   return sendCommand(session, command, args, headless);
 }
 program.name("browse").description("Browser automation CLI for AI agents").version(version3).option(
-  "--ws <url>",
-  "CDP WebSocket URL (bypasses daemon, direct connection)"
+  "--ws <url|port>",
+  "CDP WebSocket URL or port number (bypasses daemon, direct connection)"
 ).option("--headless", "Run Chrome in headless mode").option("--headed", "Run Chrome with visible window (default)").option("--json", "Output as JSON", false).option(
   "--session <name>",
   "Session name for multiple browsers (or use BROWSE_SESSION env var)"
@@ -165778,6 +166027,7 @@ program.command("status").description("Check daemon status").action(async () =>
   let wsUrl = null;
   let mode = null;
   let browserbaseSessionId = null;
+  let localDetails = {};
   if (running) {
     try {
       wsUrl = await import_fs11.promises.readFile(getWsPath(session), "utf-8");
@@ -165788,68 +166038,106 @@ program.command("status").description("Check daemon status").action(async () =>
       browserbaseSessionId = (await import_fs11.promises.readFile(getConnectPath(session), "utf-8")).trim();
     } catch {
     }
+    if (mode === "local") {
+      const localConfig = await readLocalConfig(session);
+      const localInfo = await readLocalInfo(session);
+      localDetails = {
+        localStrategy: localConfig.strategy,
+        ...localInfo ?? {}
+      };
+    }
   }
   console.log(
-    JSON.stringify({ running, session, wsUrl, mode, browserbaseSessionId })
+    JSON.stringify({
+      running,
+      session,
+      wsUrl,
+      mode,
+      browserbaseSessionId,
+      ...localDetails
+    })
   );
 });
-program.command("env [target]").description("Show or switch browser environment (local | remote)").action(async (target) => {
-  const opts = program.opts();
-  const session = getSession(opts);
-  if (!target) {
-    let mode = null;
-    const desiredMode = await getDesiredMode(session);
-    if (await isDaemonRunning(session)) {
-      mode = toModeTarget(await readCurrentMode(session) ?? desiredMode);
-    }
-    console.log(
-      JSON.stringify({
-        mode: mode ?? "not running",
-        desired: toModeTarget(desiredMode),
-        session
-      })
-    );
-    return;
-  }
-  const modeMap = {
-    local: "local",
-    remote: "browserbase"
-  };
-  const mapped = modeMap[target];
-  if (!mapped) {
-    console.error("Usage: browse env [local|remote]");
-    process.exit(1);
-  }
-  try {
-    assertModeSupported(mapped);
-  } catch (err) {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-  }
-  await import_fs11.promises.writeFile(getModeOverridePath(session), mapped);
-  if (await isDaemonRunning(session)) {
-    const currentMode = await readCurrentMode(session) ?? "local";
-    if (currentMode === mapped) {
+program.command("env [target] [cdpTarget]").description(
+  "Show or switch browser environment (local | remote)\n\n  browse env              Show current environment\n  browse env local        Auto-discover local Chrome, fallback to isolated\n  browse env local --isolated  Force clean isolated browser\n  browse env local <port|url>  Attach to specific CDP target\n  browse env remote       Use Browserbase (requires API key)"
+).option("--isolated", "Force isolated local browser (no auto-discovery)").action(
+  async (target, cdpTarget, cmdOpts) => {
+    const opts = program.opts();
+    const session = getSession(opts);
+    if (!target) {
+      let mode = null;
+      const desiredMode = await getDesiredMode(session);
+      const localConfig2 = await readLocalConfig(session);
+      const localInfo = await readLocalInfo(session);
+      if (await isDaemonRunning(session)) {
+        mode = toModeTarget(await readCurrentMode(session) ?? desiredMode);
+      }
       console.log(
         JSON.stringify({
-          mode: toModeTarget(mapped),
+          mode: mode ?? "not running",
+          desired: toModeTarget(desiredMode),
           session,
-          restarted: false
+          ...desiredMode === "local" ? {
+            localStrategy: localConfig2.strategy,
+            ...localInfo ?? {}
+          } : {}
         })
       );
       return;
     }
-    await stopDaemonAndCleanup(session);
+    const modeMap = {
+      local: "local",
+      remote: "browserbase"
+    };
+    const mapped = modeMap[target];
+    if (!mapped) {
+      console.error(
+        "Usage: browse env [local|remote]\n  browse env local [--isolated] [<port|url>]"
+      );
+      process.exit(1);
+    }
+    try {
+      assertModeSupported(mapped);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+    let localConfig = { strategy: "auto" };
+    if (mapped === "local") {
+      if (cmdOpts.isolated) {
+        localConfig = { strategy: "isolated" };
+      } else if (cdpTarget) {
+        localConfig = { strategy: "cdp", cdpTarget };
+      }
+      await writeLocalConfig(session, localConfig);
+    }
+    await import_fs11.promises.writeFile(getModeOverridePath(session), mapped);
+    if (await isDaemonRunning(session)) {
+      const currentMode = await readCurrentMode(session) ?? "local";
+      const needsRestart = currentMode !== mapped || mapped === "local";
+      if (!needsRestart) {
+        console.log(
+          JSON.stringify({
+            mode: toModeTarget(mapped),
+            session,
+            restarted: false
+          })
+        );
+        return;
+      }
+      await stopDaemonAndCleanup(session);
+    }
+    await ensureDaemon(session, isHeadless(opts));
+    console.log(
+      JSON.stringify({
+        mode: toModeTarget(mapped),
+        session,
+        restarted: true,
+        ...mapped === "local" ? { localStrategy: localConfig.strategy } : {}
+      })
+    );
   }
-  await ensureDaemon(session, isHeadless(opts));
-  console.log(
-    JSON.stringify({
-      mode: toModeTarget(mapped),
-      session,
-      restarted: true
-    })
-  );
-});
+);
 program.command("refs").description("Show cached ref map from last snapshot").action(async () => {
   const opts = program.opts();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/browse-cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Browser automation CLI for AI agents, built on Stagehand",
   "type": "commonjs",
   "license": "MIT",
@@ -41,25 +41,13 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsx src/index.ts",
-    "browse": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "eslint": "eslint .",
-    "lint": "cd ../.. && prettier --check packages/cli && cd packages/cli && pnpm run eslint && pnpm run typecheck",
-    "test": "vitest run",
-    "test:cli": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
-    "@browserbasehq/stagehand": "workspace:*",
     "commander": "^12.0.0",
     "dotenv": "^16.4.5",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "@browserbasehq/stagehand": "3.2.1-alpha-ad055f91530a84bd5d0735f7d5be82912580914b"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",
@@ -69,5 +57,16 @@
     "tsx": "^4.10.5",
     "typescript": "5.8.3",
     "vitest": "^4.0.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "browse": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "eslint": "eslint .",
+    "lint": "cd ../.. && prettier --check packages/cli && cd packages/cli && pnpm run eslint && pnpm run typecheck",
+    "test": "vitest run",
+    "test:cli": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}