/browser

Name

browser

Description

Automate browser interactions using agent-browser CLI — navigate, click, fill forms, scrape content, take screenshots, and more.

Allowed Tools

Bash(npx agent-browser *)

argument-hint

<command> [args...]

# Browser Automation with agent-browser

Control a headless Chromium browser via CLI commands. All commands are run with `npx agent-browser <command>`.

## Setup (first time only)

```bash
npx agent-browser install
```

## Navigation

| Command | Description |
|---|---|
| `open <url>` | Navigate to a URL |
| `close` | Close browser |
| `tab` | List open tabs |
| `tab new [url]` | Open new tab |
| `tab <n>` | Switch to tab n |
| `tab close [n]` | Close tab |
| `window new` | Open new browser window |
| `frame <selector>` | Switch to iframe |
| `frame main` | Return to main frame |

## Page Inspection (use these to understand page structure)

| Command | Description |
|---|---|
| `snapshot` | Get accessibility tree with `@e1`, `@e2` element refs (best for AI) |
| `screenshot [path]` | Capture screenshot |
| `screenshot --full` | Full page screenshot |
| `screenshot --annotate` | Screenshot with numbered element labels |
| `get text <sel>` | Extract text content |
| `get html <sel>` | Get innerHTML |
| `get value <sel>` | Get input value |
| `get attr <sel> <attr>` | Get element attribute |
| `get title` | Get page title |
| `get url` | Get current URL |
| `get count <sel>` | Count matching elements |
| `get box <sel>` | Get bounding box |
| `get styles <sel>` | Get computed styles |
| `is visible <sel>` | Check if element is visible |
| `is enabled <sel>` | Check if element is enabled |
| `is checked <sel>` | Check if checkbox is checked |

## Clicking & Interaction

| Command | Description |
|---|---|
| `click <sel>` | Click an element |
| `click <sel> --new-tab` | Click, opening in new tab |
| `dblclick <sel>` | Double-click |
| `hover <sel>` | Hover over element |
| `focus <sel>` | Focus element |
| `scroll <dir> [px]` | Scroll up/down/left/right |
| `scrollintoview <sel>` | Scroll element into view |
| `drag <src> <tgt>` | Drag and drop |

## Text Input

| Command | Description |
|---|---|
| `fill <sel> <text>` | Clear field and type text |
| `type <sel> <text>` | Type into focused element (appends) |
| `keyboard type <text>` | Type with real keystrokes |
| `keyboard inserttext <text>` | Insert text without key events |
| `press <key>` | Press a key (Enter, Tab, Control+a, etc.) |
| `keydown <key>` | Hold key down |
| `keyup <key>` | Release key |

## Form Controls

| Command | Description |
|---|---|
| `check <sel>` | Check a checkbox |
| `uncheck <sel>` | Uncheck a checkbox |
| `select <sel> <val>` | Select dropdown option |
| `upload <sel> <files>` | Upload file(s) to input |

## Semantic Find (locate elements by meaning, not CSS)

```
find role <role> <action> [value]         # By ARIA role
find text <text> <action>                 # By visible text
find label <label> <action> [value]       # By label
find placeholder <ph> <action> [value]    # By placeholder
find alt <text> <action>                  # By alt text
find title <text> <action>                # By title attribute
find testid <id> <action> [value]         # By data-testid
find first <sel> <action> [value]         # First match
find last <sel> <action> [value]          # Last match
find nth <n> <sel> <action> [value]       # Nth match
```

**Actions:** `click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`

**Options:** `--name <name>` (filter by accessible name), `--exact` (exact match)

**Examples:**
```bash
npx agent-browser find role button click --name "Submit"
npx agent-browser find text "Sign In" click
npx agent-browser find label "Email" fill "user@example.com"
npx agent-browser find placeholder "Search..." fill "vinyl records"
```

## Waiting

| Command | Description |
|---|---|
| `wait <selector>` | Wait for element to appear |
| `wait <ms>` | Wait N milliseconds |
| `wait --text "text"` | Wait for text to appear |
| `wait --url "**/path"` | Wait for URL pattern |
| `wait --load networkidle` | Wait for network idle |
| `wait --fn "window.ready"` | Wait for JS condition |

## Cookies & Storage

