# why
- the cli has moved to a different repo
# what changed
- removed release-cli.yml & changelog.md
- cleaned up cli publish related metadata from package.json
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Remove the CLI release workflow and publish hooks now that
`@browserbasehq/browse-cli` lives in its own repo. This prevents
accidental publishes from this monorepo and simplifies releases.
- **Refactors**
- Deleted `.github/workflows/release-cli.yml` and removed CLI
publish/canary steps from `.github/workflows/release.yml`.
- Removed `packages/cli/CHANGELOG.md`.
- Cleaned up publish-related fields in `packages/cli/package.json`
(publishConfig, files, prepublishOnly).
- Cleared `.changeset/config.json` ignore list to stop special-casing
the CLI.
<sup>Written for commit 880c857cf93643500165ed722e29e9ca69218aa9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2143?utm_source=github">Review
in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
this updates a handful of deps we were behind on & avoids breaking docs
# what changed
bumped the following deps:
- `@langchain/openai` to `^1.4.5`
- `@langchain/core` to `^1.1.46`
- `@anthropic-ai/claude-agent-sdk` to `^0.2.141`
- `@fastify/swagger-ui` to `^5.2.6` in `packages/server-v3` &
`packages/server-v4`
- `uuid` to `^11.1.1`
- `vite` to `^7.3.3` in the packages that use `vitest`
- workspace tooling like `@changesets/cli`, `c8`, `eslint`, and `tsup`
added the following `pnpm` overrides:
- `axios`
- `follow-redirects`
- `jws`
- `lodash`
- `minimatch`
- `uuid`
also fixed a `vitest` mock typing issue in
`packages/evals/tests/tui/commandTree.test.ts` that resulted from the
vite bump
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Update workspace dependencies and add `pnpm` overrides to lock
transitive versions, stabilizing builds and preventing docs from
breaking. Also fixes a Vitest typing issue introduced by the Vite
upgrade.
- **Dependencies**
- Bumped: `@langchain/openai` → `^1.4.5`, `@langchain/core` → `^1.1.46`,
`@anthropic-ai/claude-agent-sdk` → `^0.2.141`, `uuid` → `^11.1.1`,
`@fastify/swagger-ui` → `^5.2.6` (server v3/v4).
- Tooling: `vite` → `^7.3.3`, `vitest` → `^4.1.6`, `tsup` → `^8.5.1`,
plus `@changesets/cli`, `c8`, `eslint`.
- Docs: `mintlify` → `^4.2.546` and move OpenAPI path to `api.openapi`
in `packages/docs/docs.json`.
- Added `pnpm.overrides` for `axios`, `follow-redirects`, `jws`,
`lodash`, `minimatch`, `uuid`.
- **Bug Fixes**
- Fixed `vitest` mock typing in
`packages/evals/tests/tui/commandTree.test.ts` by typing handlers
(`CommandHandler`) and `printHelp` mocks.
<sup>Written for commit cd57bdf55f36ffe05bfa0de3e43aa2619d159546.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.6.0`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.6.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
`browse cdp` enables the Page domain via `Page.enable`, but
`Page.enable` does not by itself emit `Page.lifecycleEvent` — that
requires a separate `Page.setLifecycleEventsEnabled` opt-in. As a
result, consumers of `browse cdp` today see only `Page.frameNavigated`
and miss the granular lifecycle milestones (`init`, `commit`,
`DOMContentLoaded`, `load`, `firstPaint`, `firstContentfulPaint`,
`firstMeaningfulPaint`, `networkAlmostIdle`, `networkIdle`).
This PR enables lifecycle events whenever the Page domain is enabled (so
it covers both the default-domain set and explicit `--domain Page`), and
adds a `--pretty` formatter case that prints the milestone name.
## Why
These events are exactly what observability/perf tools want from the
firehose:
- approximate page-ready timing (`DOMContentLoaded` / `load`)
- network-settled signal (`networkIdle`)
- paint timing (`firstPaint` / `firstContentfulPaint` /
`firstMeaningfulPaint`)
Without the opt-in, all of those have to be approximated from
`Page.frameNavigated` + `Network.loadingFinished`, which loses the
per-milestone resolution.
## Verification
Built locally with `pnpm exec tsx src/index.ts cdp 9333` against a
debuggable Chrome and triggered an `example.com` navigation. Before this
patch, no `Page.lifecycleEvent` lines. After:
```
[Page.lifecycleEvent] init
[Page.lifecycleEvent] commit
[Page.lifecycleEvent] DOMContentLoaded
[Page.lifecycleEvent] firstPaint
[Page.lifecycleEvent] firstContentfulPaint
[Page.lifecycleEvent] firstMeaningfulPaint
[Page.lifecycleEvent] load
[Page.lifecycleEvent] networkAlmostIdle
[Page.lifecycleEvent] networkIdle
```
Default mode (NDJSON) emits the same events with full params:
```json
{"sessionId":"…","method":"Page.lifecycleEvent","params":{"frameId":"…","loaderId":"…","name":"DOMContentLoaded","timestamp":468107.080156}}
```
## Test plan
- [ ] `pnpm --filter @browserbasehq/browse-cli typecheck` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli eslint` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli test` — no new failures
(pre-existing failures in `cli.test.ts` / `mode.test.ts` reproduce on
`main` and are unrelated to this change)
- [ ] Manual: `browse cdp <port>` against a debuggable Chrome shows
`Page.lifecycleEvent` lines after a navigation
- [ ] Manual: `browse cdp <port> --pretty` formats
`[Page.lifecycleEvent] <name>`
- [ ] Manual: `browse cdp <port> --domain Network --domain Console` (no
Page) emits no lifecycle events — the opt-in is gated correctly
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
- move local CDP discovery into a dedicated module so the
DevToolsActivePort behavior is directly testable
- reuse the exact `DevToolsActivePort` websocket path for `browse env
local --auto-connect`
- reuse the same exact-path lookup for bare numeric CDP targets in
`resolveWsTarget`
- avoid the extra speculative websocket verification pass on the
file-backed discovery path
- add regression coverage for exact-path resolution, stale file cleanup,
ambiguity, and fallback port probing
## Root Cause
The CLI was reading `DevToolsActivePort` but then discarding the exact
websocket path and probing generic endpoints first. On Chrome's
remote-debugging approval flow that could trigger extra preflight
requests before the real attach.
## Validation
- `pnpm --filter @browserbasehq/stagehand gen-version`
- `pnpm --filter @browserbasehq/stagehand build-dom-scripts`
- `pnpm --filter @browserbasehq/stagehand build`
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli typecheck`
- `pnpm --filter @browserbasehq/browse-cli test`
Linear:
https://linear.app/browserbase/issue/STG-1859/use-exact-devtoolsactiveport-websocket-path-for-browse-cli-auto
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local CDP auto-connect by using the exact websocket path from
DevToolsActivePort to avoid extra probes and speed up attach in Chrome’s
approval flow. Addresses Linear STG-1859 and improves
`@browserbasehq/browse-cli` for `browse env local --auto-connect` and
bare port targets.
- **Bug Fixes**
- Reuse the exact DevToolsActivePort websocket path for local
auto-connect.
- Prefer exact-path resolution for bare numeric ports in
`resolveWsTarget`, then fall back to `/json/version`, then
`/devtools/browser`.
- Skip speculative websocket verification when a file provides the exact
path.
- Clean up stale DevToolsActivePort files and return null on ambiguity.
- **Refactors**
- Extracted local CDP discovery to `local-cdp-discovery.ts` with tests
for exact-path resolution, stale cleanup, ambiguity, and fallback
probing.
<sup>Written for commit 440eee4c562a71775cf3e413d5e929a0881837de.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2049">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Remove all `BROWSERBASE_PROJECT_ID` / `projectId` references from v3
docs, SDK docs, integration guides, migration guides, and CLI README (30
files)
- Only `BROWSERBASE_API_KEY` is required — `projectId` is optional in
all code control paths (conditionally included via spread patterns,
never validated as required)
- Preserves unrelated GCP project ID references in `models.mdx`
## Test plan
- [ ] Verify docs site builds without errors
- [ ] Spot-check code examples still make sense without projectId
- [ ] Confirm no broken references or formatting issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed all `BROWSERBASE_PROJECT_ID`/`projectId` references across v3
docs so setup only requires `BROWSERBASE_API_KEY`. Also updated
Anthropic model references to `anthropic/claude-sonnet-4-6` across
examples and guides.
- **Migration**
- Remove `BROWSERBASE_PROJECT_ID` from env files, deployment configs,
session params, and env var lists; keep `BROWSERBASE_API_KEY` only.
- Existing code passing `projectId` still works; it’s optional and not
required.
- Unrelated GCP project ID mentions remain unchanged.
- **Refactors**
- Replaced all `anthropic/claude-sonnet-4-20250514` references with
`anthropic/claude-sonnet-4-6` across v3 docs (agent examples, warnings,
best practices).
- Simplified MCP config by removing the `CardGroup` wrapper around a
single card.
<sup>Written for commit 7a1688d2cf03f68e4a14e43259c4edcd205a164a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1958">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Adds `browse upload <selector> <files...>` command to upload files to
`<input type="file">` elements
- Uses Understudy's `setInputFiles` under the hood, which handles both
local (CDP `DOM.setFileInputFiles`) and remote/Browserbase (base64
payload injection) paths automatically
- Supports ref-based selectors from `browse snapshot` (e.g., `browse
upload @0-5 ./doc.pdf`)
- Supports multiple files: `browse upload @0-5 ./a.png ./b.png`
## Usage
```bash
browse upload <selector> <file> # single file
browse upload @0-5 ./document.pdf # using ref from snapshot
browse upload @0-5 ./a.png ./b.png # multiple files
```
## Test plan
- [X] Test single file upload on a local page with `<input type="file">`
- [X] Test multiple file upload
- [X] Test with ref-based selector from snapshot
- [X] Test on remote Browserbase session (base64 injection path)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## 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 064c0e41bdac86d54d185ad4911fb39eb44bb9c1.
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>
Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.5.0`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.5.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Publish `@browserbasehq/browse-cli@0.5.0`, defaulting `browse env local`
to an isolated browser and adding `--auto-connect` to opt into attaching
to an existing debuggable Chrome; explicit CDP attach via `browse env
local <port|url>` remains unchanged.
- **Migration**
- If you previously relied on auto-attach, run: `browse env local
--auto-connect`.
<sup>Written for commit 795c0050519b5fe839e29de3d925ee5efe7603a2.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1946">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
- make `browse env local` default back to an isolated local browser
- add `browse env local --auto-connect` as the explicit opt-in path for
auto-discovering a debuggable local Chrome
- keep explicit CDP attach via `browse env local <port|url>` and add
tests to lock in the strategy behavior
## Why
`browse env local` was auto-attaching to an existing local Chrome by
default. That can trigger Chrome's remote debugging approval dialog
unexpectedly and makes isolated local usage less predictable.
## Impact
Users now get a clean local browser by default, while still having two
explicit ways to reuse an existing browser when they want to:
- `browse env local --auto-connect`
- `browse env local <port|url>`
## Test Plan
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli test`
- `pnpm exec prettier --check packages/cli && cd packages/cli && pnpm
run eslint && pnpm run typecheck`
- e2e smoke test against a disposable Chrome CDP endpoint on
`127.0.0.1:9229` using a temporary `HOME` / user-data-dir so the checks
do not touch a real browsing profile
- verified `browse env local` returns `localStrategy: "isolated"`
- verified `browse status` in isolated mode reports `localSource:
"isolated"`
- verified `browse env local` and `browse status` both print the hint to
use `browse env local --auto-connect` to reuse local credentials/cookies
- verified `browse env local --auto-connect` returns `localStrategy:
"auto"`
- verified `browse env local --auto-connect` prints the hint that plain
`browse env local` switches back to an isolated Chromium browser
- verified `open https://example.com` succeeds after `--auto-connect`
- verified `browse status` after `--auto-connect` reports `localSource:
"attached-existing"` with the resolved CDP URL and the isolated-browser
hint
- verified `browse env local 9229` returns `localStrategy: "cdp"`
- verified `browse status` after `browse env local 9229` reports
`localSource: "attached-explicit"`
Linear: STG-1752
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Defaulted `browse env local` to a clean, isolated browser. Added
`--auto-connect` to opt into reusing a debuggable Chrome, kept explicit
CDP attach via `browse env local <port|url>`, and added mode hints to
guide users. Addresses Linear STG-1752 to make local usage predictable
and avoid surprise debugging prompts.
- **New Features**
- Isolated local browser is now the default; auto-discovery only with
`--auto-connect`.
- Mode hints in `browse env`/`browse status` suggest when to use
`--auto-connect` or switch back to isolated.
- `browse env local <port|url>` remains for explicit CDP targets.
- Centralized strategy resolution in `src/local-strategy.ts` with unit
tests.
- Clearer `browse env` usage and validation; rejects mixing
`--auto-connect`, `--isolated`, or a target. `--isolated` is deprecated
(accepted; hidden from help).
- **Migration**
- To reuse an existing Chrome: `browse env local --auto-connect`.
- To attach to a specific target: `browse env local <port|url>`.
- No changes if you want a clean isolated browser by default.
<sup>Written for commit a132cb182c5387cd58ae31f366f93bcf1f5cceab.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1945">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.4.2`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.4.2` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Publish `@browserbasehq/browse-cli` 0.4.2 by bumping the version and
updating the changelog. This release adds a command to convert page HTML
to Markdown.
- **New Features**
- Add `browse get markdown [selector]` to convert page HTML to Markdown.
Defaults to body; supports an optional selector; preserves links,
tables, and code blocks via `node-html-markdown`.
<sup>Written for commit eb2b85ff35405600cb3911bc2ad3fd09b018d149.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1942">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
- Adds `browse get markdown [selector]` to convert page HTML to clean
markdown
- Defaults to body content when no selector given, accepts optional
CSS/XPath/ref selector
- Uses `node-html-markdown` for quality conversion (links, tables, code
blocks preserved)
- Useful for agents that need readable page content without HTML noise
## Usage
```bash
browse get markdown # full page body as markdown
browse get markdown .article # specific element
browse get markdown @0-5 # ref from snapshot
```
## Test results
| Test | Local | Remote (Browserbase) |
|------|-------|---------------------|
| `get markdown` (body default) | HN full page markdown | HN full page
markdown |
| `get markdown .titleline` (selector) | Clean link with title | Clean
link with title |
## Test plan
- [x] Test locally with no selector (full body)
- [x] Test locally with CSS selector
- [x] Test on remote Browserbase session (no selector)
- [x] Test on remote Browserbase session (with selector)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.4.1`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.4.1` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Release `@browserbasehq/browse-cli@0.4.1`, a patch that fixes an invalid
session metadata key. This bumps the package version and updates the
changelog for publishing from `main`.
- **Bug Fixes**
- Use underscore in `browse_cli` session metadata keys instead of a
hyphen.
<sup>Written for commit 022c400a4e398a222b0691f6c0d4c3c02621d471.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1932">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
- The `browse-cli` metadata key (with hyphen) is rejected by the
Browserbase API as an invalid metadata key, causing `env remote` to fail
with a `400 Key is not a valid metadata key: browse-cli` error.
- Changed the key to `browse_cli` (underscore) which is a valid metadata
key format.
Linear:
https://linear.app/browserbase/issue/STG-1733/fix-use-valid-metadata-key-for-browse-cli-sessions
## Test plan
- [x] Verified old key (`browse-cli`) returns 400 from Browserbase API
- [x] Verified new key (`browse_cli`) returns 201 and session creates
successfully
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.4.0`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.4.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Release `@browserbasehq/browse-cli` 0.4.0 with new session attach and
smarter local Chrome discovery, plus stability fixes. Bumps the package
version and updates the changelog; the Release workflow will publish
from this commit.
- **New Features**
- Add `--connect` to attach to an existing Browserbase session by ID.
- `browse env local` auto-discovers debuggable Chrome and attaches when
found (falls back to isolated). Adds `--isolated`, positional CDP
target, and `--ws` accepts bare port numbers.
- **Bug Fixes**
- Add CLI metadata to Browserbase sessions created via the CLI.
- Clear cached browser state when CDP connection drops to prevent
“awaitActivePage: no page available” errors.
<sup>Written for commit d74493490d65ffd4f18e128ae2afb8448c4117f0.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1925">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
Move browse-cli to a merge-first release flow so `main` becomes the
source of truth before npm is mutated.
## New release flow
1. Merge normal feature PRs into `main`, with browse-cli changesets as
usual.
2. Trigger `Prepare CLI Release` when browse-cli is ready to ship.
3. That workflow versions only `@browserbasehq/browse-cli` and opens or
updates a release PR.
4. Merge the release PR.
5. The existing `Release` workflow on `main` detects the browse-cli
version bump, publishes a packed tarball to npm with provenance, and
tags the merge commit.
## What changed
- rewired `release-cli.yml` into a prepare-only workflow that creates or
updates a release PR instead of publishing directly
- moved browse-cli publishing into `release.yml`, gated on an actual
version bump landing on `main`
- kept the `pnpm pack` -> `npm publish --provenance` path so workspace
dependencies are resolved in the published tarball
- made the main-branch publish path idempotent when that browse-cli
version is already on npm
- kept browse-cli tagging on the merge commit instead of trying to tag
from the manual workflow
- synced `packages/cli/package.json` to `0.3.0` and documented npm
`0.3.0` as a broken publish in the CLI changelog
## Why this is better
The previous standalone release design could succeed at publishing to
npm and then fail while trying to sync `main`, which left npm ahead of
git. That is the hard failure mode because npm versions are immutable.
This PR flips the order:
- git changes land first through a normal PR
- npm publish happens afterward from the exact merged commit
That removes the whole class of "published version is not reflected on
`main`" failures and makes reruns much safer.
## Validation
- `pnpm exec prettier --check .github/workflows/release.yml
.github/workflows/release-cli.yml packages/cli/package.json
packages/cli/CHANGELOG.md`
- packed `packages/cli` locally and verified the tarball manifest
resolves `@browserbasehq/stagehand` to `3.2.0`
- confirmed the currently published npm `0.3.0` manifest still contains
the broken `workspace:*` dependency
- simulated the prepare flow in a throwaway worktree and confirmed it
would cut `0.4.0` from the current 2 minor + 2 patch browse-cli
changesets
## Summary
- `browse env local` now auto-discovers an already-running Chrome with
remote debugging enabled (via `DevToolsActivePort` files and common port
probing), attaching to it instead of always launching an isolated
browser
- Falls back to isolated launch when no debuggable Chrome is found —
keeps the command reliable
- Added `--isolated` flag to force clean isolated browser (old behavior)
- Added positional CDP target argument: `browse env local 9222` or
`browse env local ws://...`
- `browse status` now reports `localStrategy`, `localSource`,
`resolvedCdpUrl`, and `fallbackReason`
**Sister PR:** browserbase/skills#54
## Test plan
<img width="698" height="373" alt="image"
src="https://github.com/user-attachments/assets/1612cf7e-61f4-46b8-9cc6-e739c7363a5a"
/>
- [x] All 44 existing tests pass
- [x] `browse env local` with Chrome running +
`--remote-debugging-port=9222` → attaches to existing Chrome
- [x] `browse env local` without debuggable Chrome → falls back to
isolated launch
- [x] `browse env local --isolated` → always launches clean browser
- [x] `browse env local 9222` → persists CDP strategy targeting
127.0.0.1:9222
- [x] `browse status` shows local strategy details
- [x] `browse env remote` → unchanged
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Adds a global `--connect <session-id>` flag to the `browse` CLI that
connects to an existing Browserbase session instead of creating a new
one
- Uses Stagehand core's existing `browserbaseSessionID` support with
`keepAlive: true` so the session stays alive after the CLI disconnects
- Follows the same state-file pattern as `--context-id` (writes session
ID to `/tmp/browse-{session}.connect`, daemon reads it during
initialization)
## Test procedure
```
# 1. Sync cookies
node cookie-sync.mjs --domains github.com
# → Session ID: 3ee737d4-237f-4557-a1ca-09a3d5dcbaf2
# 2. Connect and browse (dev build)
browse --connect 3ee737d4-... open https://github.com/notifications✅
browse eval "..." ✅
```
## Tests completed
- [x] `browse --connect <id> open ...` in local mode → errors with "only
supported in remote mode"
- [x] `browse --connect <id> open --context-id <ctx> ...` → errors with
mutual exclusion message
- [x] `--connect` writes session ID to connect file before daemon start
- [x] Commands without `--connect` clear stale connect file
- [x] `browse status` output includes `browserbaseSessionId` field
- [x] Manual: `browse --connect <valid-bb-session> open
https://example.com` connects and navigates
- [x] Manual: `browse stop` disconnects without killing the BB session
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Fixes STG-1672
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a `--connect <session-id>` flag to the `browse` CLI to attach to an
existing Browserbase session instead of creating a new one, leaving the
session running after the CLI exits. Implements STG-1672.
- **New Features**
- New global `--connect <session-id>` for `browse` to attach to an
existing Browserbase session
- Remote mode only; errors in local mode
- Mutually exclusive with `--context-id`
- Persists the session ID to `/tmp/browse-{session}.connect`; clears
when unused and restarts the daemon if the ID changes
- Uses `browserbaseSessionID` with `keepAlive: true` so the session
persists after disconnect
- `browse status` now includes a `browserbaseSessionId` field
- Minor release for `@browserbasehq/browse-cli`
<sup>Written for commit aff1badd630fbbf2276b8121f5981b551850be2f.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1889">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- When the browse CLI daemon outlives its Chrome browser (e.g., between
Claude Code sessions), `ensureBrowserInitialized()` returns the cached
`stagehand`/`context` without checking if the browser is still alive
- This causes `"No Page found for awaitActivePage: no page available"`
errors requiring a manual `browse stop` + retry
- Fix: register an `onTransportClosed` handler on the CDP connection
that clears the cached state, so the next command triggers a full
re-initialization
## Root cause
The daemon is spawned as a detached process (`detached: true`,
`child.unref()`) and persists across CLI sessions. When Chrome dies,
`_onCdpClosed` fires and calls `stagehand.close()`, but the daemon's
closure variables `stagehand` and `context` are never cleared. The next
command hits the early return at `if (stagehand && context) { return ...
}` and tries to use dead objects.
## Test plan
**Regression test added to PR is illustrative**
- [x] Start a `browse` session, close Chrome manually, run another
`browse open` — should auto-recover instead of erroring
- [x] Normal `browse` workflow (open, snapshot, click, stop) still works
- [x] Daemon restart across mode switches (local ↔ remote) still works
- [x] Regression test added: kills Chrome under daemon, verifies
auto-recovery (fails on main, passes with fix)
## Verified test results
**On `main` (without fix):** Test fails — after killing Chrome, the
retry returns exit code 1 with `"Error: No Page found for
awaitActivePage: no page available"`. The daemon is alive but returns
stale cached Stagehand/context objects.
**On this branch (with fix):** Test passes — after killing Chrome, the
`onTransportClosed` handler nulls the cached state, and the retry
triggers a full browser re-initialization. All 37 CLI tests pass (full
suite, 67s).
> **Note:** When building locally, use `npx tsup src/index.ts --format
cjs --out-dir dist --no-splitting` inside `packages/cli/` rather than
`pnpm run build:cli`, since turbo may serve a stale cached build that
doesn't include the fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Adds `userMetadata: { "browse-cli": "true" }` to every Browserbase
session created through the browse CLI
- Enables usage attribution to distinguish CLI-originated sessions from
SDK-originated ones
## Test plan
- [x] Run `browse open https://example.com` in Browserbase mode and
verify the session has `browse-cli: true` in its metadata
- [x] Verify local mode is unaffected
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `userMetadata: { "browse-cli": "true" }` to
`browserbaseSessionCreateParams` for sessions started by
`@browserbasehq/browse-cli` in Browserbase mode, enabling usage
attribution and distinguishing CLI vs SDK sessions. Satisfies STG-1678;
local mode is unaffected.
<sup>Written for commit 58c10fdf25c5494bdb2b1c1e793344009fa6374a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1890">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# why
when running pnpm format, it formats files that are not relevant to
current changes which is annoying
# what changed
formatted the unformatted files in cli package
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Standardized Prettier/ESLint formatting in `packages/cli` so `pnpm
format` runs are stable and don’t touch unrelated files. No functional
changes.
- **Refactors**
- Applied Prettier across `packages/cli/src` and tests (line breaks,
parens, quotes).
- Tidied lint/Prettier config formatting (`eslint.config.mjs`,
`.prettierrc` newline).
- Adjusted test imports and one assertion to match formatter.
<sup>Written for commit 31570dbe68a938aa5e12ccb4c36d130a5e9833c9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1819">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Adds `--context-id <id>` and `--persist` flags to `browse open` so
agents can load/persist browser state (cookies, localStorage, etc.)
across Browserbase sessions using Contexts
- Validates edge cases: `--persist` requires `--context-id`,
`--context-id` requires remote mode, context change triggers daemon
restart
## Usage
```bash
# Load a context (read-only — state not saved back)
browse open https://app.com --context-id ctx_abc123
# Load and persist changes back on session end
browse open https://app.com --context-id ctx_abc123 --persist
```
## How it works
1. `browse open --context-id` writes context config to
`/tmp/browse-{session}.context`
2. The daemon reads this file during browser initialization and passes
it through as `browserbaseSessionCreateParams.browserSettings.context`
3. If a second `browse open` is called with a different context ID, the
daemon is restarted (context is baked into the BB session at creation
time)
Context config uses a temp file (same pattern as `.mode`) because it's
needed at Browserbase session creation time, before the daemon's command
socket is up.
## Test plan
- [x] `browse open https://example.com --context-id <known-id>
--persist` on remote mode — verify session created with context in BB
dashboard
- [x] `browse stop` then reopen with same context — verify state
persists
- [x] Verify context mismatch triggers daemon restart (open with context
A, then open with context B)
- [x] Same context, second open — verify no unnecessary restart
- [x] `browse open https://example.com --context-id <id>` on local mode
— verify clear error
- [x] `browse open https://example.com --persist` without `--context-id`
— verify clear error
- [x] Plain `browse open` (no context flags) — verify no regression
- [x] `cleanupStaleFiles` removes `.context` file on shutdown
- [x] Stale `.context` file from crashed daemon is cleared on next
`browse open` without `--context-id`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Stacked on #1800
- Only `BROWSERBASE_API_KEY` is required for remote mode in the CLI
- `BROWSERBASE_PROJECT_ID` is still passed through if set, but no longer
checked
## Changes
- `packages/cli/src/index.ts` — `hasBrowserbaseCredentials()` only
checks for API key
- `packages/cli/tests/mode.test.ts` — Updated test to match new error
message
- `packages/cli/README.md` — Updated docs to reflect optional project ID
## Test plan
- [x] Existing mode test updated
- [x] Manual: `browse env remote` with only `BROWSERBASE_API_KEY` set
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make `BROWSERBASE_PROJECT_ID` optional in the CLI for remote mode, so
only `BROWSERBASE_API_KEY` is required. The project ID is still
forwarded when provided.
- **Bug Fixes**
- Updated remote mode check and error message to only require
`BROWSERBASE_API_KEY`.
- Autodetection now defaults to `remote` when the API key is set;
otherwise `local`.
- Updated tests and `@browserbasehq/browse-cli` README to match.
<sup>Written for commit 99eb1869225948dc8f9a868c27a7bf0c3a47367d.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1803">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- `browse env` showed stale "local" mode after `browse env remote`
- Root cause: `.mode` file was only written during lazy browser init
(`ensureBrowserInitialized`), not at daemon startup. Between daemon
start and first command, `readCurrentMode()` returned `null` and fell
back to hardcoded `"local"`
- Write `.mode` eagerly in `runDaemon()` at startup so it's immediately
available
- Fall back to `desiredMode` instead of `"local"` in the `env` display
handler as a safety net
## Test plan
- [x] Reproduced bug: `browse env remote` → `browse env` showed
`"mode":"local"`
- [x] Verified fix: `browse env remote` → `browse env` now shows
`"mode":"remote"`
- [x] `mode.test.ts` passes (3/3)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes `browse env` showing stale "local" after `browse env remote`
(STG-1547). The daemon now writes `.mode` at startup, the display falls
back to `desiredMode` until mode is written, and a patch changeset is
added for `@browserbasehq/browse-cli`.
<sup>Written for commit 9661d92de26f60383a1d77c6c636f43aa95089e4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1806">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>