浏览器模式

browser-use --browser chromium open <url>      # 默认：无头 Chromium
browser-use --browser chromium --headed open <url>  # 可见的 Chromium 窗口
browser-use --browser real open <url>          # 真实 Chrome（无配置文件 = 全新）
browser-use --browser real --profile "Default" open <url>  # 使用您登录会话的真实 Chrome
browser-use --browser remote open <url>        # 云端浏览器

• chromium : 快速、隔离、默认无头
• real : 使用真实的 Chrome 二进制文件。没有 --profile 时，使用位于 ~/.config/browseruse/profiles/cli/ 的持久但空的 CLI 配置文件。使用 --profile "ProfileName" 时，复制您实际的 Chrome 配置文件（cookies、登录信息、扩展程序）
• remote : 支持代理的云端托管浏览器

基本命令

# 导航
browser-use open <url>                    # 导航到 URL
browser-use back                          # 后退
browser-use scroll down                   # 向下滚动（--amount N 指定像素数）

# 页面状态（始终先运行 state 命令以获取元素索引）
browser-use state                         # 获取 URL、标题、可点击元素
browser-use screenshot                    # 截图（base64）
browser-use screenshot path.png           # 保存截图到文件

# 交互（使用 state 中的索引）
browser-use click <index>                 # 点击元素
browser-use type "text"                   # 在焦点元素中输入文本
browser-use input <index> "text"          # 点击元素，然后输入文本
browser-use keys "Enter"                  # 发送键盘按键
browser-use select <index> "option"       # 选择下拉选项

# 数据提取
browser-use eval "document.title"         # 执行 JavaScript
browser-use get text <index>              # 获取元素文本
browser-use get html --selector "h1"      # 获取限定范围的 HTML

# 等待
browser-use wait selector "h1"            # 等待元素出现
browser-use wait text "Success"           # 等待文本出现

# 会话
browser-use sessions                      # 列出活动会话
browser-use close                         # 关闭当前会话
browser-use close --all                   # 关闭所有会话

# AI 代理
browser-use -b remote run "task"          # 在云端运行代理（默认异步）
browser-use task status <id>              # 检查云端任务进度

命令

导航与标签页

browser-use open <url>                    # 导航到 URL
browser-use back                          # 历史后退
browser-use scroll down                   # 向下滚动
browser-use scroll up                     # 向上滚动
browser-use scroll down --amount 1000     # 按指定像素滚动（默认：500）
browser-use switch <tab>                  # 按索引切换到标签页
browser-use close-tab                     # 关闭当前标签页
browser-use close-tab <tab>              # 关闭特定标签页

页面状态

browser-use state                         # 获取 URL、标题和可点击元素
browser-use screenshot                    # 截图（输出 base64）
browser-use screenshot path.png           # 保存截图到文件
browser-use screenshot --full path.png    # 完整页面截图

交互

browser-use click <index>                 # 点击元素
browser-use type "text"                   # 在焦点元素中输入文本
browser-use input <index> "text"          # 点击元素，然后输入文本
browser-use keys "Enter"                  # 发送键盘按键
browser-use keys "Control+a"              # 发送组合键
browser-use select <index> "option"       # 选择下拉选项
browser-use hover <index>                 # 悬停在元素上（触发 CSS :hover）
browser-use dblclick <index>              # 双击元素
browser-use rightclick <index>            # 右键点击元素（上下文菜单）

使用 browser-use state 中的索引。

JavaScript 与数据

browser-use eval "document.title"         # 执行 JavaScript，返回结果
browser-use get title                     # 获取页面标题
browser-use get html                      # 获取完整页面 HTML
browser-use get html --selector "h1"      # 获取特定元素的 HTML
browser-use get text <index>              # 获取元素的文本内容
browser-use get value <index>             # 获取输入框/文本域的值
browser-use get attributes <index>        # 获取元素的所有属性
browser-use get bbox <index>              # 获取边界框（x, y, 宽度, 高度）

Cookies

