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

[shrey150]

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

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

---

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

^{Written for commit 064c0e4. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 064c0e4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as "Browse CLI"
    participant FS as "File System (Socket Dir)"
    participant Daemon as "CLI Daemon Process"
    participant BB as "Browserbase API"

    Note over User,BB: CLI Command Execution Flow (e.g., browse [--proxies] open URL)

    User->>CLI: Run command with session flags
    CLI->>FS: getDesiredMode(session)
    FS-->>CLI: Mode (local or browserbase)

    alt Flags provided in local mode
        CLI-->>User: Error: Session flags only supported in remote mode
    else Flags provided in remote mode
        CLI->>CLI: buildSessionParamsFromOpts()
        CLI->>FS: Read existing session-params
        FS-->>CLI: current parameters
        CLI->>FS: Write browse-{session}.session-params
        
        opt Params changed and Daemon is active
            CLI->>Daemon: stopDaemonAndCleanup()
            Daemon-->>CLI: Terminated
        end
    end

    CLI->>Daemon: ensureDaemon(session)
    
    Note over Daemon,BB: Daemon Initialization
    Daemon->>FS: Read browse-{session}.session-params
    FS-->>Daemon: JSON params (proxies, stealth, etc.)
    
    Daemon->>BB: Create session with browserbaseSessionCreateParams
    Note right of BB: Includes proxies, region, timeout and browserSettings (stealth, ads, captchas)
    BB-->>Daemon: Session ID / CDP URL

    Daemon-->>CLI: Daemon ready
    CLI->>Daemon: sendCommand(args)
    Daemon-->>CLI: Result
    CLI-->>User: Output result

    Note over User,FS: Status Check Flow
    User->>CLI: browse status
    CLI->>FS: isDaemonRunning()
    CLI->>FS: Read browse-{session}.session-params
    FS-->>CLI: session parameters
    CLI-->>User: Output JSON (includes sessionParams)

Loading