@browserbasehq/browse-cli 0.4.2 → 0.5.0

package/README.md

@@ -173,22 +173,23 @@ browse env
 # Switch current session to Browserbase (restarts daemon if needed)
 browse env remote
 
-# Switch back to local Chrome (auto-discovers existing Chrome, falls back to isolated)
+# Switch back to local Chrome (clean isolated browser by default)
 browse env local
 ```
 
 #### 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.
+By default, `browse env local` launches a clean isolated local browser.
+Use `browse env local --auto-connect` to opt into reusing an already-running
+Chrome with remote debugging enabled. If no debuggable Chrome is found, it
+falls back to launching an isolated browser.
 
 ```bash
-# Auto-discover local Chrome, fallback to isolated (default)
+# Use a clean isolated browser (default)
 browse env local
 
-# Force a clean isolated browser (no auto-discovery)
-browse env local --isolated
+# Auto-discover local Chrome, fallback to isolated
+browse env local --auto-connect
 
 # Attach to a specific CDP target (port or URL)
 browse env local 9222
@@ -210,7 +211,7 @@ 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://..."}
+# {"running":true,"session":"default","mode":"local","localStrategy":"isolated","localSource":"isolated"}
 ```
 
 #### General Behavior
@@ -283,19 +284,19 @@ browse --session personal open https://twitter.com
 
 ## Direct CDP Connection
 
-Connect to an existing Chrome instance:
+Opt into using 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!
+3. Re-run the CLI with auto-connect enabled.
 
 For more information, see the [Chrome DevTools docs](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session).
 
 ```bash
 # Auto-discover Chrome with remote debugging enabled
-browse env local
+browse env local --auto-connect
 browse open https://example.com
 
 # Or target a specific port / WebSocket URL

package/dist/index.js

@@ -164652,7 +164652,72 @@ var import_child_process4 = require("child_process");
 var readline = __toESM(require("readline"));
 
 // package.json
-var version3 = "0.4.2";
+var version3 = "0.5.0";
+
+// src/local-strategy.ts
+init_cjs_shims();
+var DEFAULT_LOCAL_CONFIG = { strategy: "isolated" };
+var ISOLATED_MODE_HINT = "Hint: Run `browse env local --auto-connect` to reuse your local browsing credentials and cookies.";
+var ATTACHED_EXISTING_HINT = "Hint: Run `browse env local` without `--auto-connect` to switch back to an isolated Chromium browser.";
+function getLocalModeHint(localConfig, localInfo) {
+  if (localInfo?.localSource === "attached-existing") {
+    return ATTACHED_EXISTING_HINT;
+  }
+  if (localInfo?.localSource === "isolated-fallback") {
+    return null;
+  }
+  if (localConfig.strategy === "auto" && !localInfo) {
+    return ATTACHED_EXISTING_HINT;
+  }
+  if (localInfo?.localSource === "isolated" || localConfig.strategy === "isolated" && !localInfo) {
+    return ISOLATED_MODE_HINT;
+  }
+  return null;
+}
+async function resolveLocalStrategy({
+  localConfig,
+  headless,
+  defaultViewport,
+  discoverLocalCdp: discoverLocalCdp2,
+  resolveWsTarget: resolveWsTarget2
+}) {
+  if (localConfig.strategy === "isolated") {
+    return {
+      localLaunchOptions: { headless, viewport: defaultViewport },
+      localInfo: { localSource: "isolated" }
+    };
+  }
+  if (localConfig.strategy === "cdp") {
+    if (!localConfig.cdpTarget) {
+      throw new Error("Local CDP strategy requires a cdpTarget");
+    }
+    const cdpUrl = await resolveWsTarget2(localConfig.cdpTarget);
+    return {
+      localLaunchOptions: { cdpUrl },
+      localInfo: {
+        localSource: "attached-explicit",
+        resolvedCdpUrl: cdpUrl
+      }
+    };
+  }
+  const discovered = await discoverLocalCdp2();
+  if (discovered) {
+    return {
+      localLaunchOptions: { cdpUrl: discovered.wsUrl },
+      localInfo: {
+        localSource: "attached-existing",
+        resolvedCdpUrl: discovered.wsUrl
+      }
+    };
+  }
+  return {
+    localLaunchOptions: { headless, viewport: defaultViewport },
+    localInfo: {
+      localSource: "isolated-fallback",
+      fallbackReason: "no debuggable local browser found"
+    }
+  };
+}
 
 // src/resolve-ws.ts
 init_cjs_shims();
@@ -164783,7 +164848,7 @@ async function readLocalConfig(session) {
     const raw = await import_fs11.promises.readFile(getLocalConfigPath(session), "utf-8");
     return JSON.parse(raw);
   } catch {
-    return { strategy: "auto" };
+    return { ...DEFAULT_LOCAL_CONFIG };
   }
 }
 async function writeLocalConfig(session, config3) {
@@ -164800,6 +164865,23 @@ async function readLocalInfo(session) {
     return null;
   }
 }
