| name | browser-use |
| description | Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages. |
| allowed-tools | Bash(uvx 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.
Quick Start
uvx browser-use open https://example.com
uvx browser-use state
uvx browser-use click 5
uvx browser-use type "Hello World"
uvx browser-use screenshot
uvx browser-use close
Core Workflow
- Navigate:
uvx browser-use open <url> - Opens URL (starts browser if needed)
- Inspect:
uvx browser-use state - Returns clickable elements with indices
- Interact: Use indices from state to interact (
uvx browser-use click 5, uvx browser-use input 3 "text")
- Verify:
uvx browser-use state or uvx browser-use screenshot to confirm actions
- Repeat: Browser stays open between commands
Browser Modes
uvx browser-use --browser chromium open <url>
uvx browser-use --browser chromium --headed open <url>
uvx browser-use --browser real open <url>
uvx browser-use --browser remote open <url>
- 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
uvx browser-use open <url>
uvx browser-use back
uvx browser-use scroll down
uvx browser-use scroll up
Page State
uvx browser-use state
uvx browser-use screenshot
uvx browser-use screenshot path.png
uvx browser-use screenshot --full path.png
Interactions (use indices from uvx browser-use state)
uvx browser-use click <index>
uvx browser-use type "text"
uvx browser-use input <index> "text"
uvx browser-use keys "Enter"
uvx browser-use keys "Control+a"
uvx browser-use select <index> "option"
Tab Management
uvx browser-use switch <tab>
uvx browser-use close-tab
uvx browser-use close-tab <tab>
JavaScript & Data
uvx browser-use eval "document.title"
uvx browser-use extract "all product prices"
Python Execution (Persistent Session)
uvx browser-use python "x = 42"
uvx browser-use python "print(x)"
uvx browser-use python "print(browser.url)"
uvx browser-use python --vars
uvx browser-use python --reset
uvx browser-use python --file script.py
The Python session maintains state across commands. The browser object provides:
browser.url - Current page URL
browser.title - Page title
browser.goto(url) - Navigate
browser.click(index) - Click element
browser.type(text) - Type text
browser.screenshot(path) - Take screenshot
browser.scroll() - Scroll page
browser.html - Get page HTML
Agent Tasks (Requires API Key)
uvx browser-use run "Fill the contact form with test data"
uvx 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).
Session Management
uvx browser-use sessions
uvx browser-use close
uvx browser-use close --all
Server Control
uvx browser-use server status
uvx browser-use server stop
uvx browser-use server logs
Global Options
| Option | Description |
|---|
--session NAME | Use named session (default: "default") |
--browser MODE | Browser mode: chromium, real, remote |
--headed | Show browser window (chromium mode) |
--profile NAME | Chrome profile (real mode only) |
--json | Output as JSON |
--api-key KEY | Override API key |
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.
Examples
Form Submission
uvx browser-use open https://example.com/contact
uvx browser-use state
uvx browser-use input 0 "John Doe"
uvx browser-use input 1 "john@example.com"
uvx browser-use input 2 "Hello, this is a test message."
uvx browser-use click 3
uvx browser-use state
Multi-Session Workflows
uvx browser-use --session work open https://work.example.com
uvx browser-use --session personal open https://personal.example.com
uvx browser-use --session work state
uvx browser-use --session personal state
uvx browser-use close --all
Data Extraction with Python
uvx browser-use open https://example.com/products
uvx browser-use python "
products = []
for i in range(20):
browser.scroll('down')
browser.screenshot('products.png')
"
uvx browser-use python "print(f'Captured {len(products)} products')"
Using Real Browser (Logged-In Sessions)
uvx browser-use --browser real open https://gmail.com
uvx browser-use state
Tips
- Always run
uvx browser-use state first to see available elements and their indices
- Use
--headed for debugging to see what the browser is doing
- Sessions persist - the browser stays open between commands
- Use
--json for parsing output programmatically
- Python variables persist across
uvx browser-use python commands within a session
- Real browser mode preserves your login sessions and extensions
Troubleshooting
Browser won't start?
uvx browser-use server stop
uvx browser-use --headed open <url>
Element not found?
uvx browser-use state
uvx browser-use scroll down
uvx browser-use state
Session issues?
uvx browser-use sessions
uvx browser-use close --all
uvx browser-use open <url>
Cleanup
Always close the browser when done. Run this after completing browser automation:
uvx browser-use close