Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/browser-use/browser-use/llms.txt

Use this file to discover all available pages before exploring further.

The Browser Use CLI provides fast, persistent browser automation from the command line. The CLI uses a session server architecture where the browser stays open between commands for instant response times (~50ms).

​
Installation

1

Install Browser Use

uv pip install browser-use
2

Install Chromium

browser-use install
Installs Chromium browser with system dependencies (Linux only).
3

Verify Installation

browser-use doctor
Checks your installation and validates dependencies.

​
Setup Commands

​
install

Installs Chromium browser with system dependencies. 
browser-use install
  • On Linux: Installs with --with-deps flag for system dependencies
  • On macOS/Windows: Installs Chromium only (no system dependencies needed)

​
init

Generates template files to get started quickly. 
browser-use init
Options:
  • --template, -t - Template name (interactive if not specified)
  • --output, -o - Output file path
  • --force, -f - Overwrite existing files
  • --list, -l - List available templates

​
setup

Configures browser-use for first-time use. 
browser-use setup
Options:
  • --mode - Setup mode: local, remote, or full (default: local)
  • --api-key - Browser-Use API key
  • --yes, -y - Skip interactive prompts

​
doctor

Validates installation and checks dependencies. 
browser-use doctor
Returns health check results for:
  • Python version
  • Browser installation
  • API key configuration
  • Network connectivity

​
open

Navigate to a URL. 
browser-use open https://example.com
Automatically starts the browser if not already running.

​
back

Go back in browser history. 
browser-use back

​
scroll

Scroll the page up or down. 
browser-use scroll down
Options:
  • direction - up or down (default: down)
  • --amount - Scroll amount in pixels (default: 500)

​
Inspection Commands

​
state

Get browser state including URL, title, and clickable elements. 
browser-use state
Returns:
  • Current URL
  • Page title
  • List of interactive elements with indices
  • Element types (button, input, link, etc.)

​
screenshot

Take a screenshot of the current page. 
browser-use screenshot output.png
Options:
  • path - Save path (outputs base64 if not provided)
  • --full - Capture full page instead of viewport

​
Interaction Commands

​
click

Click an element by its index from the state command. 
browser-use click 5

​
type

Type text into the currently focused element. 
browser-use type "Hello World"

​
input

Click an element by index, then type text into it. 
browser-use input 3 "john@example.com"
Equivalent to: click 3 + type "john@example.com"

​
keys

Send keyboard keys or key combinations. 
browser-use keys "Enter"

​
select

Select a dropdown option. 
browser-use select 4 "option-value"

​
hover

Hover over an element. 
browser-use hover 7

​
dblclick

Double-click an element. 
browser-use dblclick 2

​
rightclick

Right-click an element. 
browser-use rightclick 5

​
Tab Management

​
switch

Switch to a different tab by index. 
browser-use switch 1

​
close-tab

Close a tab. 
browser-use close-tab

​
cookies get

Get all cookies or cookies for a specific URL. 
browser-use cookies get

​
cookies set

Set a cookie with options. 
browser-use cookies set name value --domain .example.com --secure --same-site Strict
Options:
  • --domain - Cookie domain
  • --path - Cookie path (default: /)
  • --secure - Mark as secure cookie
  • --http-only - Mark as HTTP-only
  • --same-site - SameSite attribute: Strict, Lax, or None
  • --expires - Expiration timestamp

​
cookies clear

Clear cookies. 
browser-use cookies clear

​
cookies export

Export cookies to a JSON file. 
browser-use cookies export cookies.json

​
cookies import

Import cookies from a JSON file. 
browser-use cookies import cookies.json

​
Wait Commands

​
wait selector

Wait for a CSS selector to appear or disappear. 
browser-use wait selector "button.submit"
Options:
  • --timeout - Timeout in milliseconds (default: 30000)
  • --state - Element state: attached, detached, visible, or hidden (default: visible)

​
wait text

Wait for text to appear on the page. 
browser-use wait text "Success"

​
Information Retrieval

​
get title

Get the page title. 
browser-use get title

​
get html

Get page HTML. 
browser-use get html

​
get text

Get text content of an element. 
browser-use get text 5

​
get value

Get value of an input element. 
browser-use get value 3

​
get attributes

Get all attributes of an element. 
browser-use get attributes 7

​
get bbox

Get element bounding box (x, y, width, height). 
browser-use get bbox 4

​
JavaScript & Data Extraction

​
eval

Execute custom JavaScript code. 
browser-use eval "document.title"

​
extract

Extract data using LLM (requires API key). 
browser-use extract "Extract all product names from this page"

​
Python Execution

Execute Python code with persistent namespace. 
browser-use python "x = 42"
browser-use python "print(x)"  # Prints: 42
The browser object is available in the Python namespace for browser interactions.

​
Agent Tasks

Run AI-powered browser automation tasks.

​
Local Mode

browser-use run "Fill the contact form with test data"
Options:
  • --max-steps - Maximum steps
  • --llm - LLM model (e.g., gpt-4o, claude-sonnet-4-20250514)
Requires: OPENAI_API_KEY, ANTHROPIC_API_KEY, or other LLM provider API key

