browser

Files (4)

• EXAMPLES.md
• LICENSE.txt
• REFERENCE.md
• SKILL.md

SKILL.md (first lines)

# Browser Automation (Browserbase Remote)

Drive Browserbase cloud browser sessions with the browse CLI. This skill is remote-only: every session runs in Browserbase's cloud with Identity, Verified browsers, automatic CAPTCHA solving, residential proxies, and persistent contexts. For local browser automation - localhost, dev flows, your own Chrome profile - use the `agent-browser` skill instead.

## When to Escalate Here

This is the documented escalation path from `agent-browser`. Switch a run to a Browserbase session when the local browser hits:

- CAPTCHAs: reCAPTCHA, hCaptcha, Turnstile
- Bot-detection pages: "Checking your browser...", Cloudflare interstitials
- HTTP 403/429, or empty pages on sites that should have content
- Geo blocks that need residential proxies (201 countries, geo-targeting)
- Sites that require a Verified browser via Browserbase Identity
- Auth that must persist across sessions in the cloud (Browserbase contexts)
- The user asks for it

Don't escalate for simple sites (docs, wikis, public APIs) or localhost - stay on `agent-browser`.

## Setup check

Before running any browser commands, verify the CLI is available:

```bash
which browse || npm install -g @browserbasehq/browse-cli
```

**Warning**: the bare `browse` package on the npm registry is a different CLI. Always install `@browserbasehq/browse-cli`; it provides the `browse` binary.

Remote sessions need credentials from https://browserbase.com/settings:

```bash
export BROWSERBASE_API_KEY="bb_live_..."
```

## Starting a session

browse-cli 0.6.x is environment-based - there is no `--remote` flag on `open`:

- `browse env` shows the current environment; with `BROWSERBASE_API_KEY` set, Browserbase (`remote`) is the default desired mode
- `browse env remote` switches to Browserbase explicitly; `browse env local` switches back to an isolated local browser
- Then plain driver commands run in the cloud session: `browse open <url>`
- Remote-only session flags (global, e.g. `browse --proxies --region eu-central-1 open <url>`): `--proxies`, `--advanced-stealth`, `--solve-captchas` / `--no-solve-captchas`, `--block-ads`, `--region <us-west-2|us-east-1|eu-central-1|ap-southeast-1>`, `--keep-alive`, `--session-timeout <seconds>`, `--connect <session-id>` (attach to an existing session by ID)
- For persistent auth across sessions: `browse open <url> --context-id <ctx-id>` loads a Browserbase context's saved state; add `--persist` to save changes back when the session ends (remote mode only)

## Commands

Driver commands work against the Browserbase session once the daemon starts.

### Navigation
```bash
browse open <url>                         # Go to URL (in the current env's session)
browse open <url> --wait networkidle      # wait for network to settle (SPAs)
browse reload                            # Reload current page
browse back                              # Go back in history
browse forward                           # Go forward in history
```

### Page state (prefer snapshot over screenshot)
```bash
browse snapshot                          # Get accessibility tree with element refs (fast, structured)
browse snapshot --compact                # tree only, no xpath map
browse screenshot <path>                 # Take visual screenshot (slow, uses vision tokens)
browse screenshot <path> --full-page     # entire scrollable page
browse get url                           # Get current URL
browse get title                         # Get page title
browse get markdown                      # Page content as markdown
browse get text <selector>               # Get text content (use "body" for all text)
browse get html <selector>               # Get HTML content of element
browse get value <selector>              # Get form field value
```

Use `browse snapshot` as your default for understanding page state - it returns the accessibility tree with element refs you can use to interact. Only use `browse screenshot` when you need visual context (layout, images, debugging).

### Interaction
```bash
browse click <ref>                       # Click by ref from snapshot (e.g., @0-5) or CSS/XPath selector
browse type <text>                       # Type text into focused element
browse fill <selector> <value>           # Fill input; presses Enter by default
browse fill <selector> <value> --no-press-enter   # fill without submitting
browse select <selector> <values...>     # Select dropdown option(s)
browse press <key>                       # Press key (Enter, Tab, Escape, Cmd+A, etc.)
browse drag <fromX> <fromY> <toX> <toY>  # Drag from one point to another
browse scroll <x> <y> <deltaX> <deltaY>  # Scroll at coordinates
browse highlight <selector>              # Highlight element on page
browse is visible <selector>             # Check if element is visible
browse is checked <selector>             # Check if element is checked
browse wait <type> [arg]                 # Wait for: load, selector, timeout
```

`fill` pressing Enter by default means a filled search box submits itself - pass `--no-press-enter` on any form field where an implicit submit would be wrong.

### Session management
```bash
browse stop                              # Stop the browser daemon (ends the session)
browse stop --force                      # force-kill if unresponsive
browse status                            # Check daemon status and resolved mode
browse pages                             # List all open tabs (index, url, targetId)
browse switch <index>                    # Switch to tab by index
browse close [index]                     # Close tab (defaults to last)
browse newpage [url]                     # Create a new tab
```

### Typical workflow

1. `browse env remote` - select Browserbase (or rely on the API-key default)
2. `browse open <url>` - navigate to the page in a Browserbase session
3. `browse snapshot` - read the accessibility tree to understand page structure and get element refs
4. `browse click <ref>` / `browse type <text>` / `browse fill <selector> <value>` - interact using refs from snapshot
5. `browse snapshot` - confirm the action worked
6. Repeat 4-5 as needed
7. `browse stop` - end the session when done

## Quick Example

```bash
browse env remote                         # use Browserbase (needs BROWSERBASE_API_KEY)
browse open https://example.com
browse snapshot                          # see page structure + element refs
browse click @0-5                        # click element with ref 0-5

From vanducng/skills, MIT.

More from vanducng/skills