--- name: interact-with-browser description: a CLI for intearcting with browser license: MIT compatibility: opencode metadata: audience: testing --- BE SURE TO CLEAN UP SCREEN SHOTS AFTER YOU ARE DONE WITH EVERYTHING IF THIS NEEDS TO BE INSTALLED ``` npm install -g agent-browser agent-browser install # to get chromium downloaded ``` agent-browser open example.com agent-browser snapshot # Get accessibility tree with refs agent-browser click @e2 # Click by ref from snapshot agent-browser fill @e3 "test@example.com" # Fill by ref agent-browser get text @e1 # Get text by ref agent-browser screenshot page.png agent-browser close Traditional Selectors (also supported) agent-browser click "#submit" agent-browser fill "#email" "test@example.com" agent-browser find role button click --name "Submit" Commands Core Commands agent-browser open # Navigate to URL (aliases: goto, navigate) agent-browser click # Click element agent-browser dblclick # Double-click element agent-browser focus # Focus element agent-browser type # Type into element agent-browser fill # Clear and fill agent-browser press # Press key (Enter, Tab, Control+a) (alias: key) agent-browser keydown # Hold key down agent-browser keyup # Release key agent-browser hover # Hover element agent-browser select # Select dropdown option agent-browser check # Check checkbox agent-browser uncheck # Uncheck checkbox agent-browser scroll [px] # Scroll (up\/down\/left\/right) agent-browser scrollintoview # Scroll element into view (alias: scrollinto) agent-browser drag # Drag and drop agent-browser upload # Upload files agent-browser screenshot [path] # Take screenshot (--full for full page) agent-browser pdf # Save as PDF agent-browser snapshot # Accessibility tree with refs (best for AI) agent-browser eval # Run JavaScript agent-browser close # Close browser (aliases: quit, exit) Get Info agent-browser get text # Get text content agent-browser get html # Get innerHTML agent-browser get value # Get input value agent-browser get attr # Get attribute agent-browser get title # Get page title agent-browser get url # Get current URL agent-browser get count # Count matching elements agent-browser get box # Get bounding box Check State agent-browser is visible # Check if visible agent-browser is enabled # Check if enabled agent-browser is checked # Check if checked Find Elements (Semantic Locators) agent-browser find role [value] # By ARIA role agent-browser find text # By text content agent-browser find label [value] # By label agent-browser find placeholder [value] # By placeholder agent-browser find alt # By alt text agent-browser find title # By title attr agent-browser find testid [value] # By data-testid agent-browser find first [value] # First match agent-browser find last [value] # Last match agent-browser find nth [value] # Nth match Actions: click, fill, check, hover, text Examples: agent-browser find role button click --name "Submit" agent-browser find text "Sign In" click agent-browser find label "Email" fill "test@test.com" agent-browser find first ".item" click agent-browser find nth 2 "a" text Wait agent-browser wait # Wait for element to be visible agent-browser wait # Wait for time (milliseconds) agent-browser wait --text "Welcome" # Wait for text to appear agent-browser wait --url "**\/dash" # Wait for URL pattern agent-browser wait --load networkidle # Wait for load state agent-browser wait --fn "window.ready === true" # Wait for JS condition Load states: load, domcontentloaded, networkidle Mouse Control agent-browser mouse move # Move mouse agent-browser mouse down [button] # Press button (left\/right\/middle) agent-browser mouse up [button] # Release button agent-browser mouse wheel [dx] # Scroll wheel Browser Settings agent-browser set viewport # Set viewport size agent-browser set device # Emulate device ("iPhone 14") agent-browser set geo # Set geolocation agent-browser set offline [on|off] # Toggle offline mode agent-browser set headers # Extra HTTP headers agent-browser set credentials

