@dyyz1993/agent-browser 0.9.2

package/skills/agent-browser/references/commands.md

@@ -0,0 +1,471 @@
+# 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
+agent-browser snapshot -s "body" --path   # Include xpath and cssPath in refs
+agent-browser snapshot -s "body" --attrs  # Include element attributes in refs
+```
+
+### Path and Attributes Options
+
+When you need element paths or attributes, use `--path` and `--attrs`:
+
+```bash
+# Get xpath and cssPath for elements (can use without --selector)
+agent-browser snapshot --path
+agent-browser snapshot -s "body" --path
+
+# Get element attributes (id, class, href, etc.)
+agent-browser snapshot --attrs
+agent-browser snapshot -s "body" --attrs
+
+# Get both
+agent-browser snapshot --path --attrs
+agent-browser snapshot -s "body" --path --attrs
+```
+
+**Note:** Using `--selector` is optional but recommended to limit scope and prevent large responses.
+
+**Response example with --path --attrs:**
+```json
+{
+  "refs": {
+    "e1": {
+      "role": "button",
+      "name": "Submit",
+      "xpath": "//*[@id=\"submit-btn\"]",
+      "cssPath": "#submit-btn",
+      "attributes": {"id": "submit-btn", "class": "btn-primary", "type": "submit"}
+    }
+  }
+}
+```
+
+## Interactions (use @refs from snapshot)
+
+```bash
+agent-browser click @e1           # Click
+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
+agent-browser download @e1 ./file.pdf  # Download file by clicking element
+```
+
+### Human-like Mouse Movement
+
+Enable globally via environment variable to simulate natural mouse trajectories:
+
+```bash
+# Enable human mode (default: arc path type)
+export AGENT_BROWSER_HUMAN=1
+
+# Or specify path type
+export AGENT_BROWSER_HUMAN=bezier   # Bezier curve with overshoot
+export AGENT_BROWSER_HUMAN=arc      # Smooth arc (default, most natural)
+export AGENT_BROWSER_HUMAN=random   # Random path with jitter
+export AGENT_BROWSER_HUMAN=linear   # Straight line (fastest)
+
+# All interactions will use human-like movement
+agent-browser click @e1
+agent-browser fill @e1 "text"
+agent-browser type @e1 "text"
+agent-browser hover @e1
+agent-browser dblclick @e1
+
+# Wait with mouse wandering (when human mode enabled)
+agent-browser wait 3000  # Wanders mouse while waiting
+
+# Disable human mode
+unset AGENT_BROWSER_HUMAN
+```
+
+**Trajectory Types:**
+| Type | Description | Best For |
+|------|-------------|----------|
+| `arc` | Smooth arc trajectory (default) | Most natural, general use |
+| `bezier` | Bezier curve with overshoot | Realistic targeting |
+| `random` | Random path with jitter | Maximum unpredictability |
+| `linear` | Straight line | Fastest, less detection needed |
+
+**Affected Commands:**
+| Command | Human Mode Effect |
+|---------|-------------------|
+| `click` | Human-like mouse trajectory + click |
+| `dblclick` | Human-like mouse trajectory + double-click |
+| `fill` | Human-like mouse trajectory + character-by-character typing |
+| `type` | Human-like mouse trajectory + character-by-character typing |
+| `hover` | Human-like mouse trajectory |
+| `wait <ms>` | Random mouse wandering while waiting |
+
+## 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 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
+```
+
+**Important:** `first`, `last`, `nth` are locators for the `find` command, NOT CSS selectors. Do NOT use them directly with `click`, `fill`, etc.
+
+```bash
+# WRONG - "first" is not a CSS selector
+agent-browser click "first .item"      # Will fail!
+
+# CORRECT - Use find command with first locator
+agent-browser find first ".item" click
+
+# ALTERNATIVE - Use CSS pseudo-class selectors
+agent-browser click ".item:first-of-type"
+agent-browser click ".item:last-of-type"
+agent-browser click ".item:nth-of-type(2)"
+```
+
+## Browser Settings
+
+```bash
+agent-browser set viewport 1920 1080          # Set viewport size
+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
+
+# Wait for API request and capture response
+agent-browser wait --request "api/users"       # Wait for matching request
+agent-browser wait --request "aweme/post" --timeout 30000  # With timeout
+```
+
+## Tabs
+
+```bash
+agent-browser tab                 # List tabs
+agent-browser tab new [url]       # New tab
+agent-browser tab 2               # Switch to tab by index
+agent-browser tab close           # Close current tab
+agent-browser tab close 2         # Close tab by index
+```
+
+Note: `window new` command exists but creates a new browser window context.
+
+## Iframes (--in-frame option)
+
+Use `--in-frame` option to operate inside iframes. There is no separate `frame` command.
+
+```bash
+# Single iframe by ID or name
+agent-browser snapshot --in-frame "#my-iframe"
+agent-browser click @e1 --in-frame "#login-frame"
+agent-browser fill #username "admin" --in-frame "#my-frame"
+
+# Nested iframes using path
+agent-browser snapshot --in-frame "#outer-iframe/inner-iframe"
+agent-browser get value #input --in-frame "#parent/child"
+
+# Using index instead of name
+agent-browser snapshot --in-frame "#0"
+agent-browser snapshot --in-frame "#0/1"  # First iframe's second child
+```
+
+### Frame Path Syntax
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| `#id` | `#my-frame` | Frame by ID attribute |
+| `#name` | `#login-form` | Frame by name attribute |
+| `#index` | `#0`, `#1` | Frame by position |
+| `#path` | `#parent/child` | Nested frame by path |
+| `#mixed` | `#0/login-form` | Mix of index and name |
+
+The `--in-frame` option works with: click, dblclick, hover, focus, fill, type, check, uncheck, select, scrollintoview, drag, upload, download, press, wait, get, is, find, mouse, eval, snapshot, pdf, highlight, and more.
+
+## Dialogs
+
+```bash
+agent-browser dialog accept [text]  # Accept dialog
+agent-browser dialog dismiss        # Dismiss dialog
+```
+
+## 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    # Set state path (loads at browser launch)
+```
+
+**Note:** State must be loaded at browser launch. Use `--state` flag or close browser first:
+
+```bash
+# Method 1: Use --state flag at launch
+agent-browser --state auth.json open https://app.example.com
+
+# Method 2: Set path, close, then launch
+agent-browser state load auth.json
+agent-browser close
+agent-browser open https://app.example.com
+```
+
+## 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 --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 trace start                 # Start recording trace
+agent-browser trace stop trace.zip        # Stop and save trace
+```
+
+## Step Recorder
+
+Record user interactions as structured steps for LLM processing:
+
+```bash
+agent-browser recorder start                    # Start recording
+agent-browser recorder start https://site.com   # Start with navigation
+agent-browser recorder stop                     # Stop and output YAML
+agent-browser recorder stop --output session.yaml  # Save to file
+agent-browser recorder status                   # Show recording status
+agent-browser recorder replay                   # Replay most recent
+agent-browser recorder replay session.yaml      # Replay specific file
+```
+
+## Remote Viewing
+
+```bash
+agent-browser viewer           # Get viewer URL for browser session
+agent-browser viewer --json    # Get all URLs (HTTP + WebSocket)
+```
+
+Requires Stream Server to be running.
+
+## User Interaction
+
+```bash
+# Simple question
+agent-browser ask "What should I do next?"
+
+# Multiple choice question (JSON format)
+agent-browser ask '{"questions":[{"question":"Choose action","options":[{"label":"Login"},{"label":"Skip"}]}]}'
+
+# Multi-select question
+agent-browser ask '{"questions":[{"question":"Select items","multiSelect":true,"options":[{"label":"Item 1"},{"label":"Item 2"}]}]}'
+```
+
+Requires Stream Server with message bridge.
+
+## Session Management
+
+```bash
+agent-browser session          # Show current session name
+agent-browser session list     # List all active sessions
+agent-browser kill             # Kill all daemons and Stream Server
+```
+
+## Configuration
+
+```bash
+agent-browser config           # Show all AGENT_BROWSER_* settings
+agent-browser config --json    # JSON output
+```
+
+## Setup
+
+```bash
+agent-browser install          # Install browser binaries
+agent-browser install --with-deps  # Also install system dependencies (Linux)
+```
+
+## Diff Option (Page Change Detection)
+
+Show page changes after actions:
+
+```bash
+agent-browser click @e1 --diff           # Show changes 3 levels up from target
+agent-browser fill @e2 "text" --diff 5   # Show changes 5 levels up
+agent-browser click @e1 --diff full      # Show entire page changes
+agent-browser click @e1 --diff --selector "#content"  # Scope to selector
+```
+
+## 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"             # WebSocket streaming port
+AGENT_BROWSER_HOME="/path/to/agent-browser"  # Custom install location
+AGENT_BROWSER_HUMAN="1"                      # Enable human-like mouse movement (1, bezier, arc, random, linear)
+```