browser-use cookies get                   # 获取所有 cookies
browser-use cookies get --url <url>       # 获取特定 URL 的 cookies
browser-use cookies set <name> <value>    # 设置 cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies set name val --same-site Strict  # SameSite：Strict、Lax 或 None
browser-use cookies set name val --expires 1735689600  # 过期时间戳
browser-use cookies clear                 # 清除所有 cookies
browser-use cookies clear --url <url>     # 清除特定 URL 的 cookies
browser-use cookies export <file>         # 将所有 cookies 导出到 JSON 文件
browser-use cookies export <file> --url <url>  # 导出特定 URL 的 cookies
browser-use cookies import <file>         # 从 JSON 文件导入 cookies

等待条件

browser-use wait selector "h1"            # 等待元素可见
browser-use wait selector ".loading" --state hidden  # 等待元素消失
browser-use wait selector "#btn" --state attached    # 等待元素出现在 DOM 中
browser-use wait text "Success"           # 等待文本出现
browser-use wait selector "h1" --timeout 5000  # 自定义超时时间（毫秒）

Python 执行

browser-use python "x = 42"               # 设置变量
browser-use python "print(x)"             # 访问变量（输出：42）
browser-use python "print(browser.url)"   # 访问浏览器对象
browser-use python --vars                 # 显示已定义的变量
browser-use python --reset                # 清除 Python 命名空间
browser-use python --file script.py       # 执行 Python 文件

Python 会话在命令之间保持状态。browser 对象提供：

• browser.url、browser.title、browser.html — 页面信息
• browser.goto(url)、browser.back() — 导航
• browser.click(index)、browser.type(text)、browser.input(index, text)、browser.keys(keys) — 交互
• browser.screenshot(path)、browser.scroll(direction, amount) — 视觉
• browser.wait(seconds)、browser.extract(query) — 实用工具

代理任务

远程模式选项

使用 --browser remote 时，可使用以下附加选项：

# 指定 LLM 模型
browser-use -b remote run "task" --llm gpt-4o
browser-use -b remote run "task" --llm claude-sonnet-4-20250514

# 代理配置（默认：us）
browser-use -b remote run "task" --proxy-country uk

# 会话重用
browser-use -b remote run "task 1" --keep-alive        # 任务完成后保持会话活动
browser-use -b remote run "task 2" --session-id abc-123 # 重用现有会话

# 执行模式
browser-use -b remote run "task" --flash       # 快速执行模式
browser-use -b remote run "task" --wait        # 等待完成（默认：异步）

# 高级选项
browser-use -b remote run "task" --thinking    # 扩展推理模式
browser-use -b remote run "task" --no-vision   # 禁用视觉（默认启用）

# 使用云端配置文件（先创建会话，然后使用 --session-id 运行）
browser-use session create --profile <cloud-profile-id> --keep-alive
# → 返回 session_id
browser-use -b remote run "task" --session-id <session-id>

# 任务配置
browser-use -b remote run "task" --start-url https://example.com  # 从特定 URL 开始
browser-use -b remote run "task" --allowed-domain example.com     # 限制导航（可重复）
browser-use -b remote run "task" --metadata key=value             # 任务元数据（可重复）
browser-use -b remote run "task" --skill-id skill-123             # 启用技能（可重复）
browser-use -b remote run "task" --secret key=value               # 秘密元数据（可重复）

# 结构化输出和评估
browser-use -b remote run "task" --structured-output '{"type":"object"}'  # 输出的 JSON 模式
browser-use -b remote run "task" --judge                 # 启用评判模式
browser-use -b remote run "task" --judge-ground-truth "expected answer"

任务管理

browser-use task list                     # 列出最近的任务
browser-use task list --limit 20          # 显示更多任务
browser-use task list --status finished   # 按状态过滤（finished、stopped）
browser-use task list --session <id>      # 按会话 ID 过滤
browser-use task list --json              # JSON 输出

browser-use task status <task-id>         # 获取任务状态（仅最新步骤）
browser-use task status <task-id> -c      # 所有步骤（含推理）
browser-use task status <task-id> -v      # 所有步骤（含 URL + 操作）
browser-use task status <task-id> --last 5  # 仅最后 N 个步骤
browser-use task status <task-id> --step 3  # 特定步骤编号
browser-use task status <task-id> --reverse # 最新优先

browser-use task stop <task-id>           # 停止正在运行的任务
browser-use task logs <task-id>           # 获取任务执行日志

云端会话管理

browser-use session list                  # 列出云端会话
browser-use session list --limit 20       # 显示更多会话
browser-use session list --status active  # 按状态过滤
browser-use session list --json           # JSON 输出

