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

# 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

<Steps>
  <Step title="Install Browser Use">
    ```bash theme={null}
    uv pip install browser-use
    ```
  </Step>

  <Step title="Install Chromium">
    ```bash theme={null}
    browser-use install
    ```

    Installs Chromium browser with system dependencies (Linux only).
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    browser-use doctor
    ```

    Checks your installation and validates dependencies.
  </Step>
</Steps>

## Setup Commands

### install

Installs Chromium browser with system dependencies.

```bash theme={null}
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.

<CodeGroup>
  ```bash Interactive theme={null}
  browser-use init
  ```

  ```bash Specific Template theme={null}
  browser-use init --template basic
  ```

  ```bash Custom Path theme={null}
  browser-use init --output my_script.py
  ```

  ```bash Force Overwrite theme={null}
  browser-use init --force
  ```
</CodeGroup>

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

```bash theme={null}
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.

```bash theme={null}
browser-use doctor
```

Returns health check results for:

* Python version
* Browser installation
* API key configuration
* Network connectivity

## Navigation Commands

### open

Navigate to a URL.

```bash theme={null}
browser-use open https://example.com
```

Automatically starts the browser if not already running.

### back

Go back in browser history.

```bash theme={null}
browser-use back
```

### scroll

Scroll the page up or down.

<CodeGroup>
  ```bash Scroll Down theme={null}
  browser-use scroll down
  ```

  ```bash Scroll Up theme={null}
  browser-use scroll up
  ```

  ```bash Custom Amount theme={null}
  browser-use scroll down --amount 1000
  ```
</CodeGroup>

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

```bash theme={null}
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.

<CodeGroup>
  ```bash Save to File theme={null}
  browser-use screenshot output.png
  ```

  ```bash Base64 Output theme={null}
  browser-use screenshot
  ```

  ```bash Full Page theme={null}
  browser-use screenshot --full page.png
  ```
</CodeGroup>

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

```bash theme={null}
browser-use click 5
```

### type

Type text into the currently focused element.

```bash theme={null}
browser-use type "Hello World"
```

### input

Click an element by index, then type text into it.

```bash theme={null}
browser-use input 3 "john@example.com"
```

Equivalent to: `click 3` + `type "john@example.com"`

### keys

Send keyboard keys or key combinations.

<CodeGroup>
  ```bash Single Key theme={null}
  browser-use keys "Enter"
  ```

  ```bash Key Combination theme={null}
  browser-use keys "Control+a"
  ```

  ```bash Tab Navigation theme={null}
  browser-use keys "Tab Tab Enter"
  ```
</CodeGroup>

### select

Select a dropdown option.

```bash theme={null}
browser-use select 4 "option-value"
```

### hover

Hover over an element.

```bash theme={null}
browser-use hover 7
```

### dblclick

Double-click an element.

```bash theme={null}
browser-use dblclick 2
```

### rightclick

Right-click an element.

```bash theme={null}
browser-use rightclick 5
```

## Tab Management

### switch

Switch to a different tab by index.

```bash theme={null}
browser-use switch 1
```

### close-tab

Close a tab.

<CodeGroup>
  ```bash Close Current Tab theme={null}
  browser-use close-tab
  ```

  ```bash Close Specific Tab theme={null}
  browser-use close-tab 2
  ```
</CodeGroup>

## Cookie Management

### cookies get

Get all cookies or cookies for a specific URL.

<CodeGroup>
  ```bash All Cookies theme={null}
  browser-use cookies get
  ```

  ```bash Filter by URL theme={null}
  browser-use cookies get --url https://example.com
  ```
</CodeGroup>

### cookies set

Set a cookie with options.

```bash theme={null}
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.

<CodeGroup>
  ```bash Clear All theme={null}
  browser-use cookies clear
  ```

  ```bash Clear for URL theme={null}
  browser-use cookies clear --url https://example.com
  ```
</CodeGroup>

### cookies export

Export cookies to a JSON file.

```bash theme={null}
browser-use cookies export cookies.json
```

### cookies import

Import cookies from a JSON file.

```bash theme={null}
browser-use cookies import cookies.json
```

## Wait Commands

### wait selector

Wait for a CSS selector to appear or disappear.

<CodeGroup>
  ```bash Wait for Element theme={null}
  browser-use wait selector "button.submit"
  ```

  ```bash Wait for Hidden theme={null}
  browser-use wait selector ".loading" --state hidden
  ```

  ```bash Custom Timeout theme={null}
  browser-use wait selector "h1" --timeout 5000
  ```
</CodeGroup>

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

```bash theme={null}
browser-use wait text "Success"
```

## Information Retrieval

### get title

Get the page title.

```bash theme={null}
browser-use get title
```

### get html

Get page HTML.

<CodeGroup>
  ```bash Full Page theme={null}
  browser-use get html
  ```

  ```bash Specific Element theme={null}
  browser-use get html --selector "h1"
  ```
</CodeGroup>

### get text

Get text content of an element.

```bash theme={null}
browser-use get text 5
```

### get value

Get value of an input element.

```bash theme={null}
browser-use get value 3
```

### get attributes

Get all attributes of an element.

```bash theme={null}
browser-use get attributes 7
```

### get bbox

Get element bounding box (x, y, width, height).

```bash theme={null}
browser-use get bbox 4
```

## JavaScript & Data Extraction

### eval

Execute custom JavaScript code.

```bash theme={null}
browser-use eval "document.title"
```

### extract

Extract data using LLM (requires API key).

```bash theme={null}
browser-use extract "Extract all product names from this page"
```

## Python Execution

Execute Python code with persistent namespace.

<CodeGroup>
  ```bash Inline Code theme={null}
  browser-use python "x = 42"
  browser-use python "print(x)"  # Prints: 42
  ```

  ```bash From File theme={null}
  browser-use python --file script.py
  ```

  ```bash Show Variables theme={null}
  browser-use python --vars
  ```

  ```bash Reset Namespace theme={null}
  browser-use python --reset
  ```
</CodeGroup>

The `browser` object is available in the Python namespace for browser interactions.

## Agent Tasks

Run AI-powered browser automation tasks.

### Local Mode

```bash theme={null}
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)

