Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
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.mdindex 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```bashbrowser-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 profilebrowser-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# Navigationbrowser-use open <url> # Navigate to URL-browser-use back # Go back+browser-use back # Go back in historybrowser-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 statebrowser-use click <index> # Click element by indexbrowser-use click <x> <y> # Click at pixel coordinatesbrowser-use type "text" # Type into focused elementbrowser-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 optionbrowser-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 wizardbrowser-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 cloudbrowser-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 indices2. **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.mdindex 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/bbrowser-use open <url> # Default: headless Chromiumbrowser-use cloud connect # Provision cloud browser and connectbrowser-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# Navigationbrowser-use open <url> # Navigate to URL-browser-use back # Go back+browser-use back # Go back in historybrowser-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 statebrowser-use click <index> # Click element by indexbrowser-use click <x> <y> # Click at pixel coordinatesbrowser-use type "text" # Type into focused elementbrowser-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 optionbrowser-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)```