# npm (recommended)
npm install -g agent-browser
agent-browser install   # downloads Chrome for Testing

# homebrew
brew install agent-browser && agent-browser install

# cargo
cargo install agent-browser && agent-browser install

# Linux — also install system deps
agent-browser install --with-deps

agent-browser open https://example.com
agent-browser snapshot -i          # interactive elements only
# Output:
#   - heading "Example" [ref=e1]
#   - link "More info" [ref=e2]
#   - button "Submit" [ref=e3]

agent-browser click @e3            # click Submit

agent-browser open <url>
agent-browser back | forward | reload

agent-browser snapshot              # full accessibility tree
agent-browser snapshot -i           # interactive elements only (buttons, inputs, links)
agent-browser snapshot -c           # compact (remove empty nodes)
agent-browser snapshot -d 3         # limit depth
agent-browser snapshot -s "#main"   # scope to selector
agent-browser snapshot --json       # machine-readable

agent-browser click <ref|selector>
agent-browser fill <ref> "text"         # clear + type (for inputs)
agent-browser type <ref> "text"         # type without clearing
agent-browser select <ref> "option"     # dropdown
agent-browser check|uncheck <ref>       # checkbox
agent-browser hover <ref>
agent-browser press Enter|Tab|Escape    # keyboard
agent-browser press Control+a           # key combo
agent-browser scroll down 500           # scroll page
agent-browser upload <ref> file.pdf     # file upload

agent-browser get text <ref>        # element text
agent-browser get html <ref>        # innerHTML
agent-browser get value <ref>       # input value
agent-browser get attr <ref> href   # attribute
agent-browser get title             # page title
agent-browser get url               # current URL

agent-browser screenshot [path]         # to file or temp
agent-browser screenshot --full         # full page scroll capture
agent-browser screenshot --annotate     # numbered labels matching refs
agent-browser pdf output.pdf

agent-browser wait <ref>                    # wait for element visible
agent-browser wait 2000                     # wait ms
agent-browser wait --load networkidle       # wait for network idle
agent-browser wait --url "**/dashboard"     # wait for URL pattern
agent-browser wait --text "Success"         # wait for text
agent-browser wait <ref> --state hidden     # wait for element to disappear

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 placeholder "Search" fill "query"
agent-browser find testid "login-btn" click

agent-browser session list              # active sessions
agent-browser --session myapp <cmd>     # named session
agent-browser close                     # close current
agent-browser close --all               # close all

agent-browser tab                   # list tabs
agent-browser tab new [url]         # new tab
agent-browser tab 2                 # switch to tab 2
agent-browser tab close

# 1. Navigate
agent-browser open https://target.com

# 2. Observe (snapshot → LLM reads → decides action)
agent-browser snapshot -i --json

# 3. Act (LLM picks ref from snapshot)
agent-browser fill @e2 "search query"
agent-browser click @e3

# 4. Wait for result
agent-browser wait --load networkidle

# 5. Re-observe (new snapshot after DOM changed)
agent-browser snapshot -i --json

# 6. Extract or continue
agent-browser get text @e5

cat << 'EOF' | agent-browser batch --json
[
  ["open", "https://example.com/login"],
  ["fill", "@e1", "user@example.com"],
  ["fill", "@e2", "password123"],
  ["click", "@e3"],
  ["wait", "--load", "networkidle"],
  ["screenshot", "result.png"]
]
EOF

# Save credentials (encrypted vault — LLM never sees password)
echo "pass" | agent-browser auth save myapp \
  --url https://app.example.com/login \
  --username user@example.com --password-stdin

# Login with saved creds
agent-browser auth login myapp

# Auto-persist session (cookies, localStorage, IndexedDB)
agent-browser --session-name myapp open https://app.example.com
# ... interact ...
agent-browser close   # state auto-saved to ~/.agent-browser/sessions/

# Next run — auto-restored, already logged in
agent-browser --session-name myapp open https://app.example.com/dashboard

agent-browser state save auth.json
agent-browser state load auth.json

agent-browser network requests                  # list tracked requests
agent-browser network requests --type xhr,fetch # filter
agent-browser network route "**/analytics" --abort    # block tracking
agent-browser network route "**/api/*" --body '{"mock":true}'  # mock response
agent-browser network har start && agent-browser network har stop output.har

agent-browser set device "iPhone 14"
agent-browser set viewport 1920 1080        # desktop
agent-browser set viewport 1920 1080 2      # retina
agent-browser set media dark                # dark mode
agent-browser set geo 52.2297 21.0122       # Warsaw

AGENT_BROWSER_SESSION=myapp           # default session
AGENT_BROWSER_HEADED=1                # show browser window
AGENT_BROWSER_EXECUTABLE_PATH=/path   # custom Chrome
AGENT_BROWSER_PROXY=http://host:port  # proxy
AGENT_BROWSER_DEFAULT_TIMEOUT=25000   # operation timeout (max 30000)
AGENT_BROWSER_IDLE_TIMEOUT_MS=60000   # daemon auto-shutdown
AGENT_BROWSER_ENCRYPTION_KEY=<64hex>  # encrypt state files
AGENT_BROWSER_ALLOWED_DOMAINS=a.com,b.com  # restrict navigation
AGENT_BROWSER_MAX_OUTPUT=50000        # truncate output (prevent context flooding)

{
  "headed": false,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "screenshotDir": "./shots",
  "colorScheme": "dark"
}

--content-boundaries          # wrap untrusted page content in markers
--max-output 50000            # prevent context window flooding
--allowed-domains a.com,b.com # restrict navigation to trusted domains
--action-policy policy.json   # gate destructive actions
--confirm-actions eval,download  # require approval for sensitive ops