# HTTP basic auth agent-browser set media [dark|light] # Emulate color scheme Cookies & Storage agent-browser cookies # Get all cookies agent-browser cookies set # Set cookie agent-browser cookies clear # Clear cookies agent-browser storage local # Get all localStorage agent-browser storage local # Get specific key agent-browser storage local set # Set value agent-browser storage local clear # Clear all agent-browser storage session # Same for sessionStorage Network agent-browser network route # Intercept requests agent-browser network route --abort # Block requests agent-browser network route --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 & Windows agent-browser tab # List tabs agent-browser tab new [url] # New tab (optionally with URL) agent-browser tab # Switch to tab n agent-browser tab close [n] # Close tab agent-browser window new # New window Frames agent-browser frame # Switch to iframe agent-browser frame main # Back to main frame Dialogs agent-browser dialog accept [text] # Accept (with optional prompt text) agent-browser dialog dismiss # Dismiss Debug agent-browser trace start [path] # Start recording trace agent-browser trace stop [path] # Stop and save trace 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 # Highlight element agent-browser state save # Save auth state agent-browser state load # Load auth state Navigation agent-browser back # Go back agent-browser forward # Go forward agent-browser reload # Reload page Setup agent-browser install # Download Chromium browser agent-browser install --with-deps # Also install system deps (Linux) Sessions Run multiple isolated browser instances: # Different sessions agent-browser --session agent1 open site-a.com agent-browser --session agent2 open site-b.com # Or via environment variable AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn" # List active sessions agent-browser session list # Output: # Active sessions: # -> default # agent1 # Show current session agent-browser session Each session has its own: Browser instance Cookies and storage Navigation history Authentication state Snapshot Options The snapshot command supports filtering to reduce output size: agent-browser snapshot # Full accessibility tree agent-browser snapshot -i # Interactive elements only (buttons, inputs, links) agent-browser snapshot -c # Compact (remove empty structural elements) agent-browser snapshot -d 3 # Limit depth to 3 levels agent-browser snapshot -s "#main" # Scope to CSS selector agent-browser snapshot -i -c -d 5 # Combine options Option Description -i, --interactive Only show interactive elements (buttons, links, inputs) -c, --compact Remove empty structural elements -d, --depth Limit tree depth -s, --selector Scope to CSS selector Options Option Description --session Use isolated session (or AGENT_BROWSER_SESSION env) --headers Set HTTP headers scoped to the URL's origin --executable-path Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH env) --json JSON output (for agents) --full, -f Full page screenshot --name, -n Locator name filter --exact Exact text match --headed Show browser window (not headless) --cdp Connect via Chrome DevTools Protocol --debug Debug output Selectors Refs (Recommended for AI) Refs provide deterministic element selection from snapshots: # 1. Get snapshot with refs agent-browser snapshot # Output: # - heading "Example Domain" [ref=e1] [level=1] # - button "Submit" [ref=e2] # - textbox "Email" [ref=e3] # - link "Learn more" [ref=e4] # 2. Use refs to interact agent-browser click @e2 # Click the button agent-browser fill @e3 "test@example.com" # Fill the textbox agent-browser get text @e1 # Get heading text agent-browser hover @e4 # Hover the link Why use refs? Deterministic: Ref points to exact element from snapshot Fast: No DOM re-query needed AI-friendly: Snapshot + ref workflow is optimal for LLMs CSS Selectors agent-browser click "#id" agent-browser click ".class" agent-browser click "div > button" Text & XPath agent-browser click "text=Submit" agent-browser click "xpath=\/\/button" Semantic Locators agent-browser find role button click --name "Submit" agent-browser find label "Email" fill "test@test.com" Agent Mode Use --json for machine-readable output: agent-browser snapshot --json # Returns: {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}} agent-browser get text @e1 --json agent-browser is visible @e2 --json Optimal AI Workflow # 1. Navigate and get snapshot agent-browser open example.com agent-browser snapshot -i --json # AI parses tree and refs # 2. AI identifies target refs from snapshot # 3. Execute actions using refs agent-browser click @e2 agent-browser fill @e3 "input text" # 4. Get new snapshot if page changed agent-browser snapshot -i --json Headed Mode Show the browser window for debugging: agent-browser open example.com --headed This opens a visible browser window instead of running headless. Authenticated Sessions Use --headers to set HTTP headers for a specific origin, enabling authentication without login flows: # Headers are scoped to api.example.com only agent-browser open api.example.com --headers '{"Authorization": "Bearer "}' # Requests to api.example.com include the auth header agent-browser snapshot -i --json agent-browser click @e2 # Navigate to another domain - headers are NOT sent (safe!) agent-browser open other-site.com This is useful for: Skipping login flows - Authenticate via headers instead of UI Switching users - Start new sessions with different auth tokens API testing - Access protected endpoints directly Security - Headers are scoped to the origin, not leaked to other domains To set headers for multiple origins, use --headers with each open command: agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}' agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}' For global headers (all domains), use set headers: agent-browser set headers '{"X-Custom-Header": "value"}' Custom Browser Executable Use a custom browser executable instead of the bundled Chromium. This is useful for: Serverless deployment: Use lightweight Chromium builds like @sparticuz\/chromium (~50MB vs ~684MB) System browsers: Use an existing Chrome\/Chromium installation Custom builds: Use modified browser builds CLI Usage # Via flag agent-browser --executable-path \/path\/to\/chromium open example.com # Via environment variable AGENT_BROWSER_EXECUTABLE_PATH=\/path\/to\/chromium agent-browser open example.com Serverless Example (Vercel\/AWS Lambda) import chromium from '@sparticuz\/chromium'; import { BrowserManager } from 'agent-browser'; export async function handler() { const browser = new BrowserManager(); await browser.launch({ executablePath: await chromium.executablePath(), headless: true, }); \/\/ ... use browser }