[STG-1741] feat(cli): add global flags for Browserbase session parameters (browserbase#1935)

## Summary
- Add global CLI flags for commonly used Browserbase session parameters
to the `browse` CLI
- Users no longer need external tools or workarounds to configure
`advancedStealth`, `proxies`, `solveCaptchas`, etc.
- Flags are remote-mode only and trigger daemon restart when changed

### New flags
| Flag | Description |
|------|-------------|
| `--proxies` | Enable Browserbase proxy |
| `--advanced-stealth` | Enable advanced stealth mode |
| `--solve-captchas` / `--no-solve-captchas` | Toggle CAPTCHA solving |
| `--region <region>` | Session region |
| `--keep-alive` | Keep session alive after disconnection |
| `--session-timeout <seconds>` | Session timeout |
| `--block-ads` | Enable ad blocking |

### Examples
```bash
browse --proxies --advanced-stealth open https://example.com
browse --region us-east-1 --solve-captchas open https://example.com
```

Session flags are validated to only work in remote mode and will error
with a helpful message if used in local mode.

Linear:
https://linear.app/browserbase/issue/STG-1741/featcli-add-global-flags-for-browserbase-session-parameters

## Test plan
- [ ] `browse --help` shows new flags with "(remote only)" descriptions
- [ ] `browse --proxies open https://example.com` (in remote mode)
creates session with proxy enabled
- [ ] `browse --advanced-stealth --solve-captchas open
https://example.com` configures both settings
- [ ] `browse --proxies open https://example.com` (in local mode) errors
with helpful message
- [ ] Changing flags restarts the daemon automatically
- [ ] `browse status` shows active session params
- [ ] Build succeeds

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add global flags to `browse` to configure Browserbase session settings
in remote mode (proxies, stealth, CAPTCHA solving, region, keep-alive,
timeouts) without JSON. Settings persist per session, trigger a daemon
restart when changed, and appear as `sessionParams` in `browse status`
JSON; also fixes lint errors. Addresses Linear STG-1741.

- **New Features**
- Flags: `--proxies`, `--advanced-stealth`,
`--solve-captchas`/`--no-solve-captchas`, `--block-ads`, `--region
<region>`, `--keep-alive`, `--session-timeout <seconds>`; remote-only
with a clear error in local mode

<sup>Written for commit 064c0e4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1935">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: shrey150

.changeset/session-params-flags.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/browse-cli": minor
+---
+
+Add global flags for commonly used Browserbase session parameters (--proxies, --advanced-stealth, --solve-captchas, --region, --keep-alive, --session-timeout, --block-ads). These flags configure the Browserbase session in remote mode.

packages/cli/src/index.ts

@@ -178,6 +178,10 @@ function getLocalInfoPath(session: string): string {
   return path.join(SOCKET_DIR, `browse-${session}.local-info`);
 }
 
+function getSessionParamsPath(session: string): string {
+  return path.join(SOCKET_DIR, `browse-${session}.session-params`);
+}
+
 // ==================== LOCAL STRATEGY CONFIG ====================
 
 async function readLocalConfig(session: string): Promise<LocalConfig> {
@@ -544,6 +548,7 @@ async function cleanupStaleFiles(session: string): Promise<void> {
     getContextPath(session),
     getConnectPath(session),
     getLocalConfigPath(session),
+    getSessionParamsPath(session),
   ];
 
   for (const file of files) {
@@ -663,6 +668,15 @@ async function runDaemon(session: string, headless: boolean): Promise<void> {
         ).trim();
       } catch {}
 
+      // Read session params if present (written by --proxies, --advanced-stealth, etc.)
+      let sessionParams: Record<string, unknown> = {};
+      try {
+        const raw = await fs.readFile(getSessionParamsPath(session), "utf-8");
+        sessionParams = JSON.parse(raw);
+      } catch {
+        // No session params file
+      }
+
       // Resolve local browser launch options based on strategy
       let localLaunchOptions: LocalBrowserLaunchOptions | undefined;
       let localInfo: LocalInfo | undefined;
@@ -694,16 +708,24 @@ async function runDaemon(session: string, headless: boolean): Promise<void> {
                 : {}),
               ...(!connectSessionId
                 ? {
-                    browserbaseSessionCreateParams: {
-                      userMetadata: { browse_cli: "true" },
-                      ...(contextConfig
-                        ? {
-                            browserSettings: {
-                              context: contextConfig,
-                            },
-                          }
-                        : {}),
-                    },
+                    browserbaseSessionCreateParams: (() => {
+                      const sessionBrowserSettings =
+                        (sessionParams.browserSettings as Record<
+                          string,
+                          unknown
+                        >) || {};
+                      const { browserSettings: _, ...sessionParamsWithoutBS } =
+                        sessionParams;
+                      void _;
+                      return {
+                        userMetadata: { browse_cli: "true" },
+                        ...sessionParamsWithoutBS,
+                        browserSettings: {
+                          ...sessionBrowserSettings,
+                          ...(contextConfig ? { context: contextConfig } : {}),
+                        },
+                      };
+                    })(),
                   }
                 : {}),
             }
@@ -1804,6 +1826,14 @@ interface GlobalOpts {
   json?: boolean;
   session?: string;
   connect?: string;
+  // Session creation flags (remote only)
+  proxies?: boolean;
+  advancedStealth?: boolean;
+  solveCaptchas?: boolean;
+  region?: string;
+  keepAlive?: boolean;
+  sessionTimeout?: number;
+  blockAds?: boolean;
 }
 
 function getSession(opts: GlobalOpts): string {
@@ -1814,6 +1844,31 @@ function isHeadless(opts: GlobalOpts): boolean {
   return opts.headless === true && opts.headed !== true;
 }
 
+function buildSessionParamsFromOpts(
+  opts: GlobalOpts,
+): Record<string, unknown> | null {
+  const params: Record<string, unknown> = {};
+  const browserSettings: Record<string, unknown> = {};
+
+  if (opts.proxies) params.proxies = true;
+  if (opts.region) params.region = opts.region;
+  if (opts.keepAlive) params.keepAlive = true;
+  if (opts.sessionTimeout !== undefined) params.timeout = opts.sessionTimeout;
+
+  if (opts.advancedStealth) browserSettings.advancedStealth = true;
+  if (opts.blockAds) browserSettings.blockAds = true;
+  if (opts.solveCaptchas !== undefined) {
+    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: unknown, json: boolean): void {
   if (json) {
     console.log(JSON.stringify(data, null, 2));
@@ -1875,6 +1930,38 @@ async function runCommand(command: string, args: unknown[]): Promise<unknown> {
     } catch {}
   }
 
+  // Handle session params flags (--proxies, --advanced-stealth, etc.)
+  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 fs.readFile(paramsPath, "utf-8");
+    } catch {}
+
+    await fs.writeFile(paramsPath, newParamsJson);
+
+    if (
+      currentParamsJson !== newParamsJson &&
+      (await isDaemonRunning(session))
+    ) {
+      await stopDaemonAndCleanup(session);
+    }
+  }
+
   await ensureDaemon(session, headless);
   return sendCommand(session, command, args, headless);
 }
@@ -1897,6 +1984,27 @@ program
   .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,
   );
 
 // ==================== DAEMON COMMANDS ====================
@@ -1972,6 +2080,11 @@ program
         };
       }
     }
+    let sessionParams: Record<string, unknown> | null = null;
+    try {
+      const raw = await fs.readFile(getSessionParamsPath(session), "utf-8");
+      sessionParams = JSON.parse(raw);
+    } catch {}
     console.log(
       JSON.stringify({
         running,
@@ -1980,6 +2093,7 @@ program
         mode,
         browserbaseSessionId,
         ...localDetails,
+        ...(sessionParams ? { sessionParams } : {}),
       }),
     );
   });