browser-use session get <session-id>      # 获取会话详情 + 实时 URL
browser-use session get <session-id> --json

browser-use session stop <session-id>     # 停止会话
browser-use session stop --all            # 停止所有活动会话

browser-use session create                          # 使用默认值创建
browser-use session create --profile <id>           # 使用云端配置文件
browser-use session create --proxy-country uk       # 使用地理代理
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory

browser-use session share <session-id>              # 创建公共分享 URL
browser-use session share <session-id> --delete     # 删除公共分享

隧道

browser-use tunnel <port>           # 启动隧道（返回 URL）
browser-use tunnel <port>           # 幂等性 - 返回现有 URL
browser-use tunnel list             # 显示活动隧道
browser-use tunnel stop <port>      # 停止隧道
browser-use tunnel stop --all       # 停止所有隧道

会话管理

browser-use sessions                      # 列出活动会话
browser-use close                         # 关闭当前会话
browser-use close --all                   # 关闭所有会话

配置文件管理

本地 Chrome 配置文件（--browser real）

browser-use -b real profile list          # 列出本地 Chrome 配置文件
browser-use -b real profile cookies "Default"  # 显示配置文件中的 cookie 域名

云端配置文件（--browser remote）

browser-use -b remote profile list            # 列出云端配置文件
browser-use -b remote profile list --page 2 --page-size 50
browser-use -b remote profile get <id>        # 获取配置文件详情
browser-use -b remote profile create          # 创建新的云端配置文件
browser-use -b remote profile create --name "My Profile"
browser-use -b remote profile update <id> --name "New"
browser-use -b remote profile delete <id>

同步

browser-use profile sync --from "Default" --domain github.com  # 特定域名
browser-use profile sync --from "Default"                      # 完整配置文件
browser-use profile sync --from "Default" --name "Custom Name" # 使用自定义名称

服务器控制

browser-use server logs                   # 查看服务器日志

常见工作流程

暴露本地开发服务器

当您有本地开发服务器且需要云端浏览器访问时使用。

核心工作流程： 启动开发服务器 → 创建隧道 → 远程浏览隧道 URL。

# 1. 启动您的开发服务器
npm run dev &  # localhost:3000

# 2. 通过 Cloudflare 隧道暴露它
browser-use tunnel 3000
# → url: https://abc.trycloudflare.com

# 3. 现在云端浏览器可以访问您的本地服务器了
browser-use --browser remote open https://abc.trycloudflare.com
browser-use state
browser-use screenshot

注意： 隧道独立于浏览器会话。它们在 browser-use close 后仍然存在，并且可以单独管理。必须安装 Cloudflared — 运行 browser-use doctor 进行检查。

使用配置文件进行身份验证浏览

当任务需要浏览用户已登录的网站（例如 Gmail、GitHub、内部工具）时使用。

核心工作流程： 检查现有配置文件 → 询问用户使用哪个配置文件和浏览器模式 → 使用该配置文件浏览。仅在没有合适配置文件时同步 cookies。

在浏览需要身份验证的网站之前，代理必须：

1. 询问用户使用 real（本地 Chrome）还是 remote（云端）浏览器
2. 列出该模式下的可用配置文件
3. 询问使用哪个配置文件
4. 如果没有配置文件包含正确的 cookies，提供同步选项（见下文）

步骤 1：检查现有配置文件

# 选项 A：本地 Chrome 配置文件（--browser real）
browser-use -b real profile list
# → Default: Person 1 (user@gmail.com)
# → Profile 1: Work (work@company.com)

# 选项 B：云端配置文件（--browser remote）
browser-use -b remote profile list
# → abc-123: "Chrome - Default (github.com)"
# → def-456: "Work profile"

步骤 2：使用所选配置文件浏览

# 真实浏览器 — 使用带有现有登录会话的本地 Chrome
browser-use --browser real --profile "Default" open https://github.com

# 云端浏览器 — 使用带有同步 cookies 的云端配置文件
browser-use --browser remote --profile abc-123 open https://github.com

用户已经通过身份验证 — 无需登录。

注意： 云端配置文件的 cookies 可能会随时间过期。如果身份验证失败，请从本地 Chrome 配置文件重新同步 cookies。

步骤 3：同步 cookies（仅在需要时）

