Back to Browser Use

Browser-Use CLI

browser_use/skill_cli/README.md

0.12.612.9 KB
Original Source

Browser-Use CLI

Fast, persistent browser automation from the command line.

Installation

Prerequisites

PlatformRequirements
macOSPython 3.11+ (installer will use Homebrew if needed)
LinuxPython 3.11+ (installer will use apt if needed)
WindowsGit for Windows, Python 3.11+

macOS / Linux:

bash
curl -fsSL https://browser-use.com/cli/install.sh | bash

Windows (run in PowerShell):

powershell
& "C:\Program Files\Git\bin\bash.exe" -c 'curl -fsSL https://browser-use.com/cli/install.sh | bash'

Post-Install

bash
browser-use doctor   # Validate installation
browser-use setup    # Run setup wizard (optional)

Generate Templates

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

From Source

bash
uv pip install -e .

Manual Installation

If you prefer not to use the one-line installer:

bash
# 1. Install the package
uv pip install browser-use

# 2. Install Chromium
browser-use install

# 3. Validate
browser-use doctor

Quick Start

bash
# Open a webpage (starts browser automatically)
browser-use open https://example.com

# See clickable elements with their indices
browser-use state

# Click an element by index
browser-use click 5

# Type text into focused element
browser-use type "Hello World"

# Fill a specific input field (click + type)
browser-use input 3 "[email protected]"

# Take a screenshot
browser-use screenshot output.png

# Close the browser
browser-use close

Browser Modes

bash
# Default: headless Chromium
browser-use open https://example.com

# Visible browser window
browser-use --headed open https://example.com

# Use your real Chrome with Default profile (with existing logins/cookies)
browser-use --profile "Default" open https://gmail.com

# Use a specific Chrome profile
browser-use --profile "Profile 1" open https://gmail.com

# Auto-discover and connect to running Chrome
browser-use --connect open https://example.com

# Connect to an existing browser via CDP URL
browser-use --cdp-url http://localhost:9222 open https://example.com

# WebSocket CDP URL also works
browser-use --cdp-url ws://localhost:9222/devtools/browser/... state

All Commands

CommandDescription
open <url>Navigate to URL
backGo back in history
scroll downScroll down
scroll upScroll up
scroll down --amount 1000Scroll by pixels

Inspection

CommandDescription
stateGet URL, title, and clickable elements
screenshot [path]Take screenshot (base64 if no path)
screenshot --full path.pngFull page screenshot

Interaction

CommandDescription
click <index>Click element by index
click <x> <y>Click at pixel coordinates
type "text"Type into focused element
input <index> "text"Click element, then type
keys "Enter"Send keyboard keys
keys "Control+a"Send key combination
select <index> "value"Select dropdown option
upload <index> <path>Upload file to file input element
hover <index>Hover over element
dblclick <index>Double-click element
rightclick <index>Right-click element

Tabs

CommandDescription
switch <tab>Switch to tab by index
close-tabClose current tab
close-tab <tab>Close specific tab

Cookies

CommandDescription
cookies getGet all cookies
cookies get --url <url>Get cookies for URL
cookies set <name> <value>Set a cookie
cookies set name val --domain .example.com --secureSet with options
cookies set name val --same-site StrictSameSite: Strict, Lax, None
cookies set name val --expires 1735689600Set expiration timestamp
cookies clearClear all cookies
cookies clear --url <url>Clear cookies for URL
cookies export <file>Export to JSON file
cookies import <file>Import from JSON file

Wait

CommandDescription
wait selector "css"Wait for element to be visible
wait selector ".loading" --state hiddenWait for element to disappear
wait text "Success"Wait for text to appear
wait selector "h1" --timeout 5000Custom timeout (ms)

Get (Information Retrieval)

CommandDescription
get titleGet page title
get htmlGet full page HTML
get html --selector "h1"Get HTML of element
get text <index>Get text content of element
get value <index>Get value of input/textarea
get attributes <index>Get all attributes of element
get bbox <index>Get bounding box (x, y, width, height)

JavaScript & Data

CommandDescription
eval "js code"Execute JavaScript
extract "query"Extract data with LLM (not yet implemented)

Python (Persistent Session)

bash
browser-use python "x = 42"           # Set variable
browser-use python "print(x)"         # Access variable (prints: 42)
browser-use python "print(browser.url)"  # Access browser
browser-use python --vars             # Show defined variables
browser-use python --reset            # Clear namespace
browser-use python --file script.py   # Run Python file

Cloud API

Generic REST passthrough to the Browser-Use Cloud API, plus cloud browser provisioning.

CommandDescription
cloud connectProvision cloud browser and connect
cloud connect --timeout 120Cloud browser with custom timeout
cloud connect --proxy-country USCloud browser with proxy
cloud connect --profile-id <id>Cloud browser with profile
cloud login <api-key>Save API key
cloud logoutRemove API key
cloud v2 GET <path>GET request to API v2
cloud v2 POST <path> '<json>'POST request to API v2
cloud v3 POST <path> '<json>'POST request to API v3
cloud v2 poll <task-id>Poll task until done
cloud v2 --helpShow API v2 endpoints (from OpenAPI spec)
cloud v3 --helpShow API v3 endpoints
bash
# Save API key (or set BROWSER_USE_API_KEY env var)
browser-use cloud login sk-abc123...