| Command | Description |
|---|---|
| `cookies` | Get all cookies |
| `cookies set <name> <val>` | Set a cookie |
| `cookies clear` | Clear cookies |
| `storage local` | Get all localStorage |
| `storage local <key>` | Get localStorage key |
| `storage local set <k> <v>` | Set localStorage value |
| `storage local clear` | Clear localStorage |
| `storage session` | Same commands for sessionStorage |

## Network Interception

| Command | Description |
|---|---|
| `network route <url>` | Intercept requests matching URL |
| `network route <url> --abort` | Block matching requests |
| `network route <url> --body <json>` | Mock response body |
| `network unroute [url]` | Remove intercept routes |
| `network requests` | View tracked requests |
| `network requests --filter <pat>` | Filter requests by pattern |

## JavaScript Execution

| Command | Description |
|---|---|
| `eval <js>` | Run JavaScript in page context |
| `eval -b <base64>` | Run base64-encoded JS |

## Browser Configuration

| Command | Description |
|---|---|
| `set viewport <w> <h>` | Set viewport size |
| `set device <name>` | Emulate device (e.g. "iPhone 14") |
| `set media dark` | Emulate dark color scheme |
| `set media light` | Emulate light color scheme |
| `set offline on` | Enable offline mode |
| `set offline off` | Disable offline mode |
| `set geo <lat> <lng>` | Set geolocation |
| `set headers <json>` | Set extra HTTP headers |
| `set credentials <user> <pass>` | Set HTTP basic auth |

## Mouse Control

| Command | Description |
|---|---|
| `mouse move <x> <y>` | Move cursor to coordinates |
| `mouse down [button]` | Press mouse button |
| `mouse up [button]` | Release mouse button |
| `mouse wheel <dy> [dx]` | Scroll wheel |

## State Persistence

| Command | Description |
|---|---|
| `state save <path>` | Save auth/session state |
| `state load <path>` | Load saved state |
| `state list` | List saved states |
| `state clear [name]` | Clear a saved state |
| `state clear --all` | Clear all saved states |

## Debugging

| Command | Description |
|---|---|
| `console` | View console messages |
| `errors` | View uncaught exceptions |
| `highlight <sel>` | Visually highlight element |
| `trace start [path]` | Start trace recording |
| `trace stop [path]` | Stop and save trace |
| `profiler start` | Start CPU profiling |
| `profiler stop [path]` | Save profile |
| `pdf <path>` | Save page as PDF |

## Comparison & Diffing

| Command | Description |
|---|---|
| `diff snapshot` | Compare current vs previous snapshot |
| `diff snapshot --baseline <file>` | Compare against saved file |
| `diff screenshot --baseline <file>` | Visual pixel comparison |
| `diff url <a> <b>` | Compare two URLs |

## Typical Workflow

1. **Open a page:** `open http://localhost:3000`
2. **Inspect structure:** `snapshot` (returns element refs like `@e1`, `@e2`)
3. **Interact using refs:** `click @e3` or `fill @e5 "my text"`
4. **Verify results:** `get text @e7` or `screenshot`
5. **Close when done:** `close`

## Selectors

Commands accept these selector types:
- **Element refs** from snapshot: `@e1`, `@e2`, etc. (preferred for AI)
- **CSS selectors:** `#id`, `.class`, `div > span`
- **XPath:** `//button[@type="submit"]`
- **Semantic find:** Use the `find` command family above

## Default Login Flow

When testing locally, log in first before performing authenticated browser actions:
- URL: http://localhost:3000/auth
- Use Supabase Auth (email/password)

## Project-Specific Pages

Key pages to test in the MVP boilerplate:

| Page | URL | Notes |
|---|---|---|
| Landing | `http://localhost:3000` | Sections: Navbar, Hero, Logos, Items, Stats, Pricing, FAQ, Cta, Footer |
| Sign In / Sign Up | `http://localhost:3000/auth` | Supabase Auth UI |
| Account | `http://localhost:3000/account` | Authenticated - user profile & subscription |
| Pricing | `http://localhost:3000/#pricing` | Stripe checkout integration |

## Testing Dark Mode

```bash
# Toggle dark mode via the ModeToggle button in the navbar
npx agent-browser find role button click --name "Toggle theme"

# Or force via browser emulation
npx agent-browser set media dark
npx agent-browser set media light
```

## Testing Responsive Design

```bash
# Mobile
npx agent-browser set viewport 375 812

# Tablet
npx agent-browser set viewport 768 1024

# Desktop
npx agent-browser set viewport 1440 900
```