如果用户想要使用云端浏览器但没有云端配置文件包含正确的 cookies，则从本地 Chrome 配置文件同步它们。

在同步之前，代理必须：

1. 询问使用哪个本地 Chrome 配置文件
2. 询问同步哪个域名 — 不要默认同步完整配置文件
3. 在继续之前进行确认

检查本地配置文件包含哪些 cookies：

browser-use -b real profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2

域名特定同步（推荐）：

browser-use profile sync --from "Default" --domain github.com
# 创建新的云端配置文件："Chrome - Default (github.com)"
# 仅同步 github.com 的 cookies

完整配置文件同步（谨慎使用）：

browser-use profile sync --from "Default"
# 同步所有 cookies — 包括敏感数据、跟踪 cookies、每个会话令牌

仅在用户明确需要其完整浏览器状态时使用。

精细控制（高级）：

# 将 cookies 导出到文件，手动编辑，然后导入
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

使用同步的配置文件：

browser-use --browser remote --profile <id> open https://github.com

运行子代理

使用云端会话并行运行自主浏览器代理。

核心工作流程： 使用 run 启动任务 → 使用 task status 轮询 → 收集结果 → 清理会话。

• 会话 = 代理 : 每个云端会话都是一个具有自己状态的浏览器代理
• 任务 = 工作 : 分配给代理的任务；一个代理可以顺序运行多个任务
• 会话生命周期 : 一旦停止，会话无法恢复 — 启动一个新的

启动任务

# 单个任务（默认异步 — 立即返回）
browser-use -b remote run "Search for AI news and summarize top 3 articles"
# → task_id: task-abc, session_id: sess-123

# 并行任务 — 每个都有自己的会话
browser-use -b remote run "Research competitor A pricing"
# → task_id: task-1, session_id: sess-a
browser-use -b remote run "Research competitor B pricing"
# → task_id: task-2, session_id: sess-b
browser-use -b remote run "Research competitor C pricing"
# → task_id: task-3, session_id: sess-c

# 同一会话中的顺序任务（重用 cookies、登录状态等）
browser-use -b remote run "Log into example.com" --keep-alive
# → task_id: task-1, session_id: sess-123
browser-use task status task-1  # 等待完成
browser-use -b remote run "Export settings" --session-id sess-123
# → task_id: task-2, session_id: sess-123（同一会话）

管理与停止

browser-use task list --status finished      # 查看已完成的任务
browser-use task stop task-abc               # 停止任务（如果 --keep-alive，会话可能继续）
browser-use session stop sess-123            # 停止整个会话（终止其任务）
browser-use session stop --all               # 停止所有会话

监控

任务状态设计为令牌高效。 默认输出是最小化的 — 仅在需要时扩展：

# 对于长任务（50+ 步骤）
browser-use task status <id> -c --last 5   # 仅最后 5 个步骤
browser-use task status <id> -v --step 10  # 检查特定步骤

实时查看 : browser-use session get <session-id> 返回一个实时 URL 来观看代理。

检测卡住的任务 : 如果 task status 中的成本/持续时间停止增加，则任务卡住了 — 停止它并启动新的代理。

日志 : browser-use task logs <task-id> — 仅在任务完成后可用。

全局选项

会话行为 : 所有没有 --session 的命令都使用相同的 "default" 会话。浏览器保持打开状态并在命令之间重用。使用 --session NAME 并行运行多个浏览器。

提示

1. 始终先运行browser-use state 以查看可用元素及其索引
2. 使用--headed进行调试 以查看浏览器正在做什么
3. 会话持久化 — 浏览器在命令之间保持打开
4. 使用--json 进行程序化解析
5. Python 变量在会话内的browser-use python命令之间持久化
6. CLI 别名 : bu、browser 和 browseruse 都与 browser-use 功能相同

故障排除

首先运行诊断：

browser-use doctor

浏览器无法启动？

browser-use close --all               # 关闭所有会话
browser-use --headed open <url>       # 尝试使用可见窗口

找不到元素？

browser-use state                     # 检查当前元素
browser-use scroll down               # 元素可能在折叠下方
browser-use state                     # 再次检查

会话问题？

browser-use sessions                  # 检查活动会话
browser-use close --all               # 清理状态
browser-use open <url>                # 重新开始

