Quick Start#

Core workflow#

Every browser automation follows this pattern:

# 1. Navigate
agent-browser open example.com

# 2. Snapshot to get element refs
agent-browser snapshot -i
# Output:
# @e1 [heading] "Example Domain"
# @e2 [link] "More information..."

# 3. Interact using refs
agent-browser click @e2

# 4. Re-snapshot after page changes
agent-browser snapshot -i

Common commands#

agent-browser open example.com
agent-browser snapshot -i                # Get interactive elements with refs
agent-browser click @e2                  # Click by ref
agent-browser fill @e3 "test@example.com" # Fill input by ref
agent-browser get text @e1               # Get text content
agent-browser screenshot                 # Save to temp directory
agent-browser screenshot page.png        # Save to specific path
agent-browser close

Traditional selectors#

CSS selectors and semantic locators also supported:

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"

Headed mode#

Show browser window for debugging:

agent-browser open example.com --headed

Wait for content#

agent-browser wait @e1                   # Wait for element
agent-browser wait --text "Welcome"      # Wait for expected text
agent-browser wait --url "**/dashboard"  # Wait for URL pattern
agent-browser wait --fn "window.appReady === true" # Wait for JS condition
agent-browser wait --load domcontentloaded # Wait for the DOM lifecycle event

After a page change, prefer the condition that represents the result you need. Use load or domcontentloaded only when the lifecycle event is the milestone. networkidle remains available for pages known to become quiet, but SSE, WebSockets, polling, and long-polling can keep it from resolving.

Command chaining#

Chain commands with && in a single shell call. The browser persists via a background daemon, so chaining is safe and efficient:

# Open, wait, and snapshot in one call
agent-browser open example.com && agent-browser wait --load domcontentloaded && agent-browser snapshot -i

# Chain multiple interactions
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3

# Navigate and capture
agent-browser open example.com && agent-browser wait --load load && agent-browser screenshot page.png

Use && when you don't need intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs before interacting).

JSON output#

For programmatic parsing in scripts:

agent-browser snapshot --json
agent-browser get text @e1 --json

Note: The default text output is more compact and preferred for AI agents.