+async function waitForLocalInfo(session, timeoutMs = 1500) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeoutMs) {
+    const localInfo = await readLocalInfo(session);
+    if (localInfo) {
+      return localInfo;
+    }
+    await new Promise((resolve4) => setTimeout(resolve4, 50));
+  }
+  return readLocalInfo(session);
+}
+function logLocalModeHint(localConfig, localInfo) {
+  const hint = getLocalModeHint(localConfig, localInfo);
+  if (hint) {
+    console.error(hint);
+  }
+}
 function hasBrowserbaseCredentials() {
   return Boolean(process.env.BROWSERBASE_API_KEY);
 }
@@ -165097,33 +165179,15 @@ async function runDaemon(session, headless) {
       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"
-            };
-          }
-        }
+        const resolvedLocalStrategy = await resolveLocalStrategy({
+          localConfig: await readLocalConfig(session),
+          headless,
+          defaultViewport: DEFAULT_VIEWPORT2,
+          discoverLocalCdp,
+          resolveWsTarget
+        });
+        localLaunchOptions = resolvedLocalStrategy.localLaunchOptions;
+        localInfo = resolvedLocalStrategy.localInfo;
       }
       stagehand = new V3({
         env: useBrowserbase ? "BROWSERBASE" : "LOCAL",
@@ -166072,7 +166136,8 @@ program.command("status").description("Check daemon status").action(async () =>
     }
     if (mode === "local") {
       const localConfig = await readLocalConfig(session);
-      const localInfo = await readLocalInfo(session);
+      const localInfo = await readLocalInfo(session) ?? await waitForLocalInfo(session);
+      logLocalModeHint(localConfig, localInfo);
       localDetails = {
         localStrategy: localConfig.strategy,
         ...localInfo ?? {}
@@ -166090,9 +166155,20 @@ program.command("status").description("Check daemon status").action(async () =>
     })
   );
 });
-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(
+var envUsage = "Usage: browse env [local|remote]\n  browse env local [--auto-connect|<port|url>]";
+var envCommand = program.command("env [target] [cdpTarget]").description(
+  "Show or switch browser environment (local | remote)\n\n  browse env                    Show current environment\n  browse env local              Use clean isolated local browser (default)\n  browse env local --auto-connect  Auto-discover local Chrome, fallback to isolated\n  browse env local <port|url>   Attach to specific CDP target\n  browse env remote             Use Browserbase (requires API key)"
+).option(
+  "--auto-connect",
+  "Auto-discover an existing local Chrome instance via CDP"
+);
+envCommand.addOption(
+  new import_commander.Option(
+    "--isolated",
+    "Deprecated alias for the default isolated local browser"
+  ).hideHelp()
+);
+envCommand.action(
   async (target, cdpTarget, cmdOpts) => {
     const opts = program.opts();
     const session = getSession(opts);
@@ -166123,9 +166199,7 @@ program.command("env [target] [cdpTarget]").description(
     };
     const mapped = modeMap[target];
     if (!mapped) {
-      console.error(
-        "Usage: browse env [local|remote]\n  browse env local [--isolated] [<port|url>]"
-      );
+      console.error(envUsage);
       process.exit(1);
     }
     try {
@@ -166134,10 +166208,22 @@ program.command("env [target] [cdpTarget]").description(
       console.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
-    let localConfig = { strategy: "auto" };
+    let localConfig = { ...DEFAULT_LOCAL_CONFIG };
     if (mapped === "local") {
-      if (cmdOpts.isolated) {
-        localConfig = { strategy: "isolated" };
+      const selectedLocalStrategies = [
+        Boolean(cmdOpts.autoConnect),
+        Boolean(cmdOpts.isolated),
+        Boolean(cdpTarget)
+      ].filter(Boolean);
+      if (selectedLocalStrategies.length > 1) {
+        console.error(envUsage);
+        console.error(
+          "Use only one of --auto-connect, --isolated, or <port|url>."
+        );
+        process.exit(1);
+      }
+      if (cmdOpts.autoConnect) {
+        localConfig = { strategy: "auto" };
       } else if (cdpTarget) {
         localConfig = { strategy: "cdp", cdpTarget };
       }
@@ -166160,6 +166246,9 @@ program.command("env [target] [cdpTarget]").description(
       await stopDaemonAndCleanup(session);
     }
     await ensureDaemon(session, isHeadless(opts));
+    if (mapped === "local") {
+      logLocalModeHint(localConfig, await waitForLocalInfo(session));
+    }
     console.log(
       JSON.stringify({
         mode: toModeTarget(mapped),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/browse-cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Browser automation CLI for AI agents, built on Stagehand",
   "type": "commonjs",
   "license": "MIT",