task stop后会话重用失败：如果停止任务并尝试重用其会话，新任务可能会卡在 "created" 状态。改为创建新会话：

browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "new task" --session-id <new-session-id>

任务卡在 "started" : 使用 task status 检查成本 — 如果不增加，则任务卡住了。使用 session get 查看实时 URL，然后停止并启动新的代理。

任务完成后会话仍然存在 : 任务完成不会自动停止会话。运行 browser-use session stop --all 进行清理。

清理

完成后始终关闭浏览器：

browser-use close                     # 关闭浏览器会话
browser-use session stop --all        # 停止云端会话（如果有）
browser-use tunnel stop --all         # 停止隧道（如果有）

每周安装量

46.3K

仓库

browser-use/browser-use

GitHub Stars

79.9K

首次出现

Jan 22, 2026

安全审计

Gen Agent Trust HubWarnSocketFailSnykFail

安装于

claude-code37.3K

cursor34.3K

gemini-cli30.1K

opencode29.6K

codex29.0K

antigravity28.2K

Browser Modes

browser-use --browser chromium open <url>      # Default: headless Chromium
browser-use --browser chromium --headed open <url>  # Visible Chromium window
browser-use --browser real open <url>          # Real Chrome (no profile = fresh)
browser-use --browser real --profile "Default" open <url>  # Real Chrome with your login sessions
browser-use --browser remote open <url>        # Cloud browser

• chromium : Fast, isolated, headless by default
• real : Uses a real Chrome binary. Without --profile, uses a persistent but empty CLI profile at ~/.config/browseruse/profiles/cli/. With --profile "ProfileName", copies your actual Chrome profile (cookies, logins, extensions)
• remote : Cloud-hosted browser with proxy support

Essential Commands

# Navigation
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back
browser-use scroll down                   # Scroll down (--amount N for pixels)

# Page State (always run state first to get element indices)
browser-use state                         # Get URL, title, clickable elements
browser-use screenshot                    # Take screenshot (base64)
browser-use screenshot path.png           # Save screenshot to file

# Interactions (use indices from state)
browser-use click <index>                 # Click element
browser-use type "text"                   # Type into focused element
browser-use input <index> "text"          # Click element, then type
browser-use keys "Enter"                  # Send keyboard keys
browser-use select <index> "option"       # Select dropdown option

# Data Extraction
browser-use eval "document.title"         # Execute JavaScript
browser-use get text <index>              # Get element text
browser-use get html --selector "h1"      # Get scoped HTML

# Wait
browser-use wait selector "h1"            # Wait for element
browser-use wait text "Success"           # Wait for text

# Session
browser-use sessions                      # List active sessions
browser-use close                         # Close current session
browser-use close --all                   # Close all sessions

# AI Agent
browser-use -b remote run "task"          # Run agent in cloud (async by default)
browser-use task status <id>              # Check cloud task progress

Commands

Navigation & Tabs

browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back in history
browser-use scroll down                   # Scroll down
browser-use scroll up                     # Scroll up
browser-use scroll down --amount 1000     # Scroll by specific pixels (default: 500)
browser-use switch <tab>                  # Switch to tab by index
browser-use close-tab                     # Close current tab
browser-use close-tab <tab>              # Close specific tab

Page State

browser-use state                         # Get URL, title, and clickable elements
browser-use screenshot                    # Take screenshot (outputs base64)
browser-use screenshot path.png           # Save screenshot to file
browser-use screenshot --full path.png    # Full page screenshot

Interactions

browser-use click <index>                 # Click element
browser-use type "text"                   # Type text into focused element
browser-use input <index> "text"          # Click element, then type text
browser-use keys "Enter"                  # Send keyboard keys
browser-use keys "Control+a"              # Send key combination
browser-use select <index> "option"       # Select dropdown option
browser-use hover <index>                 # Hover over element (triggers CSS :hover)
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element (context menu)

Use indices from browser-use state.

JavaScript & Data

browser-use eval "document.title"         # Execute JavaScript, return result
browser-use get title                     # Get page title
browser-use get html                      # Get full page HTML
browser-use get html --selector "h1"      # Get HTML of specific element
browser-use get text <index>              # Get text content of element
browser-use get value <index>             # Get value of input/textarea
browser-use get attributes <index>        # Get all attributes of element
browser-use get bbox <index>              # Get bounding box (x, y, width, height)