# Provision a cloud browser and connect
browser-use cloud connect
browser-use state                    # works normally
browser-use close                    # disconnects AND stops cloud browser

# List browsers
browser-use cloud v2 GET /browsers

# Create a task
browser-use cloud v2 POST /tasks '{"task":"Search for AI news","url":"https://google.com"}'

# Poll until done
browser-use cloud v2 poll <task-id>

# Remove API key
browser-use cloud logout

API key stored in ~/.browser-use/config.json with 0600 permissions.

Tunnels

Expose local dev servers to cloud browsers via Cloudflare tunnels.

CommandDescription
tunnel <port>Start tunnel, get public URL
tunnel listList active tunnels
tunnel stop <port>Stop tunnel for port
tunnel stop --allStop all tunnels
bash
# Example: Test local dev server with cloud browser
npm run dev &                              # localhost:3000
browser-use tunnel 3000                    # → https://abc.trycloudflare.com
browser-use cloud connect                  # Provision cloud browser
browser-use open https://abc.trycloudflare.com

Profile Management

The profile subcommand delegates to the profile-use Go binary, which syncs local browser cookies to Browser-Use cloud.

The binary is managed at ~/.browser-use/bin/profile-use and auto-downloaded on first use.

CommandDescription
profileInteractive sync wizard
profile listList detected browsers and profiles
profile sync --allSync all profiles to cloud
profile sync --browser "Google Chrome" --profile "Default"Sync specific profile
profile auth --apikey <key>Set API key (shared with cloud login)
profile inspect --browser "Google Chrome" --profile "Default"Inspect cookies locally
profile updateDownload/update the profile-use binary

Session Management

CommandDescription
sessionsList active browser sessions
closeClose current session's browser and daemon
close --allClose all sessions
--session NAMETarget a named session (default: "default")
bash
# Default behavior unchanged
browser-use open https://example.com           # uses session 'default'
browser-use state                              # talks to 'default' daemon

# Named sessions
browser-use --session work open https://example.com
browser-use --session work state
browser-use --session cloud cloud connect

# List active sessions
browser-use sessions

# Close specific session
browser-use --session work close

# Close all sessions
browser-use close --all

# Env var fallback
BROWSER_USE_SESSION=work browser-use state

Global Options

OptionDescription
--headedShow browser window
--profile [NAME]Use real Chrome (bare --profile uses "Default")
--connectAuto-discover and connect to running Chrome via CDP
--cdp-url <url>Connect to existing browser via CDP URL (http:// or ws://)
--session NAMETarget a named session (default: "default", env: BROWSER_USE_SESSION)
--jsonOutput as JSON
--mcpRun as MCP server via stdin/stdout

Examples

Fill a Form

bash
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 "[email protected]"
browser-use click 2

Extract Data with JavaScript

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

Python Automation

bash
browser-use open https://example.com
browser-use python "
for i in range(5):
    browser.scroll('down')
    browser.wait(0.5)
browser.screenshot('scrolled.png')
"

Claude Code Skill

For Claude Code, a skill provides richer context for browser automation:

bash
mkdir -p ~/.claude/skills/browser-use
curl -o ~/.claude/skills/browser-use/SKILL.md \
  https://raw.githubusercontent.com/browser-use/browser-use/main/skills/browser-use/SKILL.md

How It Works

The CLI uses a multi-session daemon architecture:

  1. First command starts a background daemon for that session (browser stays open)
  2. Subsequent commands communicate via Unix socket (or TCP on Windows)
  3. Browser persists across commands for fast interaction
  4. Each --session gets its own daemon, socket, and PID file in ~/.browser-use/
  5. Daemon auto-starts when needed, auto-exits when browser dies, or stops with browser-use close

This gives you ~50ms command latency instead of waiting for browser startup each time.

File Layout

All CLI-managed files live under ~/.browser-use/ (override with BROWSER_USE_HOME):

~/.browser-use/
├── config.json          # API key, settings (shared with profile-use)
├── bin/
│   └── profile-use      # Managed Go binary (auto-downloaded)
├── tunnels/
│   ├── {port}.json      # Tunnel metadata
│   └── {port}.log       # Tunnel logs
├── default.sock         # Daemon socket (ephemeral)
├── default.pid          # Daemon PID (ephemeral)
└── cli.log              # Daemon log
<details> <summary>Windows Troubleshooting</summary>

ARM64 Windows (Surface Pro X, Snapdragon laptops)

Install x64 Python (runs via emulation):

powershell
winget install Python.Python.3.11 --architecture x64

Multiple Python versions

Set the version explicitly:

powershell
$env:PY_PYTHON=3.11

PATH not working after install

Restart your terminal. If still not working:

powershell
# Check PATH
echo $env:PATH

# Or run via Git Bash
& "C:\Program Files\Git\bin\bash.exe" -c 'browser-use --help'

"Failed to start daemon" error

Kill zombie processes:

powershell
# Find browser-use Python processes
tasklist | findstr python

# Kill by PID
taskkill /PID <pid> /F

# Or kill all Python
taskkill /IM python.exe /F

Stale virtual environment

Delete and reinstall:

powershell
taskkill /IM python.exe /F
Remove-Item -Recurse -Force "$env:USERPROFILE\.browser-use-env"
# Then run installer again
</details>