Chris Tate
c201623710
* fix(tabs): initialize tab_id on missing PageInfo sites PR #892 added a required `tab_id: u32` field to `PageInfo` but missed two initializer sites, which broke the build on the PR branch. CI never caught this because the external-contributor workflow status was `action_required` and never ran. - `cli/src/native/browser.rs:395` — the `direct_page` branch of `connect_cdp_inner` used by the cloud providers (Browserbase, Browserless, Browser Use, Kernel, AgentCore). Use `assign_tab_id()` to get a fresh id. - `cli/src/native/browser.rs:1580` — a unit test initializer. Use `tab_id: 1` since the test doesn't exercise id assignment. * feat(tabs): restore active tab and clear per-tab state for scoped --tab Follow-up on PR #892's `--tab <id>` flag. The original implementation called `tab_switch_by_id` directly from the pre-dispatch block in `execute_command` but didn't touch the daemon's per-tab state, and never restored the previously-active tab. Two concrete issues this fixes: 1. `state.ref_map`, `state.iframe_sessions`, and `state.active_frame_id` were left intact across the pre-dispatch switch, so `--tab N click @e1` would try to resolve `@e1` against the scoped tab's DOM using a backend-node id from the outer tab. In practice the click handler's role+name fallback hid this as "element not found" errors, but on pages where both tabs have similarly-labelled elements it could click the wrong one. 2. The PR description promised scoped routing would "restore the previous active tab", but the implementation permanently switched. `--tab 3 snapshot` would leave tab 3 as the active tab even after the command returned, surprising subsequent non-scoped commands. This change: - Saves the current tab's stable `tab_id` (not its array index, which would shift if the scoped command closed other tabs) before switching. - Clears per-tab daemon state before the switch so refs/iframes/frame context can't leak between tabs. - After the action runs, restores the original active tab (also via stable id) unless that tab was closed during the scoped command, in which case we leave the scoped tab active. - Adds `BrowserManager::active_tab_id()` and `has_tab_id()` accessors to support the above without exposing the internal `pages` vector. * test(tabs): regression tests for scoped --tab state clearing and restoration Three new `#[ignore]` e2e tests pinning the fixed behavior: - `e2e_tab_scoped_command_clears_state_on_switch` — populates `ref_map` on tab 1, runs a `tabId: 2`-scoped command, asserts `ref_map`, `iframe_sessions`, and `active_frame_id` are all cleared. - `e2e_tab_scoped_command_restores_active_tab` — sets up two tabs, runs a scoped command against the non-active one, asserts a subsequent unscoped command reflects the originally-active tab. - `e2e_tab_scoped_command_handles_outer_tab_closed` — runs a scoped `tab_close` that kills the outer tab itself, asserts no error and the scoped tab becomes active. Also updates two misleading comments in the PR's existing `e2e_tab_global_targeting*` tests to reflect restoration semantics; the assertions themselves were already consistent with restoration. * docs(tabs): document stable tab IDs and --tab scoped-command flag Per AGENTS.md, changes that users or agents would need to know about must land in every doc surface. Fills the gaps PR #892 left: - `README.md` — new `--tab <id>` row in the Options table, rewrite the tab command examples to use `<id>` instead of `<n>`, add a paragraph explaining stable tab IDs and `--tab` peek semantics. - `docs/src/app/commands/page.mdx` — same command-example rewrite plus a new "Stable tab IDs and `--tab`" subsection. - `docs/src/app/configuration/page.mdx` — add `tab` row to the config options table so JSON config users can discover it. - `agent-browser.schema.json` — add `tab` property with description, matching the config schema. - `skills/agent-browser/references/commands.md` — same command-example rewrite plus a short paragraph for agents on when to use `--tab`.
306 lines
12 KiB
Markdown
306 lines
12 KiB
Markdown
# Command Reference
|
|
|
|
Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md.
|
|
|
|
## Navigation
|
|
|
|
```bash
|
|
agent-browser open <url> # Navigate to URL (aliases: goto, navigate)
|
|
# Supports: https://, http://, file://, about:, data://
|
|
# Auto-prepends https:// if no protocol given
|
|
agent-browser back # Go back
|
|
agent-browser forward # Go forward
|
|
agent-browser reload # Reload page
|
|
agent-browser close # Close browser (aliases: quit, exit)
|
|
agent-browser connect 9222 # Connect to browser via CDP port
|
|
```
|
|
|
|
## Snapshot (page analysis)
|
|
|
|
```bash
|
|
agent-browser snapshot # Full accessibility tree
|
|
agent-browser snapshot -i # Interactive elements only (recommended)
|
|
agent-browser snapshot -c # Compact output
|
|
agent-browser snapshot -d 3 # Limit depth to 3
|
|
agent-browser snapshot -s "#main" # Scope to CSS selector
|
|
```
|
|
|
|
## Interactions (use @refs from snapshot)
|
|
|
|
```bash
|
|
agent-browser click @e1 # Click
|
|
agent-browser click @e1 --new-tab # Click and open in new tab
|
|
agent-browser dblclick @e1 # Double-click
|
|
agent-browser focus @e1 # Focus element
|
|
agent-browser fill @e2 "text" # Clear and type
|
|
agent-browser type @e2 "text" # Type without clearing
|
|
agent-browser press Enter # Press key (alias: key)
|
|
agent-browser press Control+a # Key combination
|
|
agent-browser keydown Shift # Hold key down
|
|
agent-browser keyup Shift # Release key
|
|
agent-browser hover @e1 # Hover
|
|
agent-browser check @e1 # Check checkbox
|
|
agent-browser uncheck @e1 # Uncheck checkbox
|
|
agent-browser select @e1 "value" # Select dropdown option
|
|
agent-browser select @e1 "a" "b" # Select multiple options
|
|
agent-browser scroll down 500 # Scroll page (default: down 300px)
|
|
agent-browser scrollintoview @e1 # Scroll element into view (alias: scrollinto)
|
|
agent-browser drag @e1 @e2 # Drag and drop
|
|
agent-browser upload @e1 file.pdf # Upload files
|
|
```
|
|
|
|
## Get Information
|
|
|
|
```bash
|
|
agent-browser get text @e1 # Get element text
|
|
agent-browser get html @e1 # Get innerHTML
|
|
agent-browser get value @e1 # Get input value
|
|
agent-browser get attr @e1 href # Get attribute
|
|
agent-browser get title # Get page title
|
|
agent-browser get url # Get current URL
|
|
agent-browser get cdp-url # Get CDP WebSocket URL
|
|
agent-browser get count ".item" # Count matching elements
|
|
agent-browser get box @e1 # Get bounding box
|
|
agent-browser get styles @e1 # Get computed styles (font, color, bg, etc.)
|
|
```
|
|
|
|
## Check State
|
|
|
|
```bash
|
|
agent-browser is visible @e1 # Check if visible
|
|
agent-browser is enabled @e1 # Check if enabled
|
|
agent-browser is checked @e1 # Check if checked
|
|
```
|
|
|
|
## Screenshots and PDF
|
|
|
|
```bash
|
|
agent-browser screenshot # Save to temporary directory
|
|
agent-browser screenshot path.png # Save to specific path
|
|
agent-browser screenshot --full # Full page
|
|
agent-browser pdf output.pdf # Save as PDF
|
|
```
|
|
|
|
## Video Recording
|
|
|
|
```bash
|
|
agent-browser record start ./demo.webm # Start recording
|
|
agent-browser click @e1 # Perform actions
|
|
agent-browser record stop # Stop and save video
|
|
agent-browser record restart ./take2.webm # Stop current + start new
|
|
```
|
|
|
|
## Wait
|
|
|
|
```bash
|
|
agent-browser wait @e1 # Wait for element
|
|
agent-browser wait 2000 # Wait milliseconds
|
|
agent-browser wait --text "Success" # Wait for text (or -t)
|
|
agent-browser wait --url "**/dashboard" # Wait for URL pattern (or -u)
|
|
agent-browser wait --load networkidle # Wait for network idle (or -l)
|
|
agent-browser wait --fn "window.ready" # Wait for JS condition (or -f)
|
|
```
|
|
|
|
## Mouse Control
|
|
|
|
```bash
|
|
agent-browser mouse move 100 200 # Move mouse
|
|
agent-browser mouse down left # Press button
|
|
agent-browser mouse up left # Release button
|
|
agent-browser mouse wheel 100 # Scroll wheel
|
|
```
|
|
|
|
## Semantic Locators (alternative to refs)
|
|
|
|
```bash
|
|
agent-browser find role button click --name "Submit"
|
|
agent-browser find text "Sign In" click
|
|
agent-browser find text "Sign In" click --exact # Exact match only
|
|
agent-browser find label "Email" fill "user@test.com"
|
|
agent-browser find placeholder "Search" type "query"
|
|
agent-browser find alt "Logo" click
|
|
agent-browser find title "Close" click
|
|
agent-browser find testid "submit-btn" click
|
|
agent-browser find first ".item" click
|
|
agent-browser find last ".item" click
|
|
agent-browser find nth 2 "a" hover
|
|
```
|
|
|
|
## Browser Settings
|
|
|
|
```bash
|
|
agent-browser set viewport 1920 1080 # Set viewport size
|
|
agent-browser set viewport 1920 1080 2 # 2x retina (same CSS size, higher res screenshots)
|
|
agent-browser set device "iPhone 14" # Emulate device
|
|
agent-browser set geo 37.7749 -122.4194 # Set geolocation (alias: geolocation)
|
|
agent-browser set offline on # Toggle offline mode
|
|
agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers
|
|
agent-browser set credentials user pass # HTTP basic auth (alias: auth)
|
|
agent-browser set media dark # Emulate color scheme
|
|
agent-browser set media light reduced-motion # Light mode + reduced motion
|
|
```
|
|
|
|
## Cookies and Storage
|
|
|
|
```bash
|
|
agent-browser cookies # Get all cookies
|
|
agent-browser cookies set name value # Set cookie
|
|
agent-browser cookies clear # Clear cookies
|
|
agent-browser storage local # Get all localStorage
|
|
agent-browser storage local key # Get specific key
|
|
agent-browser storage local set k v # Set value
|
|
agent-browser storage local clear # Clear all
|
|
```
|
|
|
|
## Network
|
|
|
|
```bash
|
|
agent-browser network route <url> # Intercept requests
|
|
agent-browser network route <url> --abort # Block requests
|
|
agent-browser network route <url> --body '{}' # Mock response
|
|
agent-browser network unroute [url] # Remove routes
|
|
agent-browser network requests # View tracked requests
|
|
agent-browser network requests --filter api # Filter requests
|
|
```
|
|
|
|
## Tabs and Windows
|
|
|
|
```bash
|
|
agent-browser tab # List tabs (each row includes a stable tabId)
|
|
agent-browser tab new [url] # New tab
|
|
agent-browser tab 2 # Switch to tab by tabId
|
|
agent-browser tab close # Close current tab
|
|
agent-browser tab close 2 # Close tab by tabId
|
|
agent-browser window new # New window
|
|
```
|
|
|
|
Tab IDs are stable and never reused within a session, so the same `tabId` keeps
|
|
referring to the same tab even when other tabs are opened or closed. For a
|
|
non-intrusive peek at another tab, use the global `--tab <id>` flag; the
|
|
active tab is restored after the command:
|
|
|
|
```bash
|
|
agent-browser --tab 1 snapshot # snapshot tab 1 without switching
|
|
agent-browser --tab 3 click @e1 # click @e1 on tab 3 and return
|
|
```
|
|
|
|
## Frames
|
|
|
|
```bash
|
|
agent-browser frame "#iframe" # Switch to iframe by CSS selector
|
|
agent-browser frame @e3 # Switch to iframe by element ref
|
|
agent-browser frame main # Back to main frame
|
|
```
|
|
|
|
### Iframe support
|
|
|
|
Iframes are detected automatically during snapshots. When the main-frame snapshot runs, `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the output (one level of nesting; iframes within iframes are not expanded).
|
|
|
|
```bash
|
|
agent-browser snapshot -i
|
|
# @e3 [Iframe] "payment-frame"
|
|
# @e4 [input] "Card number"
|
|
# @e5 [button] "Pay"
|
|
|
|
# Interact directly — refs inside iframes already work
|
|
agent-browser fill @e4 "4111111111111111"
|
|
agent-browser click @e5
|
|
|
|
# Or switch frame context for scoped snapshots
|
|
agent-browser frame @e3 # Switch using element ref
|
|
agent-browser snapshot -i # Snapshot scoped to that iframe
|
|
agent-browser frame main # Return to main frame
|
|
```
|
|
|
|
The `frame` command accepts:
|
|
- **Element refs** — `frame @e3` resolves the ref to an iframe element
|
|
- **CSS selectors** — `frame "#payment-iframe"` finds the iframe by selector
|
|
- **Frame name/URL** — matches against the browser's frame tree
|
|
|
|
## Dialogs
|
|
|
|
By default, `alert` and `beforeunload` dialogs are automatically accepted so they never block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` to disable this behavior.
|
|
|
|
```bash
|
|
agent-browser dialog accept [text] # Accept dialog
|
|
agent-browser dialog dismiss # Dismiss dialog
|
|
agent-browser dialog status # Check if a dialog is currently open
|
|
```
|
|
|
|
## JavaScript
|
|
|
|
```bash
|
|
agent-browser eval "document.title" # Simple expressions only
|
|
agent-browser eval -b "<base64>" # Any JavaScript (base64 encoded)
|
|
agent-browser eval --stdin # Read script from stdin
|
|
```
|
|
|
|
Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone.
|
|
|
|
```bash
|
|
# Base64 encode your script, then:
|
|
agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="
|
|
|
|
# Or use stdin with heredoc for multiline scripts:
|
|
cat <<'EOF' | agent-browser eval --stdin
|
|
const links = document.querySelectorAll('a');
|
|
Array.from(links).map(a => a.href);
|
|
EOF
|
|
```
|
|
|
|
## State Management
|
|
|
|
```bash
|
|
agent-browser state save auth.json # Save cookies, storage, auth state
|
|
agent-browser state load auth.json # Restore saved state
|
|
```
|
|
|
|
## Global Options
|
|
|
|
```bash
|
|
agent-browser --session <name> ... # Isolated browser session
|
|
agent-browser --json ... # JSON output for parsing
|
|
agent-browser --headed ... # Show browser window (not headless)
|
|
agent-browser --full ... # Full page screenshot (-f)
|
|
agent-browser --cdp <port> ... # Connect via Chrome DevTools Protocol
|
|
agent-browser -p <provider> ... # Cloud browser provider (--provider)
|
|
agent-browser --proxy <url> ... # Use proxy server
|
|
agent-browser --proxy-bypass <hosts> # Hosts to bypass proxy
|
|
agent-browser --headers <json> ... # HTTP headers scoped to URL's origin
|
|
agent-browser --executable-path <p> # Custom browser executable
|
|
agent-browser --extension <path> ... # Load browser extension (repeatable)
|
|
agent-browser --ignore-https-errors # Ignore SSL certificate errors
|
|
agent-browser --help # Show help (-h)
|
|
agent-browser --version # Show version (-V)
|
|
agent-browser <command> --help # Show detailed help for a command
|
|
```
|
|
|
|
## Debugging
|
|
|
|
```bash
|
|
agent-browser --headed open example.com # Show browser window
|
|
agent-browser --cdp 9222 snapshot # Connect via CDP port
|
|
agent-browser connect 9222 # Alternative: connect command
|
|
agent-browser console # View console messages
|
|
agent-browser console --clear # Clear console
|
|
agent-browser errors # View page errors
|
|
agent-browser errors --clear # Clear errors
|
|
agent-browser highlight @e1 # Highlight element
|
|
agent-browser inspect # Open Chrome DevTools for this session
|
|
agent-browser trace start # Start recording trace
|
|
agent-browser trace stop trace.zip # Stop and save trace
|
|
agent-browser profiler start # Start Chrome DevTools profiling
|
|
agent-browser profiler stop trace.json # Stop and save profile
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
AGENT_BROWSER_SESSION="mysession" # Default session name
|
|
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path
|
|
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # Comma-separated extension paths
|
|
AGENT_BROWSER_PROVIDER="browserbase" # Cloud browser provider
|
|
AGENT_BROWSER_STREAM_PORT="9223" # Override WebSocket streaming port (default: OS-assigned)
|
|
AGENT_BROWSER_HOME="/path/to/agent-browser" # Custom install location
|
|
```
|