@browserbasehq/browse-cli 0.4.2 → 0.5.0-alpha-666baf1

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();
@@ -164778,12 +164843,15 @@ function getLocalConfigPath(session) {
 function getLocalInfoPath(session) {
   return path11.join(SOCKET_DIR, `browse-${session}.local-info`);
 }
+function getSessionParamsPath(session) {
+  return path11.join(SOCKET_DIR, `browse-${session}.session-params`);
+}
 async function readLocalConfig(session) {
   try {
     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 +164868,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);
 }
@@ -165017,7 +165102,8 @@ async function cleanupStaleFiles(session) {
     // Client-written config, only cleaned on full shutdown
     getContextPath(session),
     getConnectPath(session),
-    getLocalConfigPath(session)
+    getLocalConfigPath(session),
+    getSessionParamsPath(session)
   ];
   for (const file2 of files) {
     try {
@@ -165094,36 +165180,24 @@ async function runDaemon(session, headless) {
         connectSessionId = (await import_fs11.promises.readFile(getConnectPath(session), "utf-8")).trim();
       } catch {
       }
+      let sessionParams = {};
+      try {
+        const raw = await import_fs11.promises.readFile(getSessionParamsPath(session), "utf-8");
+        sessionParams = JSON.parse(raw);
+      } 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"
-            };
-          }
-        }
+        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",
@@ -165136,14 +165210,19 @@ async function runDaemon(session, headless) {
             keepAlive: true
           } : {},
           ...!connectSessionId ? {
-            browserbaseSessionCreateParams: {
-              userMetadata: { browse_cli: "true" },
-              ...contextConfig ? {
+            browserbaseSessionCreateParams: (() => {
+              const sessionBrowserSettings = sessionParams.browserSettings || {};
+              const { browserSettings: _2, ...sessionParamsWithoutBS } = sessionParams;
+              void _2;
+              return {
+                userMetadata: { browse_cli: "true" },
+                ...sessionParamsWithoutBS,
                 browserSettings: {
-                  context: contextConfig
+                  ...sessionBrowserSettings,
+                  ...contextConfig ? { context: contextConfig } : {}
                 }
-              } : {}
-            }
+              };
+            })()
           } : {}
         } : {
           localBrowserLaunchOptions: localLaunchOptions
@@ -165955,6 +166034,24 @@ function getSession(opts) {
 function isHeadless(opts) {
   return opts.headless === true && opts.headed !== true;
 }
+function buildSessionParamsFromOpts(opts) {
+  const params = {};
+  const browserSettings = {};
+  if (opts.proxies) params.proxies = true;
+  if (opts.region) params.region = opts.region;
+  if (opts.keepAlive) params.keepAlive = true;
+  if (opts.sessionTimeout !== void 0) params.timeout = opts.sessionTimeout;
+  if (opts.advancedStealth) browserSettings.advancedStealth = true;
+  if (opts.blockAds) browserSettings.blockAds = true;
+  if (opts.solveCaptchas !== void 0) {
+    browserSettings.solveCaptchas = opts.solveCaptchas;
+  }
+  if (Object.keys(browserSettings).length > 0) {
+    params.browserSettings = browserSettings;
+  }
+  if (Object.keys(params).length === 0) return null;
+  return params;
+}
 function output(data, json2) {
   if (json2) {
     console.log(JSON.stringify(data, null, 2));
@@ -166009,6 +166106,29 @@ async function runCommand(command, args) {
     } catch {
     }
   }
+  const sessionParams = buildSessionParamsFromOpts(opts);
+  if (sessionParams) {
+    const desiredMode = await getDesiredMode(session);
+    if (desiredMode !== "browserbase") {
+      console.error(
+        JSON.stringify({
+          error: "Session flags (--proxies, --advanced-stealth, etc.) are only supported in remote mode. Run 'browse env remote' first."
+        })
+      );
+      process.exit(1);
+    }
+    const paramsPath = getSessionParamsPath(session);
+    const newParamsJson = JSON.stringify(sessionParams);
+    let currentParamsJson = "";
+    try {
+      currentParamsJson = await import_fs11.promises.readFile(paramsPath, "utf-8");
+    } catch {
+    }
+    await import_fs11.promises.writeFile(paramsPath, newParamsJson);
+    if (currentParamsJson !== newParamsJson && await isDaemonRunning(session)) {
+      await stopDaemonAndCleanup(session);
+    }
+  }
   await ensureDaemon(session, headless);
   return sendCommand(session, command, args, headless);
 }
@@ -166021,6 +166141,19 @@ program.name("browse").description("Browser automation CLI for AI agents").versi
 ).option(
   "--connect <session-id>",
   "Connect to an existing Browserbase session by ID"
+).option("--proxies", "Enable Browserbase proxy (remote only)").option("--advanced-stealth", "Enable advanced stealth mode (remote only)").option("--solve-captchas", "Enable automatic CAPTCHA solving (remote only)").option(
+  "--no-solve-captchas",
+  "Disable automatic CAPTCHA solving (remote only)"
+).option("--block-ads", "Enable ad blocking (remote only)").option(
+  "--region <region>",
+  "Session region: us-west-2, us-east-1, eu-central-1, ap-southeast-1 (remote only)"
+).option(
+  "--keep-alive",
+  "Keep session alive after disconnection (remote only)"
+).option(
+  "--session-timeout <seconds>",
+  "Session timeout in seconds (remote only)",
+  parseInt
 );
 program.command("start").description("Start browser daemon (auto-started by other commands)").action(async () => {
   const opts = program.opts();
@@ -166072,13 +166205,20 @@ 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 ?? {}
       };
     }
   }
+  let sessionParams = null;
+  try {
+    const raw = await import_fs11.promises.readFile(getSessionParamsPath(session), "utf-8");
+    sessionParams = JSON.parse(raw);
+  } catch {
+  }
   console.log(
     JSON.stringify({
       running,
@@ -166086,13 +166226,25 @@ program.command("status").description("Check daemon status").action(async () =>
       wsUrl,
       mode,
       browserbaseSessionId,
-      ...localDetails
+      ...localDetails,
+      ...sessionParams ? { sessionParams } : {}
     })
   );
 });
-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 +166275,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 +166284,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 +166322,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-alpha-666baf1",
   "description": "Browser automation CLI for AI agents, built on Stagehand",
   "type": "commonjs",
   "license": "MIT",