browser-use

Files (4)

• LICENSE
• SKILL.md
• cdp-python.md · references/
• multi-session.md · references/

SKILL.md (first lines)

# Browser Automation with browser-use CLI

`browser-use` keeps a managed browser open across commands

## Prerequisites

```bash
browser-use doctor    # Verify installation
```

For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

## Core Workflow

Default to the managed browser-use browser. Do **not** start by trying to attach to the user's existing Chrome unless the task explicitly requires existing cookies/profile state

1. **Navigate**: `browser-use open <url>` — launches managed Chromium and opens the page
2. **Inspect**: `browser-use state` — returns clickable elements with indices
3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
4. **Probe when needed**: use `browser-use eval "js"` to inspect app state, DOM, local/session storage, network-visible globals, or rendered text
5. **Verify visually**: use `browser-use screenshot <path.png>` for UI evidence
6. **Repeat**: browser stays open between commands

## Authorization for state-changing actions

- Use browser tools freely for read-only navigation and inspection. Before an action that submits data, changes a remote site, uploads content, provisions a cloud resource, opens a public tunnel, or changes, exports, or syncs cookie or profile data, the user must request and explicitly approve it. State the exact tool or subcommand, action, target, expected effect, and every relevant credential, data, cost, time, environment, and destructive boundary. Wait before running it

For read-only cookie or storage inspection, prefer names and metadata. Retrieve only values the task needs. Do not repeat secret values in chat or persist them in files unless the task requires that data and the applicable authorization boundary permits its disclosure or persistence

## Recovery and cleanup

- Only for a task-owned managed browser started for this task, run `browser-use close` after a command failure and retry. Never use `browser-use close` as automatic recovery after `connect`, `cloud connect`, or a `--profile` session
- it can close a user-connected/profile browser or stop a cloud browser. Before closing any of those sessions, state that effect and obtain the user's explicit approval

For local dev-server testing, the expected default is:

```bash
browser-use open http://127.0.0.1:<port>
browser-use state
browser-use eval "(() => ({ url: location.href, text: document.body.innerText.slice(0, 1000) }))()"
browser-use screenshot .scratch/ui-screenshots/<name>.png
```

Only use the user's existing Chrome/profile when managed Chromium is insufficient because the exact task needs an already-authenticated external/private session

### Auth and session strategy

1. **Local dev apps:** first use managed Chromium (`browser-use open`, `state`, `eval`, `screenshot`). If it lands on a login screen, inspect the app's local dev auth path, test-user setup, local API/session mechanism, or documented auth bypass before asking the user to relaunch Chrome. Use app-supported local auth/test setup when available
   - do not invent production auth bypasses
2. **External/private sites:** if existing cookies are required, try `browser-use connect` or `browser-use profile list`
3. **If `browser-use connect` fails:** do not get stuck on remote debugging. Fall back to managed Chromium/profile discovery and continue with whatever can be tested. Ask the user about Chrome remote debugging only when existing browser cookies are strictly required and no profile/session alternative exists

## Browser Modes

```bash
browser-use open <url>                         # Default: headless Chromium (no setup needed)
browser-use --headed open <url>                # Visible window (for debugging)
browser-use connect                            # Connect to user's Chrome (preserves logins/cookies)
browser-use cloud connect                      # Cloud browser (zero-config, requires API key)
browser-use --profile "Default" open <url>     # Real Chrome with specific profile
```

After `connect` or `cloud connect`, all subsequent commands go to that browser — no extra flags needed

## Commands

```bash
# Navigation
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back in history
browser-use scroll down                   # Scroll down (--amount N for pixels)
browser-use scroll up                     # Scroll up
browser-use tab list                      # List all tabs
browser-use tab new [url]                 # Open a new tab (blank or with URL)
browser-use tab switch <index>            # Switch to tab by index
browser-use tab close <index> [index...]  # Close one or more tabs

# Page State — always run state first to get element indices
browser-use state                         # URL, title, clickable elements with indices
browser-use screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)

# Interactions — use indices from state
browser-use click <index>                 # Click element by index
browser-use click <x> <y>                 # Click at pixel coordinates
browser-use type "text"                   # Type into focused element
browser-use input <index> "text"          # Click element, clear existing text, then type
browser-use input <index> ""              # Clear a field without typing new text
browser-use keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
browser-use select <index> "option"       # Select dropdown option
browser-use upload <index> <path>         # Upload file to file input
browser-use hover <index>                 # Hover over element
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element

# Data Extraction
browser-use eval "js code"                # Execute JavaScript, return result
browser-use get title                     # Page title
browser-use get html [--selector "h1"]    # Page HTML (or scoped to selector)
browser-use get text <index>              # Element text content
browser-use get value <index>             # Input/textarea value
browser-use get attributes <index>        # Element attributes
browser-use get bbox <index>              # Bounding box (x, y, width, height)

# Wait
browser-use wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text"              # Wait for text to appear

# Cookies
browser-use cookies get [--url <url>]     # Get cookies (optionally filtered)
browser-use cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Clear cookies
browser-use cookies export <file>         # Export to JSON
browser-use cookies import <file>         # Import from JSON

# Session
browser-use close                         # Close browser and stop daemon
browser-use sessions                      # List active sessions
browser-use close --all                   # Close all sessions
```

From OrestesK/pi, MIT.

More from OrestesK/pi