```bash theme={null}
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.

```bash theme={null}
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.

<CodeGroup>
  ```bash Default View theme={null}
  browser-use task status task-123
  ```

  ```bash Compact theme={null}
  browser-use task status task-123 -c
  ```

  ```bash Verbose theme={null}
  browser-use task status task-123 -v
  ```

  ```bash Last N Steps theme={null}
  browser-use task status task-123 --last 5
  ```

  ```bash Specific Step theme={null}
  browser-use task status task-123 --step 3
  ```

  ```bash Reverse Order theme={null}
  browser-use task status task-123 --reverse
  ```
</CodeGroup>

### task stop

Stop a running task.

```bash theme={null}
browser-use task stop task-123
```

### task logs

Get task execution logs.

```bash theme={null}
browser-use task logs task-123
```

## Cloud Session Management

### session list

List cloud sessions.

```bash theme={null}
browser-use session list
```

**Options:**

* `--limit` - Maximum sessions (default: `10`)
* `--status` - Filter by status: `active`, `stopped`

### session get

Get session details including live URL.

```bash theme={null}
browser-use session get sess-456
```

### session stop

Stop cloud session(s).

<CodeGroup>
  ```bash Stop One theme={null}
  browser-use session stop sess-456
  ```

  ```bash Stop All theme={null}
  browser-use session stop --all
  ```
</CodeGroup>

### session create

Create a new cloud session.

```bash theme={null}
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.

<CodeGroup>
  ```bash Create Share theme={null}
  browser-use session share sess-456
  ```

  ```bash Delete Share theme={null}
  browser-use session share sess-456 --delete
  ```
</CodeGroup>

## Tunnels

Expose local dev servers via Cloudflare tunnels.

### tunnel start

```bash theme={null}
browser-use tunnel 3000
```

Returns a public URL like `https://abc.trycloudflare.com`

### tunnel list

List active tunnels.

```bash theme={null}
browser-use tunnel list
```

### tunnel stop

Stop tunnel(s).

<CodeGroup>
  ```bash Stop One theme={null}
  browser-use tunnel stop 3000
  ```

  ```bash Stop All theme={null}
  browser-use tunnel stop --all
  ```
</CodeGroup>

## Profile Management

### Local Profiles (`-b real`)

<CodeGroup>
  ```bash List Profiles theme={null}
  browser-use -b real profile list
  ```

  ```bash View Cookies theme={null}
  browser-use -b real profile cookies Default
  ```

  ```bash Sync to Cloud theme={null}
  browser-use -b real profile sync --from Default
  ```

  ```bash Sync Specific Domain theme={null}
  browser-use -b real profile sync --from Default --domain youtube.com
  ```
</CodeGroup>

### Cloud Profiles (`-b remote`)

<CodeGroup>
  ```bash List theme={null}
  browser-use -b remote profile list
  ```

  ```bash Get Details theme={null}
  browser-use -b remote profile get prof-123
  ```

  ```bash Create theme={null}
  browser-use -b remote profile create --name "My Profile"
  ```

  ```bash Update theme={null}
  browser-use -b remote profile update prof-123 --name "New Name"
  ```

  ```bash Delete theme={null}
  browser-use -b remote profile delete prof-123
  ```
</CodeGroup>

## Local Session Management

### sessions

List active local sessions.

```bash theme={null}
browser-use sessions
```

### close

Close browser session.

<CodeGroup>
  ```bash Close Current theme={null}
  browser-use close
  ```

  ```bash Close All theme={null}
  browser-use close --all
  ```
</CodeGroup>

### server commands

Manage the session server.

<CodeGroup>
  ```bash Check Status theme={null}
  browser-use server status
  ```

  ```bash Stop Server theme={null}
  browser-use server stop
  ```

  ```bash View Logs theme={null}
  browser-use server logs
  ```
</CodeGroup>

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

```bash theme={null}
browser-use open https://example.com
```

### Real Browser

Use your actual Chrome browser with existing logins.

```bash theme={null}
browser-use --browser real open https://gmail.com
```

### Remote (Cloud)

Cloud browser with anti-detection features.

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
browser-use close --all
browser-use server stop
```

### View server logs

```bash theme={null}
browser-use server logs
```

### Check installation

```bash theme={null}
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`