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. ## Installation ```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 **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:** ```bash browser-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 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 ## Browser Modes ```bash browser-use --browser chromium open <url> # Default: headless Chromium browser-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) ``` - **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) ## Commands ### Navigation ```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) ``` ### 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 ``` ### Interactions (use indices from `browser-use state`) ```bash browser-use click <index> # Click element 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 ``` ### 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 ``` ### JavaScript & Data ```bash browser-use eval "document.title" # Execute JavaScript, return result browser-use extract "all product prices" # Extract data using LLM (requires API key) ``` ### 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 ``` ### 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) ```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` - 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 ### 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 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 When 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 model browser-use -b remote run "task" --llm gpt-4o browser-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 # 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 # Execution modes browser-use -b remote run "task" --no-wait # Async, returns task_id immediately browser-use -b remote run "task" --stream # Stream status updates browser-use -b remote run "task" --flash # Fast execution mode # Advanced options browser-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) # Use cloud profile (preserves cookies across sessions) browser-use -b remote run "task" --profile <cloud-profile-id> # Task configuration browser-use -b remote run "task" --start-url https://example.com # Start from specific URL browser-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) # Structured output and evaluation browser-use -b remote run "task" --structured-output '{"type":"object"}' # JSON schema for output browser-use -b remote run "task" --judge # Enable judge mode browser-use -b remote run "task" --judge-ground-truth "expected answer" # Expected answer for judge ``` ### Task Management (Remote Mode) Manage cloud tasks when using remote mode: ```bash browser-use task list # List recent tasks browser-use task list --limit 20 # Show more tasks browser-use task list --status running # Filter by status browser-use task list --session <id> # Filter by session ID browser-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 stop <task-id> # Stop a running task browser-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: ```bash browser-use session list # List cloud sessions browser-use session list --limit 20 # Show more sessions browser-use session list --status active # Filter by status browser-use session list --json # JSON output browser-use session get <session-id> # Get session details browser-use session get <session-id> --json browser-use session stop <session-id> # Stop a session browser-use session stop --all # Stop all active sessions # Create a new cloud session manually browser-use session create # Create with defaults browser-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 ``` ## 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:** ```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 ``` **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