CLI Reference

Complete command reference for the browser-use CLI

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.

Interactive

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

Navigation Commands

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.

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

Save to File

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 "[e-mail]"

Equivalent to: click 3 + type "[e-mail]"

keys

Send keyboard keys or key combinations.

Single Key

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.

Close Current Tab

browser-use close-tab

Cookie Management

cookies get

Get all cookies or cookies for a specific URL.

All Cookies

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.

Clear All

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.

Wait for Element

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.

Full Page

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.

Inline Code

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.

Default View

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

Stop One

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.

Create Share

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

Stop One

browser-use tunnel stop 3000

Profile Management

Local Profiles (-b real)

List Profiles

browser-use -b real profile list

Cloud Profiles (-b remote)

List

browser-use -b remote profile list

Local Session Management

sessions

List active local sessions.

browser-use sessions

close

Close browser session.

Close Current

browser-use close

server commands

Manage the session server.

Check Status

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 "[e-mail]"
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