1---
2name: browser-use-cli
3description: "Use when the task needs Browser Use CLI for fast persistent browser automation, browser daemon workflows, real Chrome profile reuse, cloud browser/API management, Browser Use tunnels, or Browser Use MCP mode. Triggers include requests to use `browser-use`, test Browser Use locally, automate a site with Browser Use, connect to Browser Use cloud, or manage Browser Use sessions/profiles from the terminal."
4---
5 
6# Browser Use CLI
7 
8Use this skill for terminal-driven browser automation with `browser-use`.
9It covers both local browser control and Browser Use cloud/platform workflows.
10 
11## Start by Choosing the Mode
12 
13Choose one mode before doing anything else:
14 
151. Local Chromium mode
162. Real browser mode
173. Remote/cloud mode
184. MCP mode
19 
20Do not mix them casually.
21Pick the simplest mode that matches the task.
22 
23## Prefer the Right Mode
24 
25### Use local Chromium mode when
26 
27- the task is a local browser automation flow
28- no existing login session is required
29- you want a reproducible headless/default environment
30- screenshots, state inspection, click/input, and JS execution are enough
31 
32### Use real browser mode when
33 
34- the task depends on existing Chrome logins/cookies
35- the user wants to reuse a local browser profile
36- site behavior differs in a real profile context
37- you need to connect to an already running browser or Chrome profile
38 
39### Use remote/cloud mode when
40 
41- the task needs Browser Use cloud browsers
42- you need a Browser Use API key workflow
43- you need cloud tasks, workspaces, profiles, or billing/API operations
44- you need tunnels for local dev servers exposed to cloud browsers
45 
46### Use MCP mode when
47 
48- the user wants Browser Use exposed as an MCP server
49- another agent/client should drive Browser Use over stdio JSON-RPC
50 
51## Core Local Workflow
52 
53Default local flow:
54 
551. `browser-use open <url>`
562. `browser-use state`
573. interact with indices using `click`, `input`, `type`, `select`, `hover`, `keys`
584. inspect again with `state`
595. capture with `screenshot` when needed
606. finish with `browser-use close`
61 
62Treat `state` as the main discovery step.
63Element indices come from `state` and are the basis for later actions.
64 
65## Most Useful Commands
66 
67### Navigation and inspection
68 
69- `browser-use open <url>`
70- `browser-use back`
71- `browser-use state`
72- `browser-use screenshot [path]`
73- `browser-use get title`
74- `browser-use get html`
75- `browser-use eval "<js>"`
76 
77### Interaction
78 
79- `browser-use click <index>`
80- `browser-use input <index> "text"`
81- `browser-use type "text"`
82- `browser-use keys "Enter"`
83- `browser-use select <index> "value"`
84- `browser-use hover <index>`
85 
86### Waiting and retrieval
87 
88- `browser-use wait selector "css"`
89- `browser-use wait text "Success"`
90- `browser-use get text <index>`
91- `browser-use get value <index>`
92- `browser-use get attributes <index>`
93 
94### Session management
95 
96- `browser-use --session NAME ...`
97- `browser-use sessions`
98- `browser-use close`
99- `browser-use close --all`
100 
101## Real Browser Mode
102 
103Use real mode when login reuse matters.
104 
105Typical patterns:
106 
107- `browser-use --browser real --profile "Default" open https://gmail.com`
108- `browser-use --browser real --profile "Profile 1" open <url>`
109- `browser-use --browser real open <url>`
110 
111If a site requires an already running browser or existing local profile context, prefer real mode over local Chromium mode.
112 
113## Cloud / Platform Mode
114 
115Cloud mode depends on Browser Use API auth.
116 
117Core commands:
118 
119- `browser-use cloud login <api-key>`
120- `browser-use cloud connect`
121- `browser-use cloud v2 GET <path>`
122- `browser-use cloud v2 POST <path> '<json>'`
123- `browser-use cloud v2 poll <task-id>`
124- `browser-use cloud logout`
125 
126Use cloud mode when the task is about Browser Use platform objects, cloud browsers, tasks, profiles, or workspaces.
127 
128## Tunnels
129 
130Use Browser Use tunnels when a cloud browser must reach a local dev server.
131 
132Core commands:
133 
134- `browser-use tunnel <port>`
135- `browser-use tunnel list`
136- `browser-use tunnel stop <port>`
137- `browser-use tunnel stop --all`
138 
139## MCP Mode
140 
141The CLI can run as an MCP server via stdio.
142Use `browser-use --mcp` when another client/agent needs Browser Use tools over JSON-RPC.
143 
144Treat this as a separate integration surface.
145Do not confuse it with ordinary terminal usage.
146 
147## Tested on This Machine
148 
149The following was actually exercised successfully in this environment:
150 
151- `uv tool install browser-use`
152- `browser-use doctor`
153- `browser-use open https://example.com`
154- `browser-use state`
155- `browser-use get title`
156- `browser-use screenshot generated/browser_use_test/chromium_example.png`
157- `browser-use --browser real open https://example.com`
158- `browser-use --browser real state`
159- `browser-use sessions`
160- `browser-use close --all`
161 
162Important nuance:
163 
164- `browser-use install` attempted to install system dependencies and failed because Linux dependency installation wanted `sudo`
165- despite that, local `open/state/screenshot` still worked in this environment
166 
167## Practical Guidance
168 
169- Start with local Chromium mode unless logins or cloud are required.
170- Use named sessions for parallel work.
171- Use `state` after every meaningful page change.
172- Close sessions when done.
173- For cloud mode, authenticate first.
174- For remote sites with login state, prefer real browser mode.
175 
176## References
177 
178Read these bundled references when needed:
179 
180- `references/quickstart.md` for the short command flow
181- `references/cloud-and-platform.md` for cloud/API/tunnel usage
182- `references/tested-notes.md` for what was actually validated here
183