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
update SKILL.md files
ShawnPana624cef10a93b
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdindex 5203041ac..c0b34e8e6 100644--- a/skills/browser-use/SKILL.md+++ b/skills/browser-use/SKILL.md@@ -8,95 +8,14 @@ allowed-tools: Bash(browser-use:*)The `browser-use` command provides fast, persistent browser automation. It maintains browser sessions across commands, enabling complex multi-step workflows.-## Installation+## Prerequisites-```bash-# Run without installing (recommended for one-off use)-uvx "browser-use[cli]" open https://example.com--# Or install permanently-uv pip install "browser-use[cli]"--# Install browser dependencies (Chromium)-browser-use install-```--## Setup+Before using this skill, `browser-use` must be installed and configured. Run diagnostics to verify:-**One-line install (recommended)**-```bash-curl -fsSL https://browser-use.com/cli/install.sh | bash-```--This interactive installer lets you choose your installation mode and configures everything automatically.--**Installation modes:**-```bash-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only # Cloud browser only-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --local-only # Local browser only-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --full # All modes-```--| Install Mode | Available Browsers | Default | Use Case |-|--------------|-------------------|---------|----------|-| `--remote-only` | remote | remote | Sandboxed agents, CI, no GUI |-| `--local-only` | chromium, real | chromium | Local development |-| `--full` | chromium, real, remote | chromium | Full flexibility |--When only one mode is installed, it becomes the default and no `--browser` flag is needed.--**Pass API key during install:**-```bash-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only --api-key bu_xxx-```--**Verify installation:**```bashbrowser-use doctor```-**Setup wizard (first-time configuration):**-```bash-browser-use setup # Interactive setup-browser-use setup --mode local # Configure for local browser only-browser-use setup --mode remote # Configure for cloud browser only-browser-use setup --mode full # Configure all modes-browser-use setup --api-key bu_xxx # Set API key during setup-browser-use setup --yes # Skip interactive prompts-```--**Generate template files:**-```bash-browser-use init # Interactive template selection-browser-use init --list # List available templates-browser-use init --template basic # Generate specific template-browser-use init --output my_script.py # Specify output file-browser-use init --force # Overwrite existing files-```--**Manual cloudflared install (for tunneling):**-```bash-# macOS:-brew install cloudflared--# Linux:-curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/.local/bin/cloudflared && chmod +x ~/.local/bin/cloudflared--# Windows:-winget install Cloudflare.cloudflared-```--## Quick Start--```bash-browser-use open https://example.com # Navigate to URL-browser-use state # Get page elements with indices-browser-use click 5 # Click element by index-browser-use type "Hello World" # Type text-browser-use screenshot # Take screenshot-browser-use close # Close browser-```-## Core Workflow1. **Navigate**: `browser-use open <url>` - Opens URL (starts browser if needed)@@ -110,23 +29,66 @@ browser-use close # Close browser```bashbrowser-use --browser chromium open <url> # Default: headless Chromiumbrowser-use --browser chromium --headed open <url> # Visible Chromium window-browser-use --browser real open <url> # User's Chrome with login sessions-browser-use --browser remote open <url> # Cloud browser (requires API key)+browser-use --browser real open <url> # Real Chrome (no profile = fresh)+browser-use --browser real --profile "Default" open <url> # Real Chrome with your login sessions+browser-use --browser remote open <url> # Cloud browser```- **chromium**: Fast, isolated, headless by default-- **real**: Uses your Chrome with cookies, extensions, logged-in sessions-- **remote**: Cloud-hosted browser with proxy support (requires BROWSER_USE_API_KEY)+- **real**: Uses a real Chrome binary. Without `--profile`, uses a persistent but empty CLI profile at `~/.config/browseruse/profiles/cli/`. With `--profile "ProfileName"`, copies your actual Chrome profile (cookies, logins, extensions)+- **remote**: Cloud-hosted browser with proxy support++## Essential Commands++```bash+# Navigation+browser-use open <url> # Navigate to URL+browser-use back # Go back+browser-use scroll down # Scroll down (--amount N for pixels)++# 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++# Interactions (use indices from state)+browser-use click <index> # Click element+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 select <index> "option" # Select dropdown option++# Data Extraction+browser-use eval "document.title" # Execute JavaScript+browser-use get text <index> # Get element text+browser-use get html --selector "h1" # Get scoped HTML++# Wait+browser-use wait selector "h1" # Wait for element+browser-use wait text "Success" # Wait for text++# Session+browser-use sessions # List active sessions+browser-use close # Close current session+browser-use close --all # Close all sessions++# AI Agent+browser-use -b remote run "task" # Run agent in cloud (async by default)+browser-use task status <id> # Check cloud task progress+```## Commands-### Navigation+### Navigation & Tabs```bashbrowser-use open <url> # Navigate to URLbrowser-use back # Go back in historybrowser-use scroll down # Scroll downbrowser-use scroll up # Scroll upbrowser-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```### Page State@@ -137,7 +99,7 @@ browser-use screenshot path.png # Save screenshot to filebrowser-use screenshot --full path.png # Full page screenshot```-### Interactions (use indices from `browser-use state`)+### Interactions```bashbrowser-use click <index> # Click elementbrowser-use type "text" # Type text into focused element@@ -145,19 +107,23 @@ browser-use input <index> "text" # Click element, then type textbrowser-use keys "Enter" # Send keyboard keysbrowser-use keys "Control+a" # Send key combinationbrowser-use select <index> "option" # Select dropdown option+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)```-### Tab Management-```bash-browser-use switch <tab> # Switch to tab by index-browser-use close-tab # Close current tab-browser-use close-tab <tab> # Close specific tab-```+Use indices from `browser-use state`.### JavaScript & Data```bashbrowser-use eval "document.title" # Execute JavaScript, return result-browser-use extract "all product prices" # Extract data using LLM (requires API key)+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@@ -184,25 +150,7 @@ browser-use wait text "Success" # Wait for text to appearbrowser-use wait selector "h1" --timeout 5000 # Custom timeout in ms```-### Additional Interactions-```bash-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)-```--### Information Retrieval-```bash-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)-```--### Python Execution (Persistent Session)+### Python Execution```bashbrowser-use python "x = 42" # Set variablebrowser-use python "print(x)" # Access variable (outputs: 42)@@ -213,148 +161,101 @@ browser-use python --file script.py # Execute Python file```The Python session maintains state across commands. The `browser` object provides:-- `browser.url` - Current page URL-- `browser.title` - Page title-- `browser.html` - Get page HTML-- `browser.goto(url)` - Navigate-- `browser.click(index)` - Click element-- `browser.type(text)` - Type text-- `browser.input(index, text)` - Click element, then type-- `browser.keys(keys)` - Send keyboard keys (e.g., "Enter", "Control+a")-- `browser.screenshot(path)` - Take screenshot-- `browser.scroll(direction, amount)` - Scroll page-- `browser.back()` - Go back in history-- `browser.wait(seconds)` - Sleep/pause execution-- `browser.extract(query)` - Extract data using LLM+- `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)` — interactions+- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual+- `browser.wait(seconds)`, `browser.extract(query)` — utilities-### Agent Tasks (Requires API Key)-```bash-browser-use run "Fill the contact form with test data" # Run AI agent-browser-use run "Extract all product prices" --max-steps 50-```+### Agent Tasks-Agent tasks use an LLM to autonomously complete complex browser tasks. Requires `BROWSER_USE_API_KEY` or configured LLM API key (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc).--#### Remote Mode Agent Options+#### Remote Mode OptionsWhen using `--browser remote`, additional options are available:```bash-# Basic remote task (uses US proxy by default)-browser-use -b remote run "Search for AI news"-# Specify LLM modelbrowser-use -b remote run "task" --llm gpt-4obrowser-use -b remote run "task" --llm claude-sonnet-4-20250514-browser-use -b remote run "task" --llm gemini-2.0-flash# Proxy configuration (default: us)-browser-use -b remote run "task" --proxy-country gb # UK proxy-browser-use -b remote run "task" --proxy-country de # Germany proxy+browser-use -b remote run "task" --proxy-country uk-# Session reuse (run multiple tasks in same browser session)-browser-use -b remote run "task 1" --keep-alive-# Returns: session_id: abc-123-browser-use -b remote run "task 2" --session-id abc-123+# Session reuse+browser-use -b remote run "task 1" --keep-alive # Keep session alive after task+browser-use -b remote run "task 2" --session-id abc-123 # Reuse existing session# Execution modes-browser-use -b remote run "task" --no-wait # Async, returns task_id immediately-browser-use -b remote run "task" --stream # Stream status updatesbrowser-use -b remote run "task" --flash # Fast execution mode+browser-use -b remote run "task" --wait # Wait for completion (default: async)# Advanced optionsbrowser-use -b remote run "task" --thinking # Extended reasoning mode-browser-use -b remote run "task" --vision # Enable vision (default)-browser-use -b remote run "task" --no-vision # Disable vision-browser-use -b remote run "task" --wait # Wait for completion (default: async)+browser-use -b remote run "task" --no-vision # Disable vision (enabled by default)-# Use cloud profile (preserves cookies across sessions)-browser-use -b remote run "task" --profile <cloud-profile-id>+# Using a cloud profile (create session first, then run with --session-id)+browser-use session create --profile <cloud-profile-id> --keep-alive+# → returns session_id+browser-use -b remote run "task" --session-id <session-id># Task configurationbrowser-use -b remote run "task" --start-url https://example.com # Start from specific URLbrowser-use -b remote run "task" --allowed-domain example.com # Restrict navigation (repeatable)browser-use -b remote run "task" --metadata key=value # Task metadata (repeatable)-browser-use -b remote run "task" --secret API_KEY=xxx # Task secrets (repeatable)browser-use -b remote run "task" --skill-id skill-123 # Enable skills (repeatable)+browser-use -b remote run "task" --secret key=value # Secret metadata (repeatable)# Structured output and evaluationbrowser-use -b remote run "task" --structured-output '{"type":"object"}' # JSON schema for outputbrowser-use -b remote run "task" --judge # Enable judge mode-browser-use -b remote run "task" --judge-ground-truth "expected answer" # Expected answer for judge+browser-use -b remote run "task" --judge-ground-truth "expected answer"```-### Task Management (Remote Mode)--Manage cloud tasks when using remote mode:-+### Task Management```bashbrowser-use task list # List recent tasksbrowser-use task list --limit 20 # Show more tasks-browser-use task list --status running # Filter by status+browser-use task list --status finished # Filter by status (finished, stopped)browser-use task list --session <id> # Filter by session IDbrowser-use task list --json # JSON output-browser-use task status <task-id> # Get task status (token efficient)-browser-use task status <task-id> -c # Show all steps with reasoning-browser-use task status <task-id> -v # Show all steps with URLs + actions-browser-use task status <task-id> --last 5 # Show only last 5 steps-browser-use task status <task-id> --step 3 # Show specific step number-browser-use task status <task-id> --reverse # Show steps newest first+browser-use task status <task-id> # Get task status (latest step only)+browser-use task status <task-id> -c # All steps with reasoning+browser-use task status <task-id> -v # All steps with URLs + actions+browser-use task status <task-id> --last 5 # Last N steps only+browser-use task status <task-id> --step 3 # Specific step number+browser-use task status <task-id> --reverse # Newest firstbrowser-use task stop <task-id> # Stop a running taskbrowser-use task logs <task-id> # Get task execution logs```-**Token-efficient monitoring:** Default `task status` shows only the latest step. Use `-c` (compact) or `-v` (verbose) only when you need more context.--### Cloud Session Management (Remote Mode)--Manage cloud browser sessions:-+### Cloud Session Management```bashbrowser-use session list # List cloud sessionsbrowser-use session list --limit 20 # Show more sessionsbrowser-use session list --status active # Filter by statusbrowser-use session list --json # JSON output-browser-use session get <session-id> # Get session details+browser-use session get <session-id> # Get session details + live URLbrowser-use session get <session-id> --jsonbrowser-use session stop <session-id> # Stop a sessionbrowser-use session stop --all # Stop all active sessions-# Create a new cloud session manuallybrowser-use session create # Create with defaultsbrowser-use session create --profile <id> # With cloud profile-browser-use session create --proxy-country gb # With geographic proxy-browser-use session create --start-url https://example.com # Start at URL-browser-use session create --screen-size 1920x1080 # Custom screen size-browser-use session create --keep-alive # Keep session alive-browser-use session create --persist-memory # Persist memory between tasks+browser-use session create --proxy-country uk # With geographic proxy+browser-use session create --start-url https://example.com+browser-use session create --screen-size 1920x1080+browser-use session create --keep-alive+browser-use session create --persist-memory-# Share session publicly (for collaboration/debugging)-browser-use session share <session-id> # Create public share URL-browser-use session share <session-id> --delete # Delete public share+browser-use session share <session-id> # Create public share URL+browser-use session share <session-id> --delete # Delete public share```-## Exposing Local Dev Servers--If you're running a dev server locally and need a cloud browser to reach it, use Cloudflare tunnels:--```bash-# Start your dev server-npm run dev & # localhost:3000--# Expose it via Cloudflare tunnel-browser-use tunnel 3000-# → url: https://abc.trycloudflare.com--# Now the cloud browser can reach your local server-browser-use --browser remote open https://abc.trycloudflare.com-```--**Tunnel commands:**+### Tunnels```bashbrowser-use tunnel <port> # Start tunnel (returns URL)browser-use tunnel <port> # Idempotent - returns existing URL@@ -363,474 +264,247 @@ browser-use tunnel stop <port> # Stop tunnelbrowser-use tunnel stop --all # Stop all tunnels```-**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately.--Cloudflared is installed by `install.sh`. If missing, install manually (see Setup section).--## Running Subagents (Remote Mode)--Cloud sessions and tasks provide a powerful model for running **subagents** - autonomous browser agents that execute tasks in parallel.--### Key Concepts--- **Session = Agent**: Each cloud session is a browser agent with its own state (cookies, tabs, history)-- **Task = Work**: Tasks are jobs given to an agent. An agent can run multiple tasks sequentially-- **Parallel agents**: Run multiple sessions simultaneously for parallel work-- **Session reuse**: While a session is alive, you can assign it more tasks-- **Session lifecycle**: Once stopped, a session cannot be revived - start a new one--### Basic Subagent Workflow--```bash-# 1. Start a subagent task (creates new session automatically)-browser-use -b remote run "Search for AI news and summarize top 3 articles" --no-wait-# Returns: task_id: task-abc, session_id: sess-123--# 2. Check task progress-browser-use task status task-abc-# Shows: Status: running, or finished with output--# 3. View execution logs-browser-use task logs task-abc-```--### Running Parallel Subagents--Launch multiple agents to work simultaneously:-+### Session Management```bash-# Start 3 parallel research agents-browser-use -b remote run "Research competitor A pricing" --no-wait-# → task_id: task-1, session_id: sess-a--browser-use -b remote run "Research competitor B pricing" --no-wait-# → task_id: task-2, session_id: sess-b--browser-use -b remote run "Research competitor C pricing" --no-wait-# → task_id: task-3, session_id: sess-c--# Monitor all running tasks-browser-use task list --status running-# Shows all 3 tasks with their status--# Check individual task results as they complete-browser-use task status task-1-browser-use task status task-2-browser-use task status task-3+browser-use sessions # List active sessions+browser-use close # Close current session+browser-use close --all # Close all sessions```-### Reusing an Agent for Multiple Tasks--Keep a session alive to run sequential tasks in the same browser context:+### Profile Management+#### Local Chrome Profiles (`--browser real`)```bash-# Start first task, keep session alive-browser-use -b remote run "Log into example.com" --keep-alive --no-wait-# → task_id: task-1, session_id: sess-123--# Wait for login to complete...-browser-use task status task-1-# → Status: finished--# Give the same agent another task (reuses login session)-browser-use -b remote run "Navigate to settings and export data" --session-id sess-123 --no-wait-# → task_id: task-2, session_id: sess-123 (same session!)--# Agent retains cookies, login state, etc. from previous task+browser-use -b real profile list # List local Chrome profiles+browser-use -b real profile cookies "Default" # Show cookie domains in profile```-### Managing Active Agents-+#### Cloud Profiles (`--browser remote`)```bash-# List all active agents (sessions)-browser-use session list --status active-# Shows: sess-123 [active], sess-456 [active], ...--# Get details on a specific agent-browser-use session get sess-123-# Shows: status, started time, live URL for viewing--# Stop a specific agent-browser-use session stop sess-123--# Stop all agents at once-browser-use session stop --all+browser-use -b remote profile list # List cloud profiles+browser-use -b remote profile list --page 2 --page-size 50+browser-use -b remote profile get <id> # Get profile details+browser-use -b remote profile create # Create new cloud profile+browser-use -b remote profile create --name "My Profile"+browser-use -b remote profile update <id> --name "New"+browser-use -b remote profile delete <id>```-### Stopping Tasks vs Sessions-+#### Syncing```bash-# Stop a running task (session may continue if --keep-alive was used)-browser-use task stop task-abc--# Stop an entire agent/session (terminates all its tasks)-browser-use session stop sess-123+browser-use profile sync --from "Default" --domain github.com # Domain-specific+browser-use profile sync --from "Default" # Full profile+browser-use profile sync --from "Default" --name "Custom Name" # With custom name```-### Custom Agent Configuration-+### Server Control```bash-# Default: US proxy, auto LLM selection-browser-use -b remote run "task" --no-wait--# Explicit configuration-browser-use -b remote run "task" \- --llm gpt-4o \- --proxy-country gb \- --keep-alive \- --no-wait--# With cloud profile (preserves cookies across sessions)-browser-use -b remote run "task" --profile <profile-id> --no-wait+browser-use server logs # View server logs```-### Monitoring Subagents+## Common Workflows-**Task status is designed for token efficiency.** Default output is minimal - only expand when needed:+### Exposing Local Dev Servers-| Mode | Flag | Tokens | Use When |-|------|------|--------|----------|-| Default | (none) | Low | Polling progress |-| Compact | `-c` | Medium | Need full reasoning |-| Verbose | `-v` | High | Debugging actions |+Use when you have a local dev server and need a cloud browser to reach it.-**Recommended workflow:**+**Core workflow:** Start dev server → create tunnel → browse the tunnel URL remotely.```bash-# 1. Launch task-browser-use -b remote run "task" --no-wait-# → task_id: abc-123--# 2. Poll with default (token efficient) - only latest step-browser-use task status abc-123-# ✅ abc-123... [finished] $0.009 15s-# ... 1 earlier steps-# 2. I found the information and extracted...--# 3. ONLY IF task failed or need context: use --compact-browser-use task status abc-123 -c--# 4. ONLY IF debugging specific actions: use --verbose-browser-use task status abc-123 -v-```--**For long tasks (50+ steps):**-```bash-browser-use task status <id> -c --last 5 # Last 5 steps only-browser-use task status <id> -c --reverse # Newest first-browser-use task status <id> -v --step 10 # Inspect specific step-```--**Live view**: Watch an agent work in real-time:-```bash-browser-use session get <session-id>-# → Live URL: https://live.browser-use.com?wss=...-# Open this URL in your browser to watch the agent-```+# 1. Start your dev server+npm run dev & # localhost:3000-**Detect stuck tasks**: If cost/duration stops increasing, the task may be stuck:-```bash-browser-use task status <task-id>-# 🔄 abc-123... [started] $0.009 45s ← if cost doesn't change, task is stuck-```+# 2. Expose it via Cloudflare tunnel+browser-use tunnel 3000+# → url: https://abc.trycloudflare.com-**Logs**: Only available after task completes:-```bash-browser-use task logs <task-id> # Works after task finishes+# 3. Now the cloud browser can reach your local server+browser-use --browser remote open https://abc.trycloudflare.com+browser-use state+browser-use screenshot```-### Cleanup+**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.-Always clean up sessions after parallel work:-```bash-# Stop all active agents-browser-use session stop --all+### Authenticated Browsing with Profiles-# Or stop specific sessions-browser-use session stop <session-id>-```--### Troubleshooting Subagents--**Session reuse fails after `task stop`**:-If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Solution: create a new agent instead.-```bash-# This may fail:-browser-use task stop <task-id>-browser-use -b remote run "new task" --session-id <same-session> # Might get stuck+Use when a task requires browsing a site the user is already logged into (e.g. Gmail, GitHub, internal tools).-# Do this instead:-browser-use -b remote run "new task" --profile <profile-id> # Fresh session-```+**Core workflow:** Check existing profiles → ask user which profile and browser mode → browse with that profile. Only sync cookies if no suitable profile exists.-**Task stuck at "started"**:-- Check cost with `task status` - if not increasing, task is stuck-- View live URL with `session get` to see what's happening-- Stop the task and create a new agent+**Before browsing an authenticated site, the agent MUST:**+1. Ask the user whether to use **real** (local Chrome) or **remote** (cloud) browser+2. List available profiles for that mode+3. Ask which profile to use+4. If no profile has the right cookies, offer to sync (see below)-**Sessions persist after tasks complete**:-Tasks finishing doesn't auto-stop sessions. Clean up manually:-```bash-browser-use session list --status active # See lingering sessions-browser-use session stop --all # Clean up-```+#### Step 1: Check existing profiles-### Session Management```bash-browser-use sessions # List active sessions-browser-use close # Close current session-browser-use close --all # Close all sessions-```--### Profile Management+# Option A: Local Chrome profiles (--browser real)+browser-use -b real profile list+# → Default: Person 1 ([email protected])+# → Profile 1: Work ([email protected])-#### Local Chrome Profiles (`--browser real`)-```bash-browser-use -b real profile list # List local Chrome profiles+# Option B: Cloud profiles (--browser remote)+browser-use -b remote profile list+# → abc-123: "Chrome - Default (github.com)"+# → def-456: "Work profile"```-**Before opening a real browser (`--browser real`)**, always ask the user if they want to use a specific Chrome profile or no profile. Use `profile list` to show available profiles:+#### Step 2: Browse with the chosen profile```bash-browser-use -b real profile list-# Output: Default: Person 1 ([email protected])-# Profile 1: Work ([email protected])--# With a specific profile (has that profile's cookies/logins)-browser-use --browser real --profile "Profile 1" open https://gmail.com--# Without a profile (fresh browser, no existing logins)-browser-use --browser real open https://gmail.com+# Real browser — uses local Chrome with existing login sessions+browser-use --browser real --profile "Default" open https://github.com-# Headless mode (no visible window) - useful for cookie export-browser-use --browser real --profile "Default" cookies export /tmp/cookies.json+# Cloud browser — uses cloud profile with synced cookies+browser-use --browser remote --profile abc-123 open https://github.com```-Each Chrome profile has its own cookies, history, and logged-in sessions. Choosing the right profile determines whether sites will be pre-authenticated.--#### Cloud Profiles (`--browser remote`)--Cloud profiles store browser state (cookies) in Browser-Use Cloud, persisting across sessions. Requires `BROWSER_USE_API_KEY`.--```bash-browser-use -b remote profile list # List cloud profiles-browser-use -b remote profile list --page 2 --page-size 50 # Pagination-browser-use -b remote profile get <id> # Get profile details-browser-use -b remote profile create # Create new cloud profile-browser-use -b remote profile create --name "My Profile" # Create with name-browser-use -b remote profile update <id> --name "New" # Rename profile-browser-use -b remote profile delete <id> # Delete profile-```+The user is already authenticated — no login needed.-Use a cloud profile with `--browser remote --profile <id>`:+**Note:** Cloud profile cookies can expire over time. If authentication fails, re-sync cookies from the local Chrome profile.-```bash-browser-use --browser remote --profile abc-123 open https://example.com-```+#### Step 3: Syncing cookies (only if needed)-### Syncing Cookies to Cloud+If the user wants to use a cloud browser but no cloud profile has the right cookies, sync them from a local Chrome profile.-**⚠️ IMPORTANT: Before syncing cookies from a local browser to the cloud, the agent MUST:**-1. Ask the user which local Chrome profile to use (`browser-use -b real profile list`)-2. Ask which domain(s) to sync - do NOT default to syncing the full profile+**Before syncing, the agent MUST:**+1. Ask which local Chrome profile to use+2. Ask which domain(s) to sync — do NOT default to syncing the full profile3. Confirm before proceeding-**Default behavior:** Create a NEW cloud profile for each domain sync. This ensures clear separation of concerns for cookies. Users can add cookies to existing profiles if needed.--**Step 1: List available profiles and cookies**-+**Check what cookies a local profile has:**```bash-# List local Chrome profiles-browser-use -b real profile list-# → Default: Person 1 ([email protected])-# → Profile 1: Work ([email protected])--# See what cookies are in a profilebrowser-use -b real profile cookies "Default"# → youtube.com: 23# → google.com: 18# → github.com: 2```-**Step 2: Sync cookies (three levels of control)**--**1. Domain-specific sync (recommended default)**+**Domain-specific sync (recommended):**```bash-browser-use profile sync --from "Default" --domain youtube.com-# Creates new cloud profile: "Chrome - Default (youtube.com)"-# Only syncs youtube.com cookies+browser-use profile sync --from "Default" --domain github.com+# Creates new cloud profile: "Chrome - Default (github.com)"+# Only syncs github.com cookies```-This is the recommended approach - sync only the cookies you need.-**2. Full profile sync (use with caution)**+**Full profile sync (use with caution):**```bashbrowser-use profile sync --from "Default"-# Syncs ALL cookies from the profile+# Syncs ALL cookies — includes sensitive data, tracking cookies, every session token```-⚠️ **Warning:** This syncs ALL cookies including sensitive data, tracking cookies, session tokens for every site, etc. Only use when the user explicitly needs their entire browser state.+Only use when the user explicitly needs their entire browser state.-**3. Fine-grained control (advanced)**+**Fine-grained control (advanced):**```bash-# Export cookies to file+# Export cookies to file, manually edit, then importbrowser-use --browser real --profile "Default" cookies export /tmp/cookies.json--# Manually edit the JSON to keep only specific cookies--# Import to cloud profilebrowser-use --browser remote --profile <id> cookies import /tmp/cookies.json```-For users who need individual cookie-level control.--**Step 3: Use the synced profile**+**Use the synced profile:**```bash-browser-use --browser remote --profile <id> open https://youtube.com+browser-use --browser remote --profile <id> open https://github.com```-**Adding cookies to existing profiles:**-```bash-# Sync additional domain to existing profile-browser-use --browser real --profile "Default" cookies export /tmp/cookies.json-browser-use --browser remote --profile <existing-id> cookies import /tmp/cookies.json-```+### Running Subagents-**Managing profiles:**-```bash-browser-use profile update <id> --name "New Name" # Rename-browser-use profile delete <id> # Delete-```+Use cloud sessions to run autonomous browser agents in parallel.-### Server Control-```bash-browser-use server status # Check if server is running-browser-use server stop # Stop server-browser-use server logs # View server logs-```+**Core workflow:** Launch task(s) with `run` → poll with `task status` → collect results → clean up sessions.-### Setup-```bash-browser-use install # Install Chromium and system dependencies-```+- **Session = Agent**: Each cloud session is a browser agent with its own state+- **Task = Work**: Jobs given to an agent; an agent can run multiple tasks sequentially+- **Session lifecycle**: Once stopped, a session cannot be revived — start a new one-## Global Options+#### Launching Tasks-| Option | Description |-|--------|-------------|-| `--session NAME` | Use named session (default: "default") |-| `--browser MODE` | Browser mode: chromium, real, remote |-| `--headed` | Show browser window (chromium mode) |-| `--profile NAME` | Browser profile (local name or cloud ID) |-| `--json` | Output as JSON |-| `--api-key KEY` | Override API key |-| `--mcp` | Run as MCP server via stdin/stdout |--**Session behavior**: All commands without `--session` use the same "default" session. The browser stays open and is reused across commands. Use `--session NAME` to run multiple browsers in parallel.--## API Key Configuration--Some features (`run`, `extract`, `--browser remote`) require an API key. The CLI checks these locations in order:+```bash+# Single task (async by default — returns immediately)+browser-use -b remote run "Search for AI news and summarize top 3 articles"+# → task_id: task-abc, session_id: sess-123-1. `--api-key` command line flag-2. `BROWSER_USE_API_KEY` environment variable-3. `~/.config/browser-use/config.json` file+# Parallel tasks — each gets its own session+browser-use -b remote run "Research competitor A pricing"+# → task_id: task-1, session_id: sess-a+browser-use -b remote run "Research competitor B pricing"+# → task_id: task-2, session_id: sess-b+browser-use -b remote run "Research competitor C pricing"+# → task_id: task-3, session_id: sess-c-To configure permanently:-```bash-mkdir -p ~/.config/browser-use-echo '{"api_key": "your-key-here"}' > ~/.config/browser-use/config.json+# Sequential tasks in same session (reuses cookies, login state, etc.)+browser-use -b remote run "Log into example.com" --keep-alive+# → task_id: task-1, session_id: sess-123+browser-use task status task-1 # Wait for completion+browser-use -b remote run "Export settings" --session-id sess-123+# → task_id: task-2, session_id: sess-123 (same session)```-## Examples+#### Managing & Stopping-### Form Submission```bash-browser-use open https://example.com/contact-browser-use state-# Shows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"-browser-use input 0 "John Doe"-browser-use input 1 "[email protected]"-browser-use input 2 "Hello, this is a test message."-browser-use click 3-browser-use state # Verify success+browser-use task list --status finished # See completed tasks+browser-use task stop task-abc # Stop a task (session may continue if --keep-alive)+browser-use session stop sess-123 # Stop an entire session (terminates its tasks)+browser-use session stop --all # Stop all sessions```-### Multi-Session Workflows-```bash-browser-use --session work open https://work.example.com-browser-use --session personal open https://personal.example.com-browser-use --session work state # Check work session-browser-use --session personal state # Check personal session-browser-use close --all # Close both sessions-```+#### Monitoring-### Data Extraction with Python-```bash-browser-use open https://example.com/products-browser-use python "-products = []-for i in range(20):- browser.scroll('down')-browser.screenshot('products.png')-"-browser-use python "print(f'Captured {len(products)} products')"-```+**Task status is designed for token efficiency.** Default output is minimal — only expand when needed:++| Mode | Flag | Tokens | Use When |+|------|------|--------|----------|+| Default | (none) | Low | Polling progress |+| Compact | `-c` | Medium | Need full reasoning |+| Verbose | `-v` | High | Debugging actions |-### Using Real Browser (Logged-In Sessions)```bash-browser-use --browser real open https://gmail.com-# Uses your actual Chrome with existing login sessions-browser-use state # Already logged in!+# For long tasks (50+ steps)+browser-use task status <id> -c --last 5 # Last 5 steps only+browser-use task status <id> -v --step 10 # Inspect specific step```-## Common Patterns+**Live view**: `browser-use session get <session-id>` returns a live URL to watch the agent.-### Test a Local Dev Server with Cloud Browser+**Detect stuck tasks**: If cost/duration in `task status` stops increasing, the task is stuck — stop it and start a new agent.-```bash-# Start dev server-npm run dev & # localhost:3000--# Tunnel it-browser-use tunnel 3000-# → url: https://abc.trycloudflare.com+**Logs**: `browser-use task logs <task-id>` — only available after task completes.-# Browse with cloud browser-browser-use --browser remote open https://abc.trycloudflare.com-browser-use state-browser-use screenshot-```+## Global Options-### Screenshot Loop for Visual Verification+| Option | Description |+|--------|-------------|+| `--session NAME` | Use named session (default: "default") |+| `--browser MODE` | Browser mode: chromium, real, remote |+| `--headed` | Show browser window (chromium mode) |+| `--profile NAME` | Browser profile (local name or cloud ID). Works with `open`, `session create`, etc. — does NOT work with `run` (use `--session-id` instead) |+| `--json` | Output as JSON |+| `--mcp` | Run as MCP server via stdin/stdout |-```bash-browser-use open https://example.com-for i in 1 2 3 4 5; do- browser-use scroll down- browser-use screenshot "page_$i.png"-done-```+**Session behavior**: All commands without `--session` use the same "default" session. The browser stays open and is reused across commands. Use `--session NAME` to run multiple browsers in parallel.## Tips1. **Always run `browser-use 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 parsing** output programmatically+3. **Sessions persist** — the browser stays open between commands+4. **Use `--json`** for programmatic parsing5. **Python variables persist** across `browser-use python` commands within a session-6. **Real browser mode** preserves your login sessions and extensions-7. **CLI aliases**: `bu`, `browser`, and `browseruse` all work identically to `browser-use`+6. **CLI aliases**: `bu`, `browser`, and `browseruse` all work identically to `browser-use`## Troubleshooting**Run diagnostics first:**```bash-browser-use doctor # Check installation status+browser-use doctor```**Browser won't start?**```bash-browser-use install # Install/reinstall Chromium-browser-use server stop # Stop any stuck server+browser-use close --all # Close all sessionsbrowser-use --headed open <url> # Try with visible window```@@ -848,10 +522,23 @@ browser-use close --all # Clean slatebrowser-use open <url> # Fresh start```+**Session reuse fails after `task stop`**:+If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Create a new session instead:+```bash+browser-use session create --profile <profile-id> --keep-alive+browser-use -b remote run "new task" --session-id <new-session-id>+```++**Task stuck at "started"**: Check cost with `task status` — if not increasing, the task is stuck. View live URL with `session get`, then stop and start a new agent.++**Sessions persist after tasks complete**: Tasks finishing doesn't auto-stop sessions. Run `browser-use session stop --all` to clean up.+## Cleanup-**Always close the browser when done.** Run this after completing browser automation:+**Always close the browser when done:**```bash-browser-use close+browser-use close # Close browser session+browser-use session stop --all # Stop cloud sessions (if any)+browser-use tunnel stop --all # Stop tunnels (if any)```diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdindex 15400fee2..494f6f700 100644--- a/skills/remote-browser/SKILL.md+++ b/skills/remote-browser/SKILL.md@@ -8,49 +8,17 @@ allowed-tools: Bash(browser-use:*)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 cloud browser — no local Chrome needed.-## Setup+## Prerequisites-**Remote-only install (recommended for sandboxed agents)**-```bash-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only-```--This configures browser-use to only use cloud browsers:-- No Chromium download (~300MB saved)-- `browser-use open <url>` automatically uses remote mode (no `--browser` flag needed)-- If API key is available, you can also pass it during install:- ```bash- curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only --api-key bu_xxx- ```+Before using this skill, `browser-use` must be installed and configured. Run diagnostics to verify:-**Manual install (alternative)**-```bash-pip install "browser-use[cli]"--# Install cloudflared for tunneling:-# macOS:-brew install cloudflared--# Linux:-curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/.local/bin/cloudflared && chmod +x ~/.local/bin/cloudflared--# Windows:-winget install Cloudflare.cloudflared-```--**Then configure your API key:**-```bash-export BROWSER_USE_API_KEY=bu_xxx # Required for cloud browser-```--**Verify installation:**```bashbrowser-use doctor```## Core Workflow-When installed with `--remote-only`, commands automatically use the cloud browser — no `--browser` flag needed:+Commands use the cloud browser:```bash# Step 1: Start session (automatically uses remote mode)@@ -69,54 +37,55 @@ browser-use screenshot page.png # Save screenshot to filebrowser-use close # Close browser and release resources```-### Understanding Installation Modes--| Install Command | Available Modes | Default Mode | Use Case |-|-----------------|-----------------|--------------|----------|-| `--remote-only` | remote | remote | Sandboxed agents, no GUI |-| `--local-only` | chromium, real | chromium | Local development |-| `--full` | chromium, real, remote | chromium | Full flexibility |+## Essential Commands-When only one mode is installed, it becomes the default and no `--browser` flag is needed.+```bash+# Navigation+browser-use open <url> # Navigate to URL+browser-use back # Go back+browser-use scroll down # Scroll down (--amount N for pixels)-## Exposing Local Dev Servers+# 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-If you're running a dev server on the remote machine and need the cloud browser to reach it:+# Interactions (use indices from state)+browser-use click <index> # Click element+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 select <index> "option" # Select dropdown option-```bash-# Start your dev server-python -m http.server 3000 &+# Data Extraction+browser-use eval "document.title" # Execute JavaScript+browser-use get text <index> # Get element text+browser-use get html --selector "h1" # Get scoped HTML-# Expose it via Cloudflare tunnel-browser-use tunnel 3000-# → url: https://abc.trycloudflare.com+# Wait+browser-use wait selector "h1" # Wait for element+browser-use wait text "Success" # Wait for text-# Now the cloud browser can reach your local server-browser-use open https://abc.trycloudflare.com-```+# Session+browser-use close # Close browser session-Tunnel commands:-```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+# AI Agent+browser-use run "task" # Run agent (async by default)+browser-use task status <id> # Check task progress```-**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately.--Cloudflared is installed by `install.sh --remote-only`. If missing, install manually (see Setup section).-## Commands-### Navigation+### Navigation & Tabs```bashbrowser-use open <url> # Navigate to URLbrowser-use back # Go back in historybrowser-use scroll down # Scroll downbrowser-use scroll up # Scroll upbrowser-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```### Page State@@ -127,7 +96,7 @@ browser-use screenshot path.png # Save screenshot to filebrowser-use screenshot --full p.png # Full page screenshot```-### Interactions (use indices from `state`)+### Interactions```bashbrowser-use click <index> # Click elementbrowser-use type "text" # Type into focused element@@ -140,10 +109,11 @@ browser-use dblclick <index> # Double-clickbrowser-use rightclick <index> # Right-click```+Use indices from `browser-use state`.+### JavaScript & Data```bashbrowser-use eval "document.title" # Execute JavaScript-browser-use extract "all prices" # Extract data using LLMbrowser-use get title # Get page titlebrowser-use get html # Get page HTMLbrowser-use get html --selector "h1" # Scoped HTML@@ -153,20 +123,12 @@ browser-use get attributes <index> # Get element attributesbrowser-use get bbox <index> # Get bounding box (x, y, width, height)```-### 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)-```-### Cookies```bashbrowser-use cookies get # Get all cookiesbrowser-use cookies get --url <url> # Get cookies for specific URLbrowser-use cookies set <name> <val> # Set a cookie-browser-use cookies set name val --domain .example.com --secure # With options+browser-use cookies set name val --domain .example.com --securebrowser-use cookies set name val --same-site Strict # SameSite: Strict, Lax, Nonebrowser-use cookies set name val --expires 1735689600 # Expiration timestampbrowser-use cookies clear # Clear all cookies@@ -175,14 +137,15 @@ browser-use cookies export <file> # Export to JSONbrowser-use cookies import <file> # Import from JSON```-### Tab Management+### Wait Conditions```bash-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 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 (Persistent Session)+### Python Execution```bashbrowser-use python "x = 42" # Set variablebrowser-use python "print(x)" # Access variable (prints: 42)@@ -193,19 +156,11 @@ browser-use python --file script.py # Run Python file```The Python session maintains state across commands. The `browser` object provides:-- `browser.url` - Current page URL-- `browser.title` - Page title-- `browser.html` - Get page HTML-- `browser.goto(url)` - Navigate-- `browser.click(index)` - Click element-- `browser.type(text)` - Type text-- `browser.input(index, text)` - Click element, then type-- `browser.keys(keys)` - Send keyboard keys-- `browser.screenshot(path)` - Take screenshot-- `browser.scroll(direction, amount)` - Scroll page-- `browser.back()` - Go back in history-- `browser.wait(seconds)` - Sleep/pause execution-- `browser.extract(query)` - Extract data using LLM+- `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)` — interactions+- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual+- `browser.wait(seconds)`, `browser.extract(query)` — utilities### Agent Tasks```bash@@ -215,73 +170,60 @@ browser-use run "Extract all product prices" --max-steps 50# Specify LLM modelbrowser-use run "task" --llm gpt-4obrowser-use run "task" --llm claude-sonnet-4-20250514-browser-use run "task" --llm gemini-2.0-flash# Proxy configuration (default: us)-browser-use run "task" --proxy-country gb # UK proxy-browser-use run "task" --proxy-country de # Germany proxy+browser-use run "task" --proxy-country uk-# Session reuse (run multiple tasks in same browser session)-browser-use run "task 1" --keep-alive-# Returns: session_id: abc-123-browser-use run "task 2" --session-id abc-123+# Session reuse+browser-use run "task 1" --keep-alive # Keep session alive after task+browser-use run "task 2" --session-id abc-123 # Reuse existing session# Execution modes-browser-use run "task" --no-wait # Async, returns task_id immediately-browser-use run "task" --wait # Wait for completion-browser-use run "task" --stream # Stream status updatesbrowser-use run "task" --flash # Fast execution mode+browser-use run "task" --wait # Wait for completion (default: async)# Advanced optionsbrowser-use run "task" --thinking # Extended reasoning mode-browser-use run "task" --vision # Enable vision (default)-browser-use run "task" --no-vision # Disable vision+browser-use run "task" --no-vision # Disable vision (enabled by default)-# Use cloud profile (preserves cookies across sessions)-browser-use run "task" --profile <cloud-profile-id>+# Using a cloud profile (create session first, then run with --session-id)+browser-use session create --profile <cloud-profile-id> --keep-alive+# → returns session_id+browser-use run "task" --session-id <session-id># Task configurationbrowser-use run "task" --start-url https://example.com # Start from specific URLbrowser-use run "task" --allowed-domain example.com # Restrict navigation (repeatable)browser-use run "task" --metadata key=value # Task metadata (repeatable)-browser-use run "task" --secret API_KEY=xxx # Task secrets (repeatable)browser-use run "task" --skill-id skill-123 # Enable skills (repeatable)+browser-use run "task" --secret key=value # Secret metadata (repeatable)# Structured output and evaluationbrowser-use run "task" --structured-output '{"type":"object"}' # JSON schema for outputbrowser-use run "task" --judge # Enable judge mode-browser-use run "task" --judge-ground-truth "answer" # Expected answer for judge+browser-use run "task" --judge-ground-truth "answer"```### Task Management--Manage cloud tasks:-```bashbrowser-use task list # List recent tasksbrowser-use task list --limit 20 # Show more tasks-browser-use task list --status running # Filter by status-browser-use task list --status finished+browser-use task list --status finished # Filter by status (finished, stopped)browser-use task list --session <id> # Filter by session IDbrowser-use task list --json # JSON outputbrowser-use task status <task-id> # Get task status (latest step only)-browser-use task status <task-id> -c # Compact: all steps with reasoning-browser-use task status <task-id> -v # Verbose: full details with URLs + actions-browser-use task status <task-id> --last 5 # Show only last 5 steps-browser-use task status <task-id> --step 3 # Show specific step number-browser-use task status <task-id> --reverse # Show steps newest first-browser-use task status <task-id> --json+browser-use task status <task-id> -c # All steps with reasoning+browser-use task status <task-id> -v # All steps with URLs + actions+browser-use task status <task-id> --last 5 # Last N steps only+browser-use task status <task-id> --step 3 # Specific step number+browser-use task status <task-id> --reverse # Newest firstbrowser-use task stop <task-id> # Stop a running task-browser-use task logs <task-id> # Get task execution logs```### Cloud Session Management--Manage cloud browser sessions:-```bashbrowser-use session list # List cloud sessionsbrowser-use session list --limit 20 # Show more sessions@@ -294,175 +236,114 @@ browser-use session get <session-id> --jsonbrowser-use session stop <session-id> # Stop a sessionbrowser-use session stop --all # Stop all active sessions-# Create a new cloud session manuallybrowser-use session create # Create with defaultsbrowser-use session create --profile <id> # With cloud profile-browser-use session create --proxy-country gb # With geographic proxy-browser-use session create --start-url https://example.com # Start at URL-browser-use session create --screen-size 1920x1080 # Custom screen size-browser-use session create --keep-alive # Keep session alive-browser-use session create --persist-memory # Persist memory between tasks--# Share session publicly (for collaboration/debugging)-browser-use session share <session-id> # Create public share URL-browser-use session share <session-id> --delete # Delete public share+browser-use session create --proxy-country uk # With geographic proxy+browser-use session create --start-url https://example.com+browser-use session create --screen-size 1920x1080+browser-use session create --keep-alive+browser-use session create --persist-memory++browser-use session share <session-id> # Create public share URL+browser-use session share <session-id> --delete # Delete public share```### Cloud Profile Management--Cloud profiles store browser state (cookies) persistently across sessions. Use profiles to maintain login sessions.-```bashbrowser-use profile list # List cloud profiles-browser-use profile list --page 2 --page-size 50 # Pagination+browser-use profile list --page 2 --page-size 50browser-use profile get <id> # Get profile detailsbrowser-use profile create # Create new profile-browser-use profile create --name "My Profile" # Create with name-browser-use profile update <id> --name "New Name" # Rename profile-browser-use profile delete <id> # Delete profile+browser-use profile create --name "My Profile"+browser-use profile update <id> --name "New Name"+browser-use profile delete <id>```-**Using profiles:**+### Tunnels```bash-# Run task with profile (preserves cookies)-browser-use run "Log into site" --profile <profile-id> --keep-alive--# Create session with profile-browser-use session create --profile <profile-id>--# Open URL with profile-browser-use open https://example.com --profile <profile-id>+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```-**Import cookies to cloud profile:**+### Session Management```bash-# Export cookies from current session-browser-use cookies export /tmp/cookies.json--# Import to cloud profile-browser-use cookies import /tmp/cookies.json --profile <profile-id>+browser-use sessions # List active sessions+browser-use close # Close current session+browser-use close --all # Close all sessions```-## Running Subagents--Cloud sessions and tasks provide a powerful model for running **subagents** - autonomous browser agents that execute tasks in parallel.--### Key Concepts--- **Session = Agent**: Each cloud session is a browser agent with its own state (cookies, tabs, history)-- **Task = Work**: Tasks are jobs given to an agent. An agent can run multiple tasks sequentially-- **Parallel agents**: Run multiple sessions simultaneously for parallel work-- **Session reuse**: While a session is alive, you can assign it more tasks-- **Session lifecycle**: Once stopped, a session cannot be revived - start a new one--### Basic Subagent Workflow--```bash-# 1. Start a subagent task (creates new session automatically)-browser-use run "Search for AI news and summarize top 3 articles" --no-wait-# Returns: task_id: task-abc, session_id: sess-123--# 2. Check task progress-browser-use task status task-abc-# Shows: Status: running, or finished with output+## Common Workflows-# 3. View execution logs-browser-use task logs task-abc-```+### Exposing Local Dev Servers-### Running Parallel Subagents+Use when you have a dev server on the remote machine and need the cloud browser to reach it.-Launch multiple agents to work simultaneously:+**Core workflow:** Start dev server → create tunnel → browse the tunnel URL.```bash-# Start 3 parallel research agents-browser-use run "Research competitor A pricing" --no-wait-# → task_id: task-1, session_id: sess-a--browser-use run "Research competitor B pricing" --no-wait-# → task_id: task-2, session_id: sess-b--browser-use run "Research competitor C pricing" --no-wait-# → task_id: task-3, session_id: sess-c+# 1. Start your dev server+python -m http.server 3000 &-# Monitor all running tasks-browser-use task list --status running-# Shows all 3 tasks with their status+# 2. Expose it via Cloudflare tunnel+browser-use tunnel 3000+# → url: https://abc.trycloudflare.com-# Check individual task results as they complete-browser-use task status task-1-browser-use task status task-2-browser-use task status task-3+# 3. Now the cloud browser can reach your local server+browser-use open https://abc.trycloudflare.com+browser-use state+browser-use screenshot```-### Reusing an Agent for Multiple Tasks+**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.-Keep a session alive to run sequential tasks in the same browser context:+### Running Subagents-```bash-# Start first task, keep session alive-browser-use run "Log into example.com" --keep-alive --no-wait-# → task_id: task-1, session_id: sess-123+Use cloud sessions to run autonomous browser agents in parallel.-# Wait for login to complete...-browser-use task status task-1-# → Status: finished+**Core workflow:** Launch task(s) with `run` → poll with `task status` → collect results → clean up sessions.-# Give the same agent another task (reuses login session)-browser-use run "Navigate to settings and export data" --session-id sess-123 --no-wait-# → task_id: task-2, session_id: sess-123 (same session!)+- **Session = Agent**: Each cloud session is a browser agent with its own state+- **Task = Work**: Jobs given to an agent; an agent can run multiple tasks sequentially+- **Session lifecycle**: Once stopped, a session cannot be revived — start a new one-# Agent retains cookies, login state, etc. from previous task-```--### Managing Active Agents+#### Launching Tasks```bash-# List all active agents (sessions)-browser-use session list --status active-# Shows: sess-123 [active], sess-456 [active], ...--# Get details on a specific agent-browser-use session get sess-123-# Shows: status, started time, live URL for viewing+# Single task (async by default — returns immediately)+browser-use run "Search for AI news and summarize top 3 articles"+# → task_id: task-abc, session_id: sess-123-# Stop a specific agent-browser-use session stop sess-123--# Stop all agents at once-browser-use session stop --all-```--### Stopping Tasks vs Sessions--```bash-# Stop a running task (session may continue if --keep-alive was used)-browser-use task stop task-abc+# Parallel tasks — each gets its own session+browser-use run "Research competitor A pricing"+# → task_id: task-1, session_id: sess-a+browser-use run "Research competitor B pricing"+# → task_id: task-2, session_id: sess-b+browser-use run "Research competitor C pricing"+# → task_id: task-3, session_id: sess-c-# Stop an entire agent/session (terminates all its tasks)-browser-use session stop sess-123+# Sequential tasks in same session (reuses cookies, login state, etc.)+browser-use run "Log into example.com" --keep-alive+# → task_id: task-1, session_id: sess-123+browser-use task status task-1 # Wait for completion+browser-use run "Export settings" --session-id sess-123+# → task_id: task-2, session_id: sess-123 (same session)```-### Custom Agent Configuration+#### Managing & Stopping```bash-# Default: US proxy, auto LLM selection-browser-use run "task" --no-wait--# Explicit configuration-browser-use run "task" \- --llm gpt-4o \- --proxy-country gb \- --keep-alive \- --no-wait--# With cloud profile (preserves cookies across sessions)-browser-use run "task" --profile <profile-id> --no-wait+browser-use task list --status finished # See completed tasks+browser-use task stop task-abc # Stop a task (session may continue if --keep-alive)+browser-use session stop sess-123 # Stop an entire session (terminates its tasks)+browser-use session stop --all # Stop all sessions```-### Monitoring Subagents+#### Monitoring-**Task status is designed for token efficiency.** Default output is minimal - only expand when needed:+**Task status is designed for token efficiency.** Default output is minimal — only expand when needed:| Mode | Flag | Tokens | Use When ||------|------|--------|----------|@@ -470,183 +351,71 @@ browser-use run "task" --profile <profile-id> --no-wait| Compact | `-c` | Medium | Need full reasoning || Verbose | `-v` | High | Debugging actions |-**Recommended workflow:**--```bash-# 1. Launch task-browser-use run "task" --no-wait-# → task_id: abc-123--# 2. Poll with default (token efficient) - only latest step-browser-use task status abc-123-# ✅ abc-123... [finished] $0.009 15s-# ... 1 earlier steps-# 2. I found the information and extracted...--# 3. ONLY IF task failed or need context: use --compact-browser-use task status abc-123 -c--# 4. ONLY IF debugging specific actions: use --verbose-browser-use task status abc-123 -v-```--**For long tasks (50+ steps):**```bash+# For long tasks (50+ steps)browser-use task status <id> -c --last 5 # Last 5 steps only-browser-use task status <id> -c --reverse # Newest firstbrowser-use task status <id> -v --step 10 # Inspect specific step```-**Live view**: Watch an agent work in real-time:-```bash-browser-use session get <session-id>-# → Live URL: https://live.browser-use.com?wss=...-```--**Detect stuck tasks**: If cost/duration stops increasing, the task may be stuck:-```bash-browser-use task status <task-id>-# 🔄 abc-123... [started] $0.009 45s ← if cost doesn't change, task is stuck-```--**Logs**: Only available after task completes:-```bash-browser-use task logs <task-id> # Works after task finishes-```--### Cleanup--Always clean up sessions after parallel work:-```bash-# Stop all active agents-browser-use session stop --all--# Or stop specific sessions-browser-use session stop <session-id>-```--### Troubleshooting--**Session reuse fails after `task stop`**:-If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Solution: create a new agent instead.-```bash-# This may fail:-browser-use task stop <task-id>-browser-use run "new task" --session-id <same-session> # Might get stuck--# Do this instead:-browser-use run "new task" --profile <profile-id> # Fresh session-```--**Task stuck at "started"**:-- Check cost with `task status` - if not increasing, task is stuck-- View live URL with `session get` to see what's happening-- Stop the task and create a new agent+**Live view**: `browser-use session get <session-id>` returns a live URL to watch the agent.-**Sessions persist after tasks complete**:-Tasks finishing doesn't auto-stop sessions. Clean up manually:-```bash-browser-use session list --status active # See lingering sessions-browser-use session stop --all # Clean up-```+**Detect stuck tasks**: If cost/duration in `task status` stops increasing, the task is stuck — stop it and start a new agent.-### Session Management-```bash-browser-use sessions # List active sessions-browser-use close # Close current session-browser-use close --all # Close all sessions-```+**Logs**: `browser-use task logs <task-id>` — only available after task completes.-### Global Options+## Global Options| Option | Description ||--------|-------------|| `--session NAME` | Named session (default: "default") || `--browser MODE` | Browser mode (only if multiple modes installed) |-| `--profile ID` | Cloud profile ID for persistent cookies |+| `--profile ID` | Cloud profile ID for persistent cookies. Works with `open`, `session create`, etc. — does NOT work with `run` (use `--session-id` instead) || `--json` | Output as JSON |-| `--api-key KEY` | Override API key |--## Common Patterns--### Test a Local Dev Server with Cloud Browser--```bash-# Start dev server-npm run dev & # localhost:3000--# Tunnel it-browser-use tunnel 3000-# → url: https://abc.trycloudflare.com--# Browse with cloud browser-browser-use open https://abc.trycloudflare.com-browser-use state-browser-use screenshot-```--### Form Submission--```bash-browser-use open https://example.com/contact-browser-use state-# Shows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"-browser-use input 0 "John Doe"-browser-use input 1 "[email protected]"-browser-use input 2 "Hello, this is a test message."-browser-use click 3-browser-use state # Verify success-```--### Screenshot Loop for Visual Verification--```bash-browser-use open https://example.com-for i in 1 2 3 4 5; do- browser-use scroll down- browser-use screenshot "page_$i.png"-done-```## Tips-1. **Install with `--remote-only`** for sandboxed environments — no `--browser` flag needed+1. **Run `browser-use doctor`** to verify installation before starting2. **Always run `state` first** to see available elements and their indices3. **Sessions persist** across commands — the browser stays open until you close it-4. **Tunnels are independent** — they don't require or create a browser session, and persist across `browser-use close`+4. **Tunnels are independent** — they persist across `browser-use close`5. **Use `--json`** for programmatic parsing6. **`tunnel` is idempotent** — calling it again for the same port returns the existing URL-7. **Close when done** — `browser-use close` closes the browser; `browser-use tunnel stop --all` stops tunnels## Troubleshooting**"Browser mode 'chromium' not installed"?**-- You installed with `--remote-only` which doesn't include local modes-- This is expected behavior for sandboxed agents-- If you need local browser, reinstall with `--full`+- Expected for sandboxed agents — remote mode only supports cloud browsers+- Run `browser-use doctor` to verify configuration**Cloud browser won't start?**-- Verify `BROWSER_USE_API_KEY` is set-- Check your API key at https://browser-use.com+- Run `browser-use doctor` to check configuration**Tunnel not working?**- Verify cloudflared is installed: `which cloudflared`-- If missing, install manually (see Setup section) or re-run `install.sh --remote-only`- `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-- Page may have changed — re-run `state` to get fresh indices++**Session reuse fails after `task stop`**:+Create a new session instead:+```bash+browser-use session create --profile <profile-id> --keep-alive+browser-use run "new task" --session-id <new-session-id>+```++**Task stuck at "started"**: Check cost with `task status` — if not increasing, the task is stuck. View live URL with `session get`, then stop and start a new agent.++**Sessions persist after tasks complete**: Run `browser-use session stop --all` to clean up.## Cleanup-**Close the browser when done:**+**Always close resources when done:**```bash-browser-use close # Close browser session-browser-use tunnel stop --all # Stop all tunnels (if any)+browser-use close # Close browser session+browser-use session stop --all # Stop cloud sessions (if any)+browser-use tunnel stop --all # Stop tunnels (if any)```--Browser sessions and tunnels are managed separately, so close each as needed.