diff --git a/skills/browser/EXAMPLES.md b/skills/browser/EXAMPLES.md index c43701f..db59c30 100644 --- a/skills/browser/EXAMPLES.md +++ b/skills/browser/EXAMPLES.md @@ -130,6 +130,22 @@ browse stop **Key pattern**: Use `--context-id --persist` on the first session to save auth state. On subsequent sessions, use `--context-id ` (with or without `--persist`) to resume where you left off. Omit `--persist` if you don't want changes from that session saved back. +## Example 6: Attach to an Existing Browserbase Session + +**User request**: "Connect to this running Browserbase session and check its state" + +Use `--connect` to attach the CLI to a Browserbase session that was created outside the CLI (via the API, dashboard, or another tool). The CLI connects without creating a new session, and `browse stop` disconnects without killing it. + +```bash +# Attach to the existing session +browse --connect bb_sess_abc123 open https://app.example.com/dashboard +browse snapshot # inspect the page +browse get text ".status" # extract data +browse stop # disconnect — session stays alive on Browserbase +``` + +**Key pattern**: `--connect` is for sessions you don't own — the CLI is a guest. `browse stop` only disconnects, it does not terminate the remote session. Cannot be combined with `--context-id`. + ## Tips - **Snapshot first**: Always run `browse snapshot` before interacting — it gives you the accessibility tree with element refs diff --git a/skills/browser/REFERENCE.md b/skills/browser/REFERENCE.md index 71827a4..eb184e4 100644 --- a/skills/browser/REFERENCE.md +++ b/skills/browser/REFERENCE.md @@ -411,6 +411,18 @@ Load a Browserbase context to persist browser state (cookies, localStorage, sess Save browser state changes back to the Browserbase context when the session ends. Must be used with `--context-id`. +#### `--connect ` + +Attach to an existing Browserbase session by ID instead of creating a new one. **Remote mode only** — errors in local mode. The session stays alive after `browse stop` (uses `keepAlive: true`), so you can reconnect later or hand it off to another tool. + +```bash +browse --connect bb_sess_abc123 open https://example.com +``` + +- Mutually exclusive with `--context-id` (the session already exists and has its own state). +- If the daemon is running with a different session ID, it automatically restarts. +- `browse stop` disconnects the CLI but does **not** terminate the Browserbase session. + ### Environment Variables | Variable | Required | Description | diff --git a/skills/browser/SKILL.md b/skills/browser/SKILL.md index 3c4e652..bc15bd8 100644 --- a/skills/browser/SKILL.md +++ b/skills/browser/SKILL.md @@ -56,6 +56,7 @@ All commands work identically in both modes. The daemon auto-starts on first com browse open # Go to URL (aliases: goto) browse open --context-id # Load Browserbase context (remote only) browse open --context-id --persist # Load context + save changes back +browse --connect open # Attach to existing Browserbase session (remote only) browse reload # Reload current page browse back # Go back in history browse forward # Go forward in history