Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

condense SKILL.md files: merge redundant sections, cut 45% of lines

ShawnPanaaa2ac2e7f1bc
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
index 2b4006ba8..cc2e93d77 100644
--- a/skills/browser-use/SKILL.md
+++ b/skills/browser-use/SKILL.md
@@ -6,368 +6,197 @@ allowed-tools: Bash(browser-use:*)
# Browser Automation with browser-use CLI
-The `browser-use` command provides fast, persistent browser automation. It maintains browser sessions across commands, enabling complex multi-step workflows.
+The `browser-use` command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call.
## Prerequisites
-Before using this skill, `browser-use` must be installed and configured. Run diagnostics to verify:
-
```bash
-browser-use doctor
+browser-use doctor # Verify installation
```
-For more information, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
+For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
## Core Workflow
-1. **Navigate**: `browser-use open <url>` - Opens URL (starts browser if needed)
-2. **Inspect**: `browser-use state` - Returns clickable elements with indices
-3. **Interact**: Use indices from state to interact (`browser-use click 5`, `browser-use input 3 "text"`)
-4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm actions
-5. **Repeat**: Browser stays open between commands
+1. **Navigate**: `browser-use open <url>` — starts browser if needed
+2. **Inspect**: `browser-use state` — returns clickable elements with indices
+3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
+4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
+5. **Repeat**: browser stays open between commands
+6. **Cleanup**: `browser-use close` when done
## Browser Modes
```bash
browser-use open <url> # Default: headless Chromium
-browser-use --headed open <url> # Visible Chromium window
-browser-use --profile open <url> # Real Chrome with Default profile
+browser-use --headed open <url> # Visible window
+browser-use --profile open <url> # Real Chrome with Default profile (existing logins/cookies)
browser-use --profile "Profile 1" open <url> # Real Chrome with named profile
browser-use --connect open <url> # Auto-discover running Chrome via CDP
-browser-use --cdp-url http://localhost:9222 open <url> # Connect to existing browser via CDP
-browser-use --cdp-url ws://localhost:9222/devtools/browser/... state # WebSocket CDP URL
+browser-use --cdp-url ws://localhost:9222/... open <url> # Connect via CDP URL
```
-- **Default (no --profile)**: Fast, isolated Chromium, headless by default
-- **With --profile**: Uses your real Chrome binary with the specified profile (cookies, logins, extensions). Bare `--profile` uses "Default".
-- **With --connect**: Auto-discovers a running Chrome instance with remote debugging enabled by reading `DevToolsActivePort` or probing well-known ports. No manual URL needed.
-- **With --cdp-url**: Connects to an already-running browser via CDP URL (http:// or ws://). Useful for Docker containers, remote debugging sessions, or cloud-provisioned browsers. `--connect`, `--cdp-url`, and `--profile` are mutually exclusive.
+`--connect`, `--cdp-url`, and `--profile` are mutually exclusive.
-## Essential Commands
+## Commands
```bash
# Navigation
browser-use open <url> # Navigate to URL
-browser-use back # Go back
+browser-use back # Go back in history
browser-use scroll down # Scroll down (--amount N for pixels)
+browser-use scroll up # Scroll up
+browser-use switch <tab> # Switch to tab by index
+browser-use close-tab [tab] # Close tab (current if no index)
-# Page State (always run state first to get element indices)
-browser-use state # Get URL, title, clickable elements
-browser-use screenshot # Take screenshot (base64)
-browser-use screenshot path.png # Save screenshot to file
+# Page State — always run state first to get element indices
+browser-use state # URL, title, clickable elements with indices
+browser-use screenshot [path.png] # Screenshot (base64 if no path, --full for full page)
-# Interactions (use indices from state)
+# Interactions — use indices from state
browser-use click <index> # Click element by index
browser-use click <x> <y> # Click at pixel coordinates
browser-use type "text" # Type into focused element
browser-use input <index> "text" # Click element, then type
-browser-use keys "Enter" # Send keyboard keys
+browser-use keys "Enter" # Send keyboard keys (also "Control+a", etc.)
browser-use select <index> "option" # Select dropdown option
browser-use upload <index> <path> # Upload file to file input
+browser-use hover <index> # Hover over element
+browser-use dblclick <index> # Double-click element
+browser-use rightclick <index> # Right-click element
# Data Extraction
-browser-use eval "document.title" # Execute JavaScript
-browser-use extract "query" # Extract data with LLM (not yet implemented)
-browser-use get text <index> # Get element text
-browser-use get html --selector "h1" # Get scoped HTML
+browser-use eval "js code" # Execute JavaScript, return result
+browser-use get title # Page title
+browser-use get html [--selector "h1"] # Page HTML (or scoped to selector)
+browser-use get text <index> # Element text content
+browser-use get value <index> # Input/textarea value
+browser-use get attributes <index> # Element attributes
+browser-use get bbox <index> # Bounding box (x, y, width, height)
# Wait
-browser-use wait selector "h1" # Wait for element
-browser-use wait text "Success" # Wait for text
+browser-use wait selector "css" # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
+browser-use wait text "text" # Wait for text to appear
+
+# Cookies
+browser-use cookies get [--url <url>] # Get cookies (optionally filtered)
+browser-use cookies set <name> <value> # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
+browser-use cookies clear [--url <url>] # Clear cookies
+browser-use cookies export <file> # Export to JSON
+browser-use cookies import <file> # Import from JSON
+
+# Python — persistent session with browser access
+browser-use python "code" # Execute Python (variables persist across calls)
+browser-use python --file script.py # Run file
+browser-use python --vars # Show defined variables
+browser-use python --reset # Clear namespace
# Session
-browser-use close # Close browser session
+browser-use close # Close browser and stop daemon
+browser-use sessions # List active sessions
+browser-use close --all # Close all sessions
```
-## Commands
-
-### Navigation & Tabs
-```bash
-browser-use open <url> # Navigate to URL
-browser-use back # Go back in history
-browser-use scroll down # Scroll down
-browser-use scroll up # Scroll up
-browser-use scroll down --amount 1000 # Scroll by specific pixels (default: 500)
-browser-use switch <tab> # Switch to tab by index
-browser-use close-tab # Close current tab
-browser-use close-tab <tab> # Close specific tab
-```
+The Python `browser` object provides: `browser.url`, `browser.title`, `browser.html`, `browser.goto(url)`, `browser.back()`, `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)`, `browser.screenshot(path)`, `browser.scroll(direction, amount)`, `browser.wait(seconds)`.
-### Page State
-```bash
-browser-use state # Get URL, title, and clickable elements
-browser-use screenshot # Take screenshot (outputs base64)
-browser-use screenshot path.png # Save screenshot to file
-browser-use screenshot --full path.png # Full page screenshot
-```
+## Cloud API
-### Interactions
```bash
-browser-use click <index> # Click element by index
-browser-use click <x> <y> # Click at pixel coordinates
-browser-use type "text" # Type text into focused element
-browser-use input <index> "text" # Click element, then type text
-browser-use keys "Enter" # Send keyboard keys
-browser-use keys "Control+a" # Send key combination
-browser-use select <index> "option" # Select dropdown option
-browser-use upload <index> <path> # Upload file to file input element
-browser-use hover <index> # Hover over element (triggers CSS :hover)
-browser-use dblclick <index> # Double-click element
-browser-use rightclick <index> # Right-click element (context menu)
+browser-use cloud connect # Provision cloud browser and connect
+browser-use cloud connect --timeout 120 --proxy-country US # With options
+browser-use cloud login <api-key> # Save API key (or set BROWSER_USE_API_KEY)
+browser-use cloud logout # Remove API key
+browser-use cloud v2 GET /browsers # REST passthrough (v2 or v3)
+browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
+browser-use cloud v2 poll <task-id> # Poll task until done
+browser-use cloud v2 --help # Show API endpoints
```
-Use indices from `browser-use state`.
+`cloud connect` provisions a cloud browser, connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser.
-### JavaScript & Data
-```bash
-browser-use eval "document.title" # Execute JavaScript, return result
-browser-use extract "query" # Extract data with LLM (not yet implemented)
-browser-use get title # Get page title
-browser-use get html # Get full page HTML
-browser-use get html --selector "h1" # Get HTML of specific element
-browser-use get text <index> # Get text content of element
-browser-use get value <index> # Get value of input/textarea
-browser-use get attributes <index> # Get all attributes of element
-browser-use get bbox <index> # Get bounding box (x, y, width, height)
-```
-
-### Cookies
-```bash
-browser-use cookies get # Get all cookies
-browser-use cookies get --url <url> # Get cookies for specific URL
-browser-use cookies set <name> <value> # Set a cookie
-browser-use cookies set name val --domain .example.com --secure --http-only
-browser-use cookies set name val --same-site Strict # SameSite: Strict, Lax, or None
-browser-use cookies set name val --expires 1735689600 # Expiration timestamp
-browser-use cookies clear # Clear all cookies
-browser-use cookies clear --url <url> # Clear cookies for specific URL
-browser-use cookies export <file> # Export all cookies to JSON file
-browser-use cookies export <file> --url <url> # Export cookies for specific URL
-browser-use cookies import <file> # Import cookies from JSON file
-```
-
-### Wait Conditions
-```bash
-browser-use wait selector "h1" # Wait for element to be visible
-browser-use wait selector ".loading" --state hidden # Wait for element to disappear
-browser-use wait selector "#btn" --state attached # Wait for element in DOM
-browser-use wait text "Success" # Wait for text to appear
-browser-use wait selector "h1" --timeout 5000 # Custom timeout in ms
-```
-
-### Python Execution
-```bash
-browser-use python "x = 42" # Set variable
-browser-use python "print(x)" # Access variable (outputs: 42)
-browser-use python "print(browser.url)" # Access browser object
-browser-use python --vars # Show defined variables
-browser-use python --reset # Clear Python namespace
-browser-use python --file script.py # Execute Python file
-```
-
-The Python session maintains state across commands. The `browser` object provides:
-- `browser.url`, `browser.title`, `browser.html` — page info
-- `browser.goto(url)`, `browser.back()` — navigation
-- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)` — interactions
-- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual
-- `browser.wait(seconds)` — utilities
-
-### Cloud API
-```bash
-browser-use cloud connect # Provision cloud browser and connect
-browser-use cloud connect --timeout 120 # Custom timeout
-browser-use cloud connect --proxy-country US # With proxy
-browser-use cloud connect --profile-id <id> # With cloud profile
-browser-use cloud login <api-key> # Save API key
-browser-use cloud logout # Remove API key
-browser-use cloud v2 GET /browsers # List browsers
-browser-use cloud v2 POST /tasks '{"task":"...","url":"https://..."}' # Create task
-browser-use cloud v3 POST /sessions '{"task":"...","model":"bu-mini"}' # Create session
-browser-use cloud v2 GET /tasks/<task-id> # Get task status
-browser-use cloud v2 poll <task-id> # Poll task until done
-browser-use cloud v2 --help # Show API v2 endpoints
-browser-use cloud v3 --help # Show API v3 endpoints
-```
-
-`cloud connect` provisions a cloud browser, connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser (no orphaned billing). Mutually exclusive with `--cdp-url` and `--profile`.
-
-API key: env var `BROWSER_USE_API_KEY` or `browser-use cloud login`. Stored in `~/.browser-use/config.json`.
-
-### Tunnels
-```bash
-browser-use tunnel <port> # Start tunnel (returns URL)
-browser-use tunnel <port> # Idempotent - returns existing URL
-browser-use tunnel list # Show active tunnels
-browser-use tunnel stop <port> # Stop tunnel
-browser-use tunnel stop --all # Stop all tunnels
-```
+## Tunnels
-### Session Management
```bash
-browser-use close # Close browser session
+browser-use tunnel <port> # Start Cloudflare tunnel (idempotent)
+browser-use tunnel list # Show active tunnels
+browser-use tunnel stop <port> # Stop tunnel
+browser-use tunnel stop --all # Stop all tunnels
```
-### Profile Management
-
-Manages browser profiles via the profile-use Go binary (auto-downloaded to `~/.browser-use/bin/`).
+## Profile Management
```bash
-browser-use profile # Interactive sync wizard
browser-use profile list # List detected browsers and profiles
-browser-use profile sync --all # Sync all profiles to cloud
-browser-use profile sync --browser "Google Chrome" --profile "Default" # Sync specific
-browser-use profile auth --apikey <key> # Set API key (shared with cloud login)
-browser-use profile inspect --browser "Google Chrome" --profile "Default" # Inspect locally
+browser-use profile sync --all # Sync profiles to cloud
browser-use profile update # Download/update profile-use binary
```
-## Common Workflows
-
-### Authenticated Browsing with Profiles
-
-Use when a task requires browsing a site the user is already logged into (e.g. Gmail, GitHub, internal tools).
-
-**Core workflow:** Check existing profiles → ask user which profile → browse with that profile.
-
-**Before browsing an authenticated site, the agent MUST:**
-1. List available profiles
-2. Ask which profile to use
-3. Browse with the chosen profile
-
-#### Step 1: Check existing profiles
-
-```bash
-browser-use profile list
-# → Google Chrome - Person 1 (Default)
-# → Google Chrome - Work (Profile 1)
-```
+## Command Chaining
-#### Step 2: Browse with the chosen profile
+Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
```bash
-# Real Chrome — uses existing login sessions from the chosen profile
-browser-use --profile "Default" open https://github.com
+browser-use open https://example.com && browser-use state
+browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7
```
-The user is already authenticated — no login needed.
-
-#### Check what cookies a profile has
-```bash
-browser-use profile inspect --browser "Google Chrome" --profile "Person 1"
-# Shows cookie domains and counts
-```
+Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
-### Connecting to an Existing Chrome Browser
+## Common Workflows
-Use when the user has Chrome already running and wants to control it via browser-use.
+### Authenticated Browsing
-**Requirement:** Chrome must have remote debugging enabled (`chrome://inspect/#remote-debugging` on Chrome >= 144, or launch with `--remote-debugging-port=<port>`).
+When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles:
-**Recommended: auto-discovery with `--connect`:**
```bash
-browser-use close # Close any existing session
-browser-use --connect open https://example.com # Auto-discovers Chrome's CDP endpoint
-browser-use --connect state # Works with all commands
+browser-use profile list # Check available profiles
+# Ask the user which profile to use, then:
+browser-use --profile "Default" open https://github.com # Already logged in
```
-`--connect` reads `DevToolsActivePort` from known Chrome data directories and probes well-known ports (9222, 9229) as a fallback — no manual URL construction needed.
-
-**Manual fallback with `--cdp-url`:**
-
-If auto-discovery doesn't work (e.g. non-standard Chrome location or remote host), read Chrome's `DevToolsActivePort` file manually:
- - macOS: `~/Library/Application Support/Google/Chrome/DevToolsActivePort`
- - Linux: `~/.config/google-chrome/DevToolsActivePort`
- - The file contains two lines: the port and the WebSocket path. Combine into `ws://127.0.0.1:<port><path>`.
+### Connecting to Existing Chrome
```bash
-browser-use --cdp-url ws://127.0.0.1:<port><path> open https://example.com
+browser-use --connect open https://example.com # Auto-discovers Chrome's CDP endpoint
```
-**Important:** Always use the `ws://` WebSocket URL (not `http://`) with `--cdp-url` when connecting to an existing Chrome instance.
+Requires Chrome with remote debugging enabled. Falls back to probing ports 9222/9229.
### Exposing Local Dev Servers
-Use when you have a local dev server and need to expose it via tunnel.
-
```bash
-# 1. Start your dev server
-npm run dev & # localhost:3000
-
-# 2. Expose it via Cloudflare tunnel
-browser-use tunnel 3000
-# → url: https://abc.trycloudflare.com
-
-# 3. Browse the tunnel URL
-browser-use open https://abc.trycloudflare.com
-browser-use state
-browser-use screenshot
+browser-use tunnel 3000 # → https://abc.trycloudflare.com
+browser-use open https://abc.trycloudflare.com # Browse the tunnel
```
-**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately. Cloudflared must be installed — run `browser-use doctor` to check.
-
## Global Options
| Option | Description |
|--------|-------------|
| `--headed` | Show browser window |
| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |
-| `--connect` | Auto-discover and connect to running Chrome via CDP |
-| `--cdp-url <url>` | Connect to existing browser via CDP URL (`http://` or `ws://`) |
+| `--connect` | Auto-discover running Chrome via CDP |
+| `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
| `--session NAME` | Target a named session (default: "default") |
| `--json` | Output as JSON |
| `--mcp` | Run as MCP server via stdin/stdout |
-## Command Chaining
-
-Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls.
-
-```bash
-# Chain open + state in one call
-browser-use open https://example.com && browser-use state
-
-# Chain multiple interactions
-browser-use input 5 "[email protected]" && browser-use input 6 "password123" && browser-use click 7
-
-# Fill and verify
-browser-use input 3 "search query" && browser-use keys "Enter" && browser-use state
-```
-
-**When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding. Run commands separately when you need to parse the output first (e.g., `state` to discover indices, then interact using those indices).
-
## Tips
-1. **Always run `browser-use state` first** to see available elements and their indices
+1. **Always run `state` first** to see available elements and their indices
2. **Use `--headed` for debugging** to see what the browser is doing
-3. **Sessions persist** — the browser stays open between commands
-4. **Use `--json`** for programmatic parsing
-5. **Python variables persist** across `browser-use python` commands within a session
-6. **CLI aliases**: `bu`, `browser`, and `browseruse` all work identically to `browser-use`
+3. **Sessions persist** — browser stays open between commands
+4. **CLI aliases**: `bu`, `browser`, and `browseruse` all work
## Troubleshooting
-**Run diagnostics first:**
-```bash
-browser-use doctor
-```
-
-**Browser won't start?**
-```bash
-browser-use close # Close browser session
-browser-use --headed open <url> # Try with visible window
-```
-
-**Element not found?**
-```bash
-browser-use state # Check current elements
-browser-use scroll down # Element might be below fold
-browser-use state # Check again
-```
+- **Browser won't start?** `browser-use close` then `browser-use --headed open <url>`
+- **Element not found?** `browser-use scroll down` then `browser-use state`
+- **Run diagnostics:** `browser-use doctor`
## Cleanup
-**Always close the browser when done:**
-
```bash
-browser-use close # Close browser session
-browser-use tunnel stop --all # Stop tunnels (if any)
+browser-use close # Close browser session
+browser-use tunnel stop --all # Stop tunnels (if any)
```
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.md
index 721fc5a45..a57ee44f4 100644
--- a/skills/remote-browser/SKILL.md
+++ b/skills/remote-browser/SKILL.md
@@ -6,17 +6,24 @@ allowed-tools: Bash(browser-use:*)
# Browser Automation for Sandboxed Agents
-This skill is for agents running on **sandboxed remote machines** (cloud VMs, CI, coding agents) that need to control a browser. Install `browser-use` and drive a headless Chromium browser.
+This skill is for agents running on **sandboxed remote machines** (cloud VMs, CI, coding agents) that need to control a headless browser.
## Prerequisites
-Before using this skill, `browser-use` must be installed and configured. Run diagnostics to verify:
-
```bash
-browser-use doctor
+browser-use doctor # Verify installation
```
-For more information, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
+For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
+
+## Core Workflow
+
+1. **Navigate**: `browser-use open <url>` — starts headless browser if needed
+2. **Inspect**: `browser-use state` — returns clickable elements with indices
+3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
+4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
+5. **Repeat**: browser stays open between commands
+6. **Cleanup**: `browser-use close` when done
## Browser Modes
@@ -24,255 +31,130 @@ For more information, see https://github.com/browser-use/browser-use/blob/main/b
browser-use open <url> # Default: headless Chromium
browser-use cloud connect # Provision cloud browser and connect
browser-use --connect open <url> # Auto-discover running Chrome via CDP
-browser-use --cdp-url http://localhost:9222 open <url> # Connect to existing browser via CDP
-browser-use --cdp-url ws://localhost:9222/devtools/browser/... state # WebSocket CDP URL
+browser-use --cdp-url ws://localhost:9222/... open <url> # Connect via CDP URL
```
-- **Default**: Launches headless Chromium
-- **With cloud connect**: Provisions a cloud browser via Browser-Use Cloud API, connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser. Requires API key (`BROWSER_USE_API_KEY` env var or `browser-use cloud login`).
-- **With --connect**: Auto-discovers a running Chrome instance with remote debugging enabled. No manual URL needed.
-- **With --cdp-url**: Connects to an already-running browser via CDP URL (http:// or ws://). Useful for Docker containers, remote debugging sessions, or cloud-provisioned browsers. `browser-use close` disconnects without killing the external browser.
-
-## Core Workflow
-
-```bash
-# Step 1: Start session (headless Chromium by default)
-browser-use open https://example.com
-
-# Step 2+: All subsequent commands use the existing session
-browser-use state # Get page elements with indices
-browser-use click 5 # Click element by index
-browser-use type "Hello World" # Type into focused element
-browser-use input 3 "text" # Click element, then type
-browser-use screenshot # Take screenshot (base64)
-browser-use screenshot page.png # Save screenshot to file
-
-# Done: Close the session
-browser-use close # Close browser and release resources
-```
-
-## Essential Commands
+## Commands
```bash
# Navigation
browser-use open <url> # Navigate to URL
-browser-use back # Go back
+browser-use back # Go back in history
browser-use scroll down # Scroll down (--amount N for pixels)
+browser-use scroll up # Scroll up
+browser-use switch <tab> # Switch to tab by index
+browser-use close-tab [tab] # Close tab (current if no index)
-# Page State (always run state first to get element indices)
-browser-use state # Get URL, title, clickable elements
-browser-use screenshot # Take screenshot (base64)
-browser-use screenshot path.png # Save screenshot to file
+# Page State — always run state first to get element indices
+browser-use state # URL, title, clickable elements with indices
+browser-use screenshot [path.png] # Screenshot (base64 if no path, --full for full page)
-# Interactions (use indices from state)
+# Interactions — use indices from state
browser-use click <index> # Click element by index
browser-use click <x> <y> # Click at pixel coordinates
browser-use type "text" # Type into focused element
browser-use input <index> "text" # Click element, then type
-browser-use keys "Enter" # Send keyboard keys
+browser-use keys "Enter" # Send keyboard keys (also "Control+a", etc.)
browser-use select <index> "option" # Select dropdown option
browser-use upload <index> <path> # Upload file to file input
+browser-use hover <index> # Hover over element
+browser-use dblclick <index> # Double-click element
+browser-use rightclick <index> # Right-click element
# Data Extraction
-browser-use eval "document.title" # Execute JavaScript
-browser-use extract "query" # Extract data with LLM (not yet implemented)
-browser-use get text <index> # Get element text
-browser-use get html --selector "h1" # Get scoped HTML
+browser-use eval "js code" # Execute JavaScript, return result
+browser-use get title # Page title
+browser-use get html [--selector "h1"] # Page HTML (or scoped to selector)
+browser-use get text <index> # Element text content
+browser-use get value <index> # Input/textarea value
+browser-use get attributes <index> # Element attributes
+browser-use get bbox <index> # Bounding box (x, y, width, height)
# Wait
-browser-use wait selector "h1" # Wait for element
-browser-use wait text "Success" # Wait for text
+browser-use wait selector "css" # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
+browser-use wait text "text" # Wait for text to appear
+
+# Cookies
+browser-use cookies get [--url <url>] # Get cookies (optionally filtered)
+browser-use cookies set <name> <value> # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
+browser-use cookies clear [--url <url>] # Clear cookies
+browser-use cookies export <file> # Export to JSON
+browser-use cookies import <file> # Import from JSON
+
+# Python — persistent session with browser access
+browser-use python "code" # Execute Python (variables persist across calls)
+browser-use python --file script.py # Run file
+browser-use python --vars # Show defined variables
+browser-use python --reset # Clear namespace
# Session
-browser-use close # Close browser session
-```
-
-## Commands
-
-### Navigation & Tabs
-```bash
-browser-use open <url> # Navigate to URL
-browser-use back # Go back in history
-browser-use scroll down # Scroll down
-browser-use scroll up # Scroll up
-browser-use scroll down --amount 1000 # Scroll by specific pixels (default: 500)
-browser-use switch <tab> # Switch tab by index
-browser-use close-tab # Close current tab
-browser-use close-tab <tab> # Close specific tab
+browser-use close # Close browser and stop daemon
+browser-use sessions # List active sessions
+browser-use close --all # Close all sessions
```
-### Page State
-```bash
-browser-use state # Get URL, title, and clickable elements
-browser-use screenshot # Take screenshot (base64)
-browser-use screenshot path.png # Save screenshot to file
-browser-use screenshot --full p.png # Full page screenshot
-```
+The Python `browser` object provides: `browser.url`, `browser.title`, `browser.html`, `browser.goto(url)`, `browser.back()`, `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)`, `browser.screenshot(path)`, `browser.scroll(direction, amount)`, `browser.wait(seconds)`.
-### Interactions
-```bash
-browser-use click <index> # Click element by index
-browser-use click <x> <y> # Click at pixel coordinates
-browser-use type "text" # Type into focused element
-browser-use input <index> "text" # Click element, then type
-browser-use keys "Enter" # Send keyboard keys
-browser-use keys "Control+a" # Key combination
-browser-use select <index> "option" # Select dropdown option
-browser-use upload <index> <path> # Upload file to file input
-browser-use hover <index> # Hover over element
-browser-use dblclick <index> # Double-click
-browser-use rightclick <index> # Right-click
-```
-
-Use indices from `browser-use state`.
+## Tunnels
-### JavaScript & Data
-```bash
-browser-use eval "document.title" # Execute JavaScript
-browser-use extract "query" # Extract data with LLM (not yet implemented)
-browser-use get title # Get page title
-browser-use get html # Get page HTML
-browser-use get html --selector "h1" # Scoped HTML
-browser-use get text <index> # Get element text
-browser-use get value <index> # Get input value
-browser-use get attributes <index> # Get element attributes
-browser-use get bbox <index> # Get bounding box (x, y, width, height)
-```
+Expose local dev servers to the browser via Cloudflare tunnels.
-### Cookies
```bash
-browser-use cookies get # Get all cookies
-browser-use cookies get --url <url> # Get cookies for specific URL
-browser-use cookies set <name> <val> # Set a cookie
-browser-use cookies set name val --domain .example.com --secure
-browser-use cookies set name val --same-site Strict # SameSite: Strict, Lax, None
-browser-use cookies set name val --expires 1735689600 # Expiration timestamp
-browser-use cookies clear # Clear all cookies
-browser-use cookies clear --url <url> # Clear cookies for specific URL
-browser-use cookies export <file> # Export to JSON
-browser-use cookies import <file> # Import from JSON
+browser-use tunnel <port> # Start tunnel (idempotent)
+browser-use tunnel list # Show active tunnels
+browser-use tunnel stop <port> # Stop tunnel
+browser-use tunnel stop --all # Stop all tunnels
```
-### Wait Conditions
-```bash
-browser-use wait selector "h1" # Wait for element
-browser-use wait selector ".loading" --state hidden # Wait for element to disappear
-browser-use wait text "Success" # Wait for text
-browser-use wait selector "#btn" --timeout 5000 # Custom timeout (ms)
-```
-
-### Python Execution
-```bash
-browser-use python "x = 42" # Set variable
-browser-use python "print(x)" # Access variable (prints: 42)
-browser-use python "print(browser.url)" # Access browser object
-browser-use python --vars # Show defined variables
-browser-use python --reset # Clear namespace
-browser-use python --file script.py # Run Python file
-```
+## Command Chaining
-The Python session maintains state across commands. The `browser` object provides:
-- `browser.url`, `browser.title`, `browser.html` — page info
-- `browser.goto(url)`, `browser.back()` — navigation
-- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)` — interactions
-- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual
-- `browser.wait(seconds)` — utilities
+Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
-### Tunnels
```bash
-browser-use tunnel <port> # Start tunnel (returns URL)
-browser-use tunnel <port> # Idempotent - returns existing URL
-browser-use tunnel list # Show active tunnels
-browser-use tunnel stop <port> # Stop tunnel
-browser-use tunnel stop --all # Stop all tunnels
+browser-use open https://example.com && browser-use state
+browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7
```
-### Session Management
-```bash
-browser-use close # Close browser session
-```
+Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
## Common Workflows
### Exposing Local Dev Servers
-Use when you have a dev server on the remote machine and need the browser to reach it via tunnel.
-
-**Core workflow:** Start dev server → create tunnel → browse the tunnel URL.
-
```bash
-# 1. Start your dev server
-python -m http.server 3000 &
-
-# 2. Expose it via Cloudflare tunnel
-browser-use tunnel 3000
-# → url: https://abc.trycloudflare.com
-
-# 3. Now the browser can reach your local server
-browser-use open https://abc.trycloudflare.com
-browser-use state
-browser-use screenshot
+python -m http.server 3000 & # Start dev server
+browser-use tunnel 3000 # → https://abc.trycloudflare.com
+browser-use open https://abc.trycloudflare.com # Browse the tunnel
```
-**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately. Cloudflared must be installed — run `browser-use doctor` to check.
+Tunnels are independent of browser sessions and persist across `browser-use close`.
## Global Options
| Option | Description |
|--------|-------------|
| `--headed` | Show browser window |
-| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |
-| `--connect` | Auto-discover and connect to running Chrome via CDP |
-| `--cdp-url <url>` | Connect to existing browser via CDP URL (`http://` or `ws://`) |
+| `--connect` | Auto-discover running Chrome via CDP |
+| `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
| `--session NAME` | Target a named session (default: "default") |
| `--json` | Output as JSON |
-## Command Chaining
-
-Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls.
-
-```bash
-# Chain open + state in one call
-browser-use open https://example.com && browser-use state
-
-# Chain multiple interactions
-browser-use input 5 "[email protected]" && browser-use input 6 "password123" && browser-use click 7
-
-# Fill and verify
-browser-use input 3 "search query" && browser-use keys "Enter" && browser-use state
-```
-
-**When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding. Run commands separately when you need to parse the output first (e.g., `state` to discover indices, then interact using those indices).
-
## Tips
-1. **Run `browser-use doctor`** to verify installation before starting
-2. **Always run `state` first** to see available elements and their indices
-3. **Sessions persist** across commands — the browser stays open until you close it
-4. **Tunnels are independent** — they persist across `browser-use close`
-5. **Use `--json`** for programmatic parsing
-6. **`tunnel` is idempotent** — calling it again for the same port returns the existing URL
+1. **Always run `state` first** to see available elements and their indices
+2. **Sessions persist** — browser stays open between commands until you close it
+3. **Tunnels are independent** — they persist across `browser-use close`
+4. **`tunnel` is idempotent** — calling again for the same port returns the existing URL
## Troubleshooting
-**Browser won't start?**
-- Run `browser-use doctor` to check configuration
-- `browser-use close` then retry
-
-**Tunnel not working?**
-- Verify cloudflared is installed: `which cloudflared`
-- `browser-use tunnel list` to check active tunnels
-- `browser-use tunnel stop <port>` and retry
-
-**Element not found?**
-- Run `browser-use state` to see current elements
-- `browser-use scroll down` then `browser-use state` — element might be below fold
+- **Browser won't start?** `browser-use close` then retry. Run `browser-use doctor` to check.
+- **Element not found?** `browser-use scroll down` then `browser-use state`
+- **Tunnel not working?** `which cloudflared` to check, `browser-use tunnel list` to see active tunnels
## Cleanup
-**Always close resources when done:**
-
```bash
-browser-use close # Close browser session
-browser-use tunnel stop --all # Stop tunnels (if any)
+browser-use close # Close browser session
+browser-use tunnel stop --all # Stop tunnels (if any)
```