​
Remote Mode (Cloud)

browser-use -b remote run "Search for AI news"
Cloud Options:
  • --session-id - Reuse existing cloud session
  • --proxy-country - Proxy country code (e.g., us, uk, gb)
  • --stream - Stream output in real-time
  • --wait - Wait for completion (default: async)
  • --flash - Enable fast mode
  • --keep-alive - Keep session alive after task
  • --thinking - Enable extended reasoning
  • --vision - Enable vision (default)
  • --no-vision - Disable vision
  • --profile - Use cloud profile ID
  • --start-url - Start from specific URL
  • --allowed-domain - Restrict navigation (repeatable)
  • --metadata - Task metadata as KEY=VALUE (repeatable)
  • --secret - Task secrets as KEY=VALUE (repeatable)
  • --skill-id - Enable skill IDs (repeatable)
  • --structured-output - JSON schema for structured output
  • --judge - Enable judge mode
  • --judge-ground-truth - Expected answer for evaluation
Requires: BROWSER_USE_API_KEY

​
Task Management (Remote)

​
task list

List recent cloud tasks. 
browser-use task list
Options:
  • --limit - Maximum tasks to list (default: 10)
  • --status - Filter by status: running, finished, stopped, failed
  • --session - Filter by session ID

​
task status

Get task status and details. 
browser-use task status task-123

​
task stop

Stop a running task. 
browser-use task stop task-123

​
task logs

Get task execution logs. 
browser-use task logs task-123

​
Cloud Session Management

​
session list

List cloud sessions. 
browser-use session list
Options:
  • --limit - Maximum sessions (default: 10)
  • --status - Filter by status: active, stopped

​
session get

Get session details including live URL. 
browser-use session get sess-456

​
session stop

Stop cloud session(s). 
browser-use session stop sess-456

​
session create

Create a new cloud session. 
browser-use session create --profile prof-123 --proxy-country us
Options:
  • --profile - Cloud profile ID
  • --proxy-country - Proxy country code
  • --start-url - Initial URL
  • --screen-size - Screen size (e.g., 1920x1080)
  • --keep-alive - Keep session alive
  • --persist-memory - Persist memory between tasks

​
session share

Create or delete public share URL. 
browser-use session share sess-456

​
Tunnels

Expose local dev servers via Cloudflare tunnels.

​
tunnel start

browser-use tunnel 3000
Returns a public URL like https://abc.trycloudflare.com

​
tunnel list

List active tunnels. 
browser-use tunnel list

​
tunnel stop

Stop tunnel(s). 
browser-use tunnel stop 3000

​
Profile Management

​
Local Profiles (-b real)

browser-use -b real profile list

​
Cloud Profiles (-b remote)

browser-use -b remote profile list

​
Local Session Management

​
sessions

List active local sessions. 
browser-use sessions

​
close

Close browser session. 
browser-use close

​
server commands

Manage the session server. 
browser-use server status

​
Global Options

These options work with any command:
  • --session NAME - Use named session (default: default)
  • --browser MODE - Browser mode: chromium, real, or remote
  • --headed - Show browser window (default: headless)
  • --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

​
Browser Modes

​
Chromium (Default)

Headless Chromium browser. 
browser-use open https://example.com

​
Real Browser

Use your actual Chrome browser with existing logins. 
browser-use --browser real open https://gmail.com

​
Remote (Cloud)

Cloud browser with anti-detection features. 
browser-use --browser remote open https://example.com
Requires: BROWSER_USE_API_KEY

​
Persistent Sessions

The CLI uses a session server architecture where the browser stays open between commands: 
# Start session (default name: "default")
browser-use open https://example.com

# Reuses same browser
browser-use state
browser-use click 5

# Close when done
browser-use close

​
Multiple Sessions

Run multiple browsers in parallel: 
browser-use --session work open https://work.example.com
browser-use --session personal open https://personal.example.com

browser-use --session work state
browser-use --session personal state

browser-use close --all

​
Examples

​
Form Filling

browser-use open https://example.com/contact
browser-use state
# Shows: [0] input "Name", [1] input "Email", [2] button "Submit"
browser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use click 2

​
Data Extraction

browser-use open https://news.ycombinator.com
browser-use eval "Array.from(document.querySelectorAll('.titleline a')).slice(0,5).map(a => a.textContent)"

​
Cloud Agent with Session Reuse

# Start task, keep session alive
browser-use -b remote run "Log into example.com" --keep-alive --wait
# → task_id: task-123, session_id: sess-456

# Check status
browser-use task status task-123

# Run another task in same session (preserves login)
browser-use -b remote run "Go to settings" --session-id sess-456

​
Troubleshooting

​
Session server won’t start

browser-use close --all
browser-use server stop

​
View server logs

browser-use server logs

​
Check installation

browser-use doctor

​
How It Works

The CLI uses a background session server:
  1. First command starts a server (browser stays open)
  2. Commands communicate via Unix socket (TCP on Windows)
  3. ~50ms latency instead of waiting for browser startup
  4. Server auto-starts when needed, stops with browser-use server stop