Cookies

browser-use cookies get                   # Get all cookies
browser-use cookies get --url <url>       # Get cookies for specific URL
browser-use cookies set <name> <value>    # Set a cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies set name val --same-site Strict  # SameSite: Strict, Lax, or None
browser-use cookies set name val --expires 1735689600  # Expiration timestamp
browser-use cookies clear                 # Clear all cookies
browser-use cookies clear --url <url>     # Clear cookies for specific URL
browser-use cookies export <file>         # Export all cookies to JSON file
browser-use cookies export <file> --url <url>  # Export cookies for specific URL
browser-use cookies import <file>         # Import cookies from JSON file

Wait Conditions

browser-use wait selector "h1"            # Wait for element to be visible
browser-use wait selector ".loading" --state hidden  # Wait for element to disappear
browser-use wait selector "#btn" --state attached    # Wait for element in DOM
browser-use wait text "Success"           # Wait for text to appear
browser-use wait selector "h1" --timeout 5000  # Custom timeout in ms

Python Execution

browser-use python "x = 42"               # Set variable
browser-use python "print(x)"             # Access variable (outputs: 42)
browser-use python "print(browser.url)"   # Access browser object
browser-use python --vars                 # Show defined variables
browser-use python --reset                # Clear Python namespace
browser-use python --file script.py       # Execute Python file

The Python session maintains state across commands. The browser object provides:

• browser.url, browser.title, browser.html — page info
• browser.goto(url), browser.back() — navigation
• browser.click(index), browser.type(text), browser.input(index, text), browser.keys(keys) — interactions
• browser.screenshot(path), browser.scroll(direction, amount) — visual
• browser.wait(seconds), browser.extract(query) — utilities

Agent Tasks

Remote Mode Options

When using --browser remote, additional options are available:

# Specify LLM model
browser-use -b remote run "task" --llm gpt-4o
browser-use -b remote run "task" --llm claude-sonnet-4-20250514

# Proxy configuration (default: us)
browser-use -b remote run "task" --proxy-country uk

# Session reuse
browser-use -b remote run "task 1" --keep-alive        # Keep session alive after task
browser-use -b remote run "task 2" --session-id abc-123 # Reuse existing session

# Execution modes
browser-use -b remote run "task" --flash       # Fast execution mode
browser-use -b remote run "task" --wait        # Wait for completion (default: async)

# Advanced options
browser-use -b remote run "task" --thinking    # Extended reasoning mode
browser-use -b remote run "task" --no-vision   # Disable vision (enabled by default)

# Using a cloud profile (create session first, then run with --session-id)
browser-use session create --profile <cloud-profile-id> --keep-alive
# → returns session_id
browser-use -b remote run "task" --session-id <session-id>

# Task configuration
browser-use -b remote run "task" --start-url https://example.com  # Start from specific URL
browser-use -b remote run "task" --allowed-domain example.com     # Restrict navigation (repeatable)
browser-use -b remote run "task" --metadata key=value             # Task metadata (repeatable)
browser-use -b remote run "task" --skill-id skill-123             # Enable skills (repeatable)
browser-use -b remote run "task" --secret key=value               # Secret metadata (repeatable)

# Structured output and evaluation
browser-use -b remote run "task" --structured-output '{"type":"object"}'  # JSON schema for output
browser-use -b remote run "task" --judge                 # Enable judge mode
browser-use -b remote run "task" --judge-ground-truth "expected answer"

Task Management

browser-use task list                     # List recent tasks
browser-use task list --limit 20          # Show more tasks
browser-use task list --status finished   # Filter by status (finished, stopped)
browser-use task list --session <id>      # Filter by session ID
browser-use task list --json              # JSON output

browser-use task status <task-id>         # Get task status (latest step only)
browser-use task status <task-id> -c      # All steps with reasoning
browser-use task status <task-id> -v      # All steps with URLs + actions
browser-use task status <task-id> --last 5  # Last N steps only
browser-use task status <task-id> --step 3  # Specific step number
browser-use task status <task-id> --reverse # Newest first

browser-use task stop <task-id>           # Stop a running task
browser-use task logs <task-id>           # Get task execution logs

Cloud Session Management

