1---
2name: browser-use
3description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.
4allowed-tools: Bash(browser-use:*)
5---
6 
7# Browser Automation with browser-use CLI
8 
9The `browser-use` command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call.
10 
11## Prerequisites
12 
13```bash
14browser-use doctor    # Verify installation
15```
16 
17For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
18 
19## Core Workflow
20 
211. **Navigate**: `browser-use open <url>` — launches headless browser and opens page
222. **Inspect**: `browser-use state` — returns clickable elements with indices
233. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
244. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
255. **Repeat**: browser stays open between commands
26 
27If a command fails, run `browser-use close` first to clear any broken session, then retry.
28 
29To use the user's existing Chrome (preserves logins/cookies): run `browser-use connect` first.
30To use a cloud browser instead: run `browser-use cloud connect` first.
31After either, commands work the same way.
32 
33### If `browser-use connect` fails
34 
35When `browser-use connect` cannot find a running Chrome with remote debugging, prompt the user with two options:
36 
371. **Use their real Chrome browser** — they need to enable remote debugging first:
38   - Open `chrome://inspect/#remote-debugging` in Chrome, or relaunch Chrome with `--remote-debugging-port=9222`
39   - Then retry `browser-use connect`
402. **Use managed Chromium with their Chrome profile** — no Chrome setup needed:
41   - Run `browser-use profile list` to show available profiles
42   - Ask which profile they want, then use `browser-use --profile "ProfileName" open <url>`
43   - This launches a separate Chromium instance with their profile data (cookies, logins, extensions)
44 
45Let the user choose — don't assume one path over the other.
46 
47## Browser Modes
48 
49```bash
50browser-use open <url>                         # Default: headless Chromium (no setup needed)
51browser-use --headed open <url>                # Visible window (for debugging)
52browser-use connect                            # Connect to user's Chrome (preserves logins/cookies)
53browser-use cloud connect                      # Cloud browser (zero-config, requires API key)
54browser-use --profile "Default" open <url>     # Real Chrome with specific profile
55```
56 
57After `connect` or `cloud connect`, all subsequent commands go to that browser — no extra flags needed.
58 
59## Commands
60 
61```bash
62# Navigation
63browser-use open <url>                    # Navigate to URL
64browser-use back                          # Go back in history
65browser-use scroll down                   # Scroll down (--amount N for pixels)
66browser-use scroll up                     # Scroll up
67browser-use tab list                      # List all tabs
68browser-use tab new [url]                 # Open a new tab (blank or with URL)
69browser-use tab switch <index>            # Switch to tab by index
70browser-use tab close <index> [index...]  # Close one or more tabs
71 
72# Page State — always run state first to get element indices
73browser-use state                         # URL, title, clickable elements with indices
74browser-use screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)
75 
76# Interactions — use indices from state
77browser-use click <index>                 # Click element by index
78browser-use click <x> <y>                 # Click at pixel coordinates
79browser-use type "text"                   # Type into focused element
80browser-use input <index> "text"          # Click element, clear existing text, then type
81browser-use input <index> ""              # Clear a field without typing new text
82browser-use keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
83browser-use select <index> "option"       # Select dropdown option
84browser-use upload <index> <path>         # Upload file to file input
85browser-use hover <index>                 # Hover over element
86browser-use dblclick <index>              # Double-click element
87browser-use rightclick <index>            # Right-click element
88 
89# Data Extraction
90browser-use eval "js code"                # Execute JavaScript, return result
91browser-use get title                     # Page title
92browser-use get html [--selector "h1"]    # Page HTML (or scoped to selector)
93browser-use get text <index>              # Element text content
94browser-use get value <index>             # Input/textarea value
95browser-use get attributes <index>        # Element attributes
96browser-use get bbox <index>              # Bounding box (x, y, width, height)
97 
98# Wait
99browser-use wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
100browser-use wait text "text"              # Wait for text to appear
101 
102# Cookies
103browser-use cookies get [--url <url>]     # Get cookies (optionally filtered)
104browser-use cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
105browser-use cookies clear [--url <url>]   # Clear cookies
106browser-use cookies export <file>         # Export to JSON
107browser-use cookies import <file>         # Import from JSON
108 
109# Session
110browser-use close                         # Close browser and stop daemon
111browser-use sessions                      # List active sessions
112browser-use close --all                   # Close all sessions
113```
114 
115For advanced browser control (CDP, device emulation, tab activation), see `references/cdp-python.md`.
116 
117## Cloud API
118 
119```bash
120browser-use cloud connect                 # Provision cloud browser and connect (zero-config)
121browser-use cloud login <api-key>         # Save API key (or set BROWSER_USE_API_KEY)
122browser-use cloud logout                  # Remove API key
123browser-use cloud v2 GET /browsers        # REST passthrough (v2 or v3)
124browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
125browser-use cloud v2 poll <task-id>       # Poll task until done
126browser-use cloud v2 --help               # Show API endpoints
127```
128 
129`cloud connect` provisions a cloud browser with a persistent profile (auto-created on first use), connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser. For custom browser settings (proxy, timeout, specific profile), use `cloud v2 POST /browsers` directly with the desired parameters.
130 
131### Agent Self-Registration
132 
133Only use this if you don't already have an API key (check `browser-use doctor` to see if api_key is set). If already logged in, skip this entirely.
134 
1351. `browser-use cloud signup` — get a challenge
1362. Solve the challenge
1373. `browser-use cloud signup --verify <challenge-id> <answer>` — verify and save API key
1384. `browser-use cloud signup --claim` — generate URL for a human to claim the account
139 
140## Tunnels
141 
142```bash
143browser-use tunnel <port>                 # Start Cloudflare tunnel (idempotent)
144browser-use tunnel list                   # Show active tunnels
145browser-use tunnel stop <port>            # Stop tunnel
146browser-use tunnel stop --all             # Stop all tunnels
147```
148 
149## Profile Management
150 
151```bash
152browser-use profile list                  # List detected browsers and profiles
153browser-use profile sync --all            # Sync profiles to cloud
154browser-use profile update                # Download/update profile-use binary
155```
156 
157## Command Chaining
158 
159Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
160 
161```bash
162browser-use open https://example.com && browser-use state
163browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7
164```
165 
166Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
167 
168## Common Workflows
169 
170### Authenticated Browsing
171 
172When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles:
173 
174```bash
175browser-use profile list                           # Check available profiles
176# Ask the user which profile to use, then:
177browser-use --profile "Default" open https://github.com  # Already logged in
178```
179 
180### Exposing Local Dev Servers
181 
182```bash
183browser-use tunnel 3000                            # → https://abc.trycloudflare.com
184browser-use open https://abc.trycloudflare.com     # Browse the tunnel
185```
186 
187## Multiple Browsers
188 
189For subagent workflows or running multiple browsers in parallel, use `--session NAME`. Each session gets its own browser. See `references/multi-session.md`.
190 
191## Configuration
192 
193```bash
194browser-use config list                            # Show all config values
195browser-use config set cloud_connect_proxy jp      # Set a value
196browser-use config get cloud_connect_proxy         # Get a value
197browser-use config unset cloud_connect_timeout     # Remove a value
198browser-use doctor                                 # Shows config + diagnostics
199browser-use setup                                  # Interactive post-install setup
200```
201 
202Config stored in `~/.browser-use/config.json`.
203 
204## Global Options
205 
206| Option | Description |
207|--------|-------------|
208| `--headed` | Show browser window |
209| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |
210| `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
211| `--session NAME` | Target a named session (default: "default") |
212| `--json` | Output as JSON |
213| `--mcp` | Run as MCP server via stdin/stdout |
214 
215## Tips
216 
2171. **Always run `state` first** to see available elements and their indices
2182. **Use `--headed` for debugging** to see what the browser is doing
2193. **Sessions persist** — browser stays open between commands
2204. **CLI aliases**: `bu`, `browser`, and `browseruse` all work
2215. **If commands fail**, run `browser-use close` first, then retry
222 
223## Troubleshooting
224 
225- **Browser won't start?** `browser-use close` then `browser-use --headed open <url>`
226- **Element not found?** `browser-use scroll down` then `browser-use state`
227- **Run diagnostics:** `browser-use doctor`
228 
229## Cleanup
230 
231```bash
232browser-use close                         # Close browser session
233browser-use tunnel stop --all             # Stop tunnels (if any)
234```
235