domains / agent-tooling / browser-automation / browser-use

browser-use

Skill card

combined

The two skills describe fundamentally different interfaces for the `browser-use` tool. The first (davidondrej) describes a Python-heredoc based CLI (`browser-use <<'PY'`) that uses a daemon, CDP directly, and specific helper functions like `new_tab()` and `page_info()`. It focuses on advanced CDP control, remote daemons, and specific local Chrome debugging workflows. The second (LeoYeAI) describes a command-line argument based CLI (`browser-use open <url>`, `browser-use click <index>`) that uses a state-based interaction model (getting indices from `state` and using them for clicks). These are mutually exclusive workflows; an agent following the first would fail if it tried to use the second's commands, and vice versa. Therefore, they must be combined to provide a complete picture of the available interfaces.

Repositories

Other copies

Combined skill

---
name: browser-use
description: "Direct browser control via CDP or CLI for web interaction: automation, scraping, testing, screenshots, and site/app work."
homepage: https://browser-use.com
---

# Browser Use

This skill supports two distinct interfaces for the `browser-use` tool: a **Python/CDP interface** for advanced control and a **CLI/State interface** for simple command-line automation. Choose the interface based on your task complexity and environment.

## Interface 1: Python/CDP (Advanced)

Use this interface when you need direct CDP access, complex session management, or when the environment supports Python heredocs.

### Setup & Diagnostics
- Install via `uv` if not present.
- Run `browser-use --doctor` for connection issues.
- For local Chrome remote debugging issues, use `browser-use mac-approve` on macOS if prompted.

### Usage Pattern
Invoke using Python heredocs. Helpers are pre-imported.

```bash
browser-use <<'PY'
# First navigation for a task
new_tab("https://example.com")
print(page_info())
PY
```

### Key Rules
- **Tab Management**: Use `new_tab(url)` for the first navigation. Reuse tabs with `switch_tab()` and inspect with `list_tabs()`. Do not create duplicate tabs for the same URL.
- **Background vs Foreground**: The daemon attaches to a background tab by default. Screenshots and CDP input work in the background. Only call `activate_tab(target)` if the user explicitly asks or if a page pauses rendering while hidden.
- **Scrolling**: If `scroll(...)` times out on a background tab, call `activate_tab(current_tab())`, retry the scroll once, then re-read position.
- **Remote Daemons**: For parallel tasks or isolated environments, start a remote daemon:
  ```bash
  browser-use <<'PY'
  start_remote_daemon("unique_name")
  PY
  
  BU_NAME=unique_name browser-use <<'PY'
  new_tab("https://example.com")
  PY
  ```
  Remember to stop remote daemons when done to avoid billing: `stop_remote_daemon("unique_name")`.

## Interface 2: CLI/State (Simple)

Use this interface for straightforward command-line automation where you interact with elements by index.

### Setup & Diagnostics
- Run `browser-use doctor` to verify installation.

### Core Workflow
1. **Navigate**: `browser-use open <url>`
2. **Inspect**: `browser-use state` (Returns clickable elements with indices)
3. **Interact**: Use indices from state (e.g., `browser-use click 5`, `browser-use input 3 "text"`)
4. **Verify**: `browser-use state` or `browser-use screenshot`

### Browser Modes
- `--browser chromium`: Default, headless, isolated.
- `--browser real`: Uses local Chrome. Add `--profile "Default"` to use existing logins.
- `--browser remote`: Cloud-hosted browser.

### Essential Commands
```bash
# Navigation
browser-use open <url>
browser-use back
browser-use scroll down --amount 1000

# State & Data
browser-use state
browser-use screenshot path.png
browser-use eval "document.title"
browser-use get text <index>

# Interaction
browser-use click <index>
browser-use input <index> "text"
browser-use keys "Enter"

# Session
browser-use sessions
browser-use close
```

## When Not to Use
- If a plain HTTP request (`curl` or fetch) can retrieve the data, do not use the browser.
- Use the browser only for interaction (click, type), JS rendering, logged-in sessions, or bot-protected pages.