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

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

Quick Start

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

• Navigate: browser-use open <url>

• Opens URL (starts browser if needed)

• Inspect: browser-use state

• Returns clickable elements with indices

• Interact: Use indices from state to interact (browser-use click 5 , browser-use input 3 "text" )

• Verify: browser-use state or browser-use screenshot to confirm actions

• Repeat: Browser stays open between commands

Browser Modes

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

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

Page State

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 )

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

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

browser-use eval "document.title" # Execute JavaScript, return result browser-use extract "all product prices" # Extract data using LLM (requires API key)

Cookies

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 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

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

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

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)

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.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)

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).

Session Management

browser-use sessions # List active sessions browser-use close # Close current session browser-use close --all # Close all sessions

Profile Management

browser-use profile list-local # List local Chrome profiles

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-local to show available profiles:

browser-use profile list-local

Output: Default: Person 1 (user@gmail.com)

Profile 1: Work (work@company.com)

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

Headless mode (no visible window) - useful for cookie export

browser-use --browser real --profile "Default" cookies export /tmp/cookies.json

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

Cloud profiles store browser state (cookies) in Browser-Use Cloud, persisting across sessions. Requires BROWSER_USE_API_KEY .

browser-use profile list # List cloud profiles browser-use profile get <id> # Get profile details browser-use profile update <id> --name "New" # Rename profile browser-use profile delete <id> # Delete profile

Use a cloud profile with --browser remote --profile <id> :

browser-use --browser remote --profile abc-123 open https://example.com

Syncing Cookies to Cloud

⚠️ IMPORTANT: Before syncing cookies from a local browser to the cloud, the agent MUST:

• Ask the user which local Chrome profile to use (browser-use profile list-local )

• Ask which domain(s) to sync - do NOT default to syncing the full profile

• 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

List local Chrome profiles

browser-use profile list-local

→ Default: Person 1 (user@gmail.com)

→ Profile 1: Work (work@company.com)

See what cookies are in a profile

browser-use 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)

browser-use profile sync --from "Default" --domain youtube.com

Creates new cloud profile: "Chrome - Default (youtube.com)"

Only syncs youtube.com cookies

This is the recommended approach - sync only the cookies you need.

2. Full profile sync (use with caution)

browser-use profile sync --from "Default"

Syncs ALL cookies from the profile

⚠️ 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.

3. Fine-grained control (advanced)

Export cookies to file

browser-use --browser real --profile "Default" cookies export /tmp/cookies.json

Manually edit the JSON to keep only specific cookies

Import to cloud profile

browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

For users who need individual cookie-level control.

Step 3: Use the synced profile

browser-use --browser remote --profile <id> open https://youtube.com

Adding cookies to existing profiles:

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

Managing profiles:

browser-use profile update <id> --name "New Name" # Rename browser-use profile delete <id> # Delete

Server Control

browser-use server status # Check if server is running browser-use server stop # Stop server browser-use server logs # View server logs

Setup

browser-use install # Install Chromium and system dependencies

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.

API Key Configuration

Some features (run , extract , --browser remote ) require an API key. The CLI checks these locations in order:

• --api-key command line flag

• BROWSER_USE_API_KEY environment variable

• ~/.config/browser-use/config.json file

To configure permanently:

mkdir -p ~/.config/browser-use echo '{"api_key": "your-key-here"}' > ~/.config/browser-use/config.json

Examples

Form Submission

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 "john@example.com" browser-use input 2 "Hello, this is a test message." browser-use click 3 browser-use state # Verify success

Multi-Session Workflows

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

Data Extraction with Python

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')"

Using Real Browser (Logged-In Sessions)

browser-use --browser real open https://gmail.com

Uses your actual Chrome with existing login sessions

browser-use state # Already logged in!

Tips

• Always run 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 browser-use python commands within a session

• Real browser mode preserves your login sessions and extensions

• CLI aliases: bu , browser , and browseruse all work identically to browser-use

Troubleshooting

Browser won't start?

browser-use install # Install/reinstall Chromium browser-use server stop # Stop any stuck server browser-use --headed open <url> # Try with visible window

Element not found?

browser-use state # Check current elements browser-use scroll down # Element might be below fold browser-use state # Check again

Session issues?

browser-use sessions # Check active sessions browser-use close --all # Clean slate browser-use open <url> # Fresh start

Cleanup

Always close the browser when done. Run this after completing browser automation:

browser-use close