Browser Use CLI

Use this skill for terminal-driven browser automation with browser-use. It covers both local browser control and Browser Use cloud/platform workflows.

Start by Choosing the Mode

Choose one mode before doing anything else:

1. Local Chromium mode
2. Real browser mode
3. Remote/cloud mode
4. MCP mode

Do not mix them casually. Pick the simplest mode that matches the task.

Prefer the Right Mode

Use local Chromium mode when

• the task is a local browser automation flow
• no existing login session is required
• you want a reproducible headless/default environment
• screenshots, state inspection, click/input, and JS execution are enough

Use real browser mode when

• the task depends on existing Chrome logins/cookies
• the user wants to reuse a local browser profile
• site behavior differs in a real profile context
• you need to connect to an already running browser or Chrome profile

Use remote/cloud mode when

• the task needs Browser Use cloud browsers
• you need a Browser Use API key workflow
• you need cloud tasks, workspaces, profiles, or billing/API operations
• you need tunnels for local dev servers exposed to cloud browsers

Use MCP mode when

• the user wants Browser Use exposed as an MCP server
• another agent/client should drive Browser Use over stdio JSON-RPC

Core Local Workflow

Default local flow:

1. browser-use open <url>
2. browser-use state
3. interact with indices using click, input, type, select, hover, keys
4. inspect again with state
5. capture with screenshot when needed
6. finish with browser-use close

Treat state as the main discovery step. Element indices come from state and are the basis for later actions.

Most Useful Commands

Navigation and inspection

• browser-use open <url>
• browser-use back
• browser-use state
• browser-use screenshot [path]
• browser-use get title
• browser-use get html
• browser-use eval "<js>"

Interaction

• browser-use click <index>
• browser-use input <index> "text"
• browser-use type "text"
• browser-use keys "Enter"
• browser-use select <index> "value"
• browser-use hover <index>

Waiting and retrieval

• browser-use wait selector "css"
• browser-use wait text "Success"
• browser-use get text <index>
• browser-use get value <index>
• browser-use get attributes <index>

Session management

• browser-use --session NAME ...
• browser-use sessions
• browser-use close
• browser-use close --all

Real Browser Mode

Use real mode when login reuse matters.

Typical patterns:

• browser-use --browser real --profile "Default" open https://gmail.com
• browser-use --browser real --profile "Profile 1" open <url>
• browser-use --browser real open <url>

If a site requires an already running browser or existing local profile context, prefer real mode over local Chromium mode.

Cloud / Platform Mode

Cloud mode depends on Browser Use API auth.

Core commands:

• browser-use cloud login <api-key>
• browser-use cloud connect
• browser-use cloud v2 GET <path>
• browser-use cloud v2 POST <path> '<json>'
• browser-use cloud v2 poll <task-id>
• browser-use cloud logout

Use cloud mode when the task is about Browser Use platform objects, cloud browsers, tasks, profiles, or workspaces.

Tunnels

Use Browser Use tunnels when a cloud browser must reach a local dev server.

Core commands:

• browser-use tunnel <port>
• browser-use tunnel list
• browser-use tunnel stop <port>
• browser-use tunnel stop --all

MCP Mode

The CLI can run as an MCP server via stdio. Use browser-use --mcp when another client/agent needs Browser Use tools over JSON-RPC.

Treat this as a separate integration surface. Do not confuse it with ordinary terminal usage.

Tested on This Machine

The following was actually exercised successfully in this environment:

• uv tool install browser-use
• browser-use doctor
• browser-use open https://example.com
• browser-use state
• browser-use get title
• browser-use screenshot generated/browser_use_test/chromium_example.png
• browser-use --browser real open https://example.com
• browser-use --browser real state
• browser-use sessions
• browser-use close --all

Important nuance:

• browser-use install attempted to install system dependencies and failed because Linux dependency installation wanted sudo
• despite that, local open/state/screenshot still worked in this environment

Practical Guidance

• Start with local Chromium mode unless logins or cloud are required.
• Use named sessions for parallel work.
• Use state after every meaningful page change.
• Close sessions when done.
• For cloud mode, authenticate first.
• For remote sites with login state, prefer real browser mode.

References

Read these bundled references when needed:

• references/quickstart.md for the short command flow
• references/cloud-and-platform.md for cloud/API/tunnel usage
• references/tested-notes.md for what was actually validated here