Browser-Use Automation

# Browser-Use Automation Skill

You are an expert in browser automation using browser-use, a powerful CLI tool designed for persistent, multi-session browser automation. When the user asks you to automate complex browser workflows, manage sessions, or perform long-running automation tasks, follow these detailed instructions.

## Core Principles

1. **Persistent sessions** -- Maintain browser state across multiple automation runs.
2. **Multi-session support** -- Run multiple isolated browser sessions in parallel.
3. **Flexible browser modes** -- Support for Chromium (headless), Real (headed), and Remote browser instances.
4. **Cookie management** -- Export, import, and manage cookies for authentication persistence.
5. **JavaScript execution** -- Execute custom JavaScript in page context for advanced automation.

## Installation

```bash
# Install via npm
npm install -g browser-use

# Or use with npx
npx browser-use --version

# Install with Python
pip install browser-use

# Verify installation
browser-use --help
```

## Browser Modes

### Chromium Mode (Default Headless)

```bash
# Launch Chromium in headless mode
browser-use start --mode chromium --headless

# With custom user data directory
browser-use start --mode chromium --user-data-dir ./browser-data

# With custom viewport
browser-use start --mode chromium --viewport 1920x1080
```

### Real Browser Mode (Headed)

```bash
# Launch visible Chrome browser
browser-use start --mode real --browser chrome

# Launch Firefox
browser-use start --mode real --browser firefox

# Launch with specific profile
browser-use start --mode real --browser chrome --profile "Profile 1"
```

### Remote Browser Mode

```bash
# Connect to remote Chrome DevTools Protocol
browser-use start --mode remote --cdp-url ws://localhost:9222

# Connect to Selenium Grid
browser-use start --mode remote --selenium-url http://localhost:4444/wd/hub
```

## Session Management

### Creating and Managing Sessions

```bash
# Create named session
browser-use session create --name "user-session-1" --persist

# List all sessions
browser-use session list

# Attach to existing session
browser-use session attach --name "user-session-1"

# Delete session
browser-use session delete --name "user-session-1"

# Export session state
browser-use session export --name "user-session-1" --output ./session-state.json

# Import session state
browser-use session import --input ./session-state.json --name "restored-session"
```

**Session List Output:**
```json
{
  "sessions": [
    {
      "name": "user-session-1",
      "id": "abc123",
      "created": "2024-02-12T10:00:00Z",
      "lastActive": "2024-02-12T10:30:00Z",
      "persistent": true,
      "tabs": 3
    },
    {
      "name": "test-session-2",
      "id": "def456",
      "created": "2024-02-12T11:00:00Z",
      "lastActive": "2024-02-12T11:15:00Z",
      "persistent": false,
      "tabs": 1
    }
  ]
}
```

### Multi-Session Parallel Execution

```bash
# Run multiple sessions in parallel
browser-use parallel --sessions "session-1,session-2,session-3" \
  --command "navigate --url https://example.com"

# Run different commands per session
browser-use parallel \
  --session session-1 --command "navigate --url https://site1.com" \
  --session session-2 --command "navigate --url https://site2.com" \
  --session session-3 --command "navigate --url https://site3.com"
```

## Cookie Management

### Export and Import Cookies

```bash
# Export cookies from session
browser-use cookies export --session "user-session-1" --output cookies.json

# Export specific domain cookies
browser-use cookies export --session "user-session-1" --domain "example.com" --output example-cookies.json

# Import cookies into session
browser-use cookies import --session "user-session-1" --input cookies.json

# Import cookies for specific domain
browser-use cookies import --session "user-session-1" --input auth-cookies.json --domain "app.example.com"

# Clear all cookies
browser-use cookies clear --session "user-session-1"

# Clear cookies for specific domain
browser-use cookies clear --session "user-session-1" --domain "example.com"
```

**Cookie Export Format:**
```json
{
  "cookies": [
    {
      "name": "session_token",
      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "domain": ".example.com",
      "path": "/",
      "expires": 1707753600,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    },
    {
      "name": "user_preferences",
      "value": "theme=dark&lang=en",
      "domain": "app.example.com",
      "path": "/",
      "expires": 1739289600,
      "httpOnly": false,
      "secure": true,
      "sameSite": "Strict"
    }
  ]
}
```

### Cookie-Based Authentication Persistence

```bash
#!/bin/bash
# auth-persist.sh - Login once, reuse session

SESSION_NAME="authenticated-user"

# Check if session exists
if browser-use session list | grep -q "$SESSION_NAME"; then
  echo "Using existing authenticated session"
  browser-use session attach --name "$SESSION_NAME"
else
  echo "Creating new authenticated session"
  browser-use session create --name "$SESSION_NAME" --persist

  # Perform login
  browser-use navigate --url "https://app.example.com/login"
  browser-use type --selector "#email" --text "user@example.com"
  browser-use type --selector "#password" --text "$PASSWORD"
  browser-use click --selector "button[type='submit']"
  browser-use wait --selector ".dashboard" --timeout 10000

  # Export cookies for backup
  browser-use cookies export --session "$SESSION_NAME" --output auth-cookies.json
  echo "Session authenticated and cookies saved"
fi

# Now use authenticated session
browser-use navigate --url "https://app.example.com/dashboard"
```

## JavaScript Execution

### Execute JavaScript in Page Context

```bash
# Execute simple JavaScript
browser-use execute --script "return document.title"

# Execute with arguments
browser-use execute --script "return arguments[0] + arguments[1]" --args "[5, 10]"

# Execute and save re