browser-use session list                  # List cloud sessions
browser-use session list --limit 20       # Show more sessions
browser-use session list --status active  # Filter by status
browser-use session list --json           # JSON output

browser-use session get <session-id>      # Get session details + live URL
browser-use session get <session-id> --json

browser-use session stop <session-id>     # Stop a session
browser-use session stop --all            # Stop all active sessions

browser-use session create                          # Create with defaults
browser-use session create --profile <id>           # With cloud profile
browser-use session create --proxy-country uk       # With geographic proxy
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory

browser-use session share <session-id>              # Create public share URL
browser-use session share <session-id> --delete     # Delete public share

Tunnels

browser-use tunnel <port>           # Start tunnel (returns URL)
browser-use tunnel <port>           # Idempotent - returns existing URL
browser-use tunnel list             # Show active tunnels
browser-use tunnel stop <port>      # Stop tunnel
browser-use tunnel stop --all       # Stop all tunnels

Session Management

browser-use sessions                      # List active sessions
browser-use close                         # Close current session
browser-use close --all                   # Close all sessions

Profile Management

Local Chrome Profiles (--browser real)

browser-use -b real profile list          # List local Chrome profiles
browser-use -b real profile cookies "Default"  # Show cookie domains in profile

Cloud Profiles (--browser remote)

browser-use -b remote profile list            # List cloud profiles
browser-use -b remote profile list --page 2 --page-size 50
browser-use -b remote profile get <id>        # Get profile details
browser-use -b remote profile create          # Create new cloud profile
browser-use -b remote profile create --name "My Profile"
browser-use -b remote profile update <id> --name "New"
browser-use -b remote profile delete <id>

Syncing

browser-use profile sync --from "Default" --domain github.com  # Domain-specific
browser-use profile sync --from "Default"                      # Full profile
browser-use profile sync --from "Default" --name "Custom Name" # With custom name

Server Control

browser-use server logs                   # View server logs

Common Workflows

Exposing Local Dev Servers

Use when you have a local dev server and need a cloud browser to reach it.

Core workflow: Start dev server → create tunnel → browse the tunnel URL remotely.

# 1. Start your dev server
npm run dev &  # localhost:3000

# 2. Expose it via Cloudflare tunnel
browser-use tunnel 3000
# → url: https://abc.trycloudflare.com

# 3. Now the cloud browser can reach your local server
browser-use --browser remote open https://abc.trycloudflare.com
browser-use state
browser-use screenshot

Note: Tunnels are independent of browser sessions. They persist across browser-use close and can be managed separately. Cloudflared must be installed — run browser-use doctor to check.

Authenticated Browsing with Profiles

Use when a task requires browsing a site the user is already logged into (e.g. Gmail, GitHub, internal tools).

Core workflow: Check existing profiles → ask user which profile and browser mode → browse with that profile. Only sync cookies if no suitable profile exists.

Before browsing an authenticated site, the agent MUST:

1. Ask the user whether to use real (local Chrome) or remote (cloud) browser
2. List available profiles for that mode
3. Ask which profile to use
4. If no profile has the right cookies, offer to sync (see below)

Step 1: Check existing profiles

# Option A: Local Chrome profiles (--browser real)
browser-use -b real profile list
# → Default: Person 1 (user@gmail.com)
# → Profile 1: Work (work@company.com)

# Option B: Cloud profiles (--browser remote)
browser-use -b remote profile list
# → abc-123: "Chrome - Default (github.com)"
# → def-456: "Work profile"

Step 2: Browse with the chosen profile

# Real browser — uses local Chrome with existing login sessions
browser-use --browser real --profile "Default" open https://github.com

# Cloud browser — uses cloud profile with synced cookies
browser-use --browser remote --profile abc-123 open https://github.com

The user is already authenticated — no login needed.

Note: Cloud profile cookies can expire over time. If authentication fails, re-sync cookies from the local Chrome profile.

Step 3: Syncing cookies (only if needed)

If the user wants to use a cloud browser but no cloud profile has the right cookies, sync them from a local Chrome profile.

Before syncing, the agent MUST:

1. Ask which local Chrome profile to use
2. Ask which domain(s) to sync — do NOT default to syncing the full profile
3. Confirm before proceeding

Check what cookies a local profile has:

browser-use -b real profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2

Domain-specific sync (recommended):

browser-use profile sync --from "Default" --domain github.com
# Creates new cloud profile: "Chrome - Default (github.com)"
# Only syncs github.com cookies

Full profile sync (use with caution):

browser-use profile sync --from "Default"
# Syncs ALL cookies — includes sensitive data, tracking cookies, every session token

Only use when the user explicitly needs their entire browser state.

Fine-grained control (advanced):

# Export cookies to file, manually edit, then import
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

Use the synced profile:

browser-use --browser remote --profile <id> open https://github.com

Running Subagents

Use cloud sessions to run autonomous browser agents in parallel.

Core workflow: Launch task(s) with run → poll with task status → collect results → clean up sessions.

• Session = Agent : Each cloud session is a browser agent with its own state
• Task = Work : Jobs given to an agent; an agent can run multiple tasks sequentially
• Session lifecycle : Once stopped, a session cannot be revived — start a new one

Launching Tasks

# Single task (async by default — returns immediately)
browser-use -b remote run "Search for AI news and summarize top 3 articles"
# → task_id: task-abc, session_id: sess-123

# Parallel tasks — each gets its own session
browser-use -b remote run "Research competitor A pricing"
# → task_id: task-1, session_id: sess-a
browser-use -b remote run "Research competitor B pricing"
# → task_id: task-2, session_id: sess-b
browser-use -b remote run "Research competitor C pricing"
# → task_id: task-3, session_id: sess-c

# Sequential tasks in same session (reuses cookies, login state, etc.)
browser-use -b remote run "Log into example.com" --keep-alive
# → task_id: task-1, session_id: sess-123
browser-use task status task-1  # Wait for completion
browser-use -b remote run "Export settings" --session-id sess-123
# → task_id: task-2, session_id: sess-123 (same session)

Managing & Stopping

browser-use task list --status finished      # See completed tasks
browser-use task stop task-abc               # Stop a task (session may continue if --keep-alive)
browser-use session stop sess-123            # Stop an entire session (terminates its tasks)
browser-use session stop --all               # Stop all sessions

Monitoring

Task status is designed for token efficiency. Default output is minimal — only expand when needed:

# For long tasks (50+ steps)
browser-use task status <id> -c --last 5   # Last 5 steps only
browser-use task status <id> -v --step 10  # Inspect specific step

Live view : browser-use session get <session-id> returns a live URL to watch the agent.

Detect stuck tasks : If cost/duration in task status stops increasing, the task is stuck — stop it and start a new agent.

Logs : browser-use task logs <task-id> — only available after task completes.

Global Options

Session behavior : All commands without --session use the same "default" session. The browser stays open and is reused across commands. Use --session NAME to run multiple browsers in parallel.

Tips

1. Always runbrowser-use state first to see available elements and their indices
2. Use--headed for debugging to see what the browser is doing
3. Sessions persist — the browser stays open between commands
4. Use--json for programmatic parsing
5. Python variables persist across browser-use python commands within a session
6. CLI aliases : bu, browser, and browseruse all work identically to browser-use

Troubleshooting

Run diagnostics first:

browser-use doctor

Browser won't start?

browser-use close --all               # Close all sessions
browser-use --headed open <url>       # Try with visible window

Element not found?

browser-use state                     # Check current elements
browser-use scroll down               # Element might be below fold
browser-use state                     # Check again

Session issues?

browser-use sessions                  # Check active sessions
browser-use close --all               # Clean slate
browser-use open <url>                # Fresh start

Session reuse fails aftertask stop: If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Create a new session instead:

browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "new task" --session-id <new-session-id>

Task stuck at "started" : Check cost with task status — if not increasing, the task is stuck. View live URL with session get, then stop and start a new agent.

Sessions persist after tasks complete : Tasks finishing doesn't auto-stop sessions. Run browser-use session stop --all to clean up.

Cleanup

Always close the browser when done:

browser-use close                     # Close browser session
browser-use session stop --all        # Stop cloud sessions (if any)
browser-use tunnel stop --all         # Stop tunnels (if any)

Weekly Installs

46.3K

Repository

browser-use/browser-use

GitHub Stars

79.9K

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubWarnSocketFailSnykFail

Installed on

claude-code37.3K

cursor34.3K

gemini-cli30.1K

opencode29.6K

codex29.0K

antigravity28.2K