# Browser-Use CLI 命令行工具完整文档

## 概述

`browser-use` 是一个快速、持久化的浏览器自动化命令行工具。它在命令之间保持浏览器会话，支持复杂的多步骤工作流程。

## 快速开始

```bash
browser-use open https://example.com           # 导航到 URL
browser-use state                              # 获取页面元素及其索引
browser-use click 5                            # 通过索引点击元素
browser-use type "Hello World"                 # 输入文本
browser-use screenshot                         # 截图
browser-use close                              # 关闭浏览器
```

## 安装

```bash
# 安装 browser-use 包
uv add browser-use
uv sync

# 安装 Chromium 浏览器
uvx browser-use install
```

## 核心工作流程

1. **导航**: `browser-use open <url>` - 打开 URL（如需要会自动启动浏览器）
2. **检查**: `browser-use state` - 返回可点击元素及其索引
3. **交互**: 使用 state 返回的索引进行交互（`browser-use click 5`, `browser-use input 3 "text"`）
4. **验证**: 使用 `browser-use state` 或 `browser-use screenshot` 确认操作结果
5. **重复**: 浏览器在命令之间保持打开状态

## 浏览器模式

```bash
# 默认：无头 Chromium
browser-use --browser chromium open <url>

# 可见的 Chromium 窗口
browser-use --browser chromium --headed open <url>

# 使用真实的 Chrome（带登录会话）
browser-use --browser real open <url>

# 云端浏览器（需要 API key）
browser-use --browser remote open <url>
```

**模式说明**:
- **chromium**: 快速、隔离、默认无头模式
- **real**: 使用你的 Chrome，包含 cookies、扩展、已登录会话
- **remote**: 云端托管浏览器，支持代理（需要 BROWSER_USE_API_KEY）

## 命令参考

### 1. 导航命令

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use open <url>` | 导航到指定 URL | `browser-use open https://example.com` |
| `browser-use back` | 返回上一页 | `browser-use back` |
| `browser-use scroll down` | 向下滚动 | `browser-use scroll down` |
| `browser-use scroll up` | 向上滚动 | `browser-use scroll up` |
| `browser-use scroll down --amount 1000` | 向下滚动指定像素 | `browser-use scroll down --amount 1000` |

### 2. 页面状态检查

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use state` | 获取 URL、标题和可点击元素 | `browser-use state` |
| `browser-use screenshot` | 截图（输出 base64） | `browser-use screenshot` |
| `browser-use screenshot <path>` | 保存截图到文件 | `browser-use screenshot page.png` |
| `browser-use screenshot --full <path>` | 全页面截图 | `browser-use screenshot --full page.png` |

### 3. 交互命令

**注意**: 使用 `browser-use state` 获取的索引来进行交互

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use click <index>` | 点击指定索引的元素 | `browser-use click 5` |
| `browser-use type "text"` | 在当前焦点元素中输入文本 | `browser-use type "Hello World"` |
| `browser-use input <index> "text"` | 点击元素后输入文本 | `browser-use input 3 "john@example.com"` |
| `browser-use keys "Enter"` | 发送键盘按键 | `browser-use keys "Enter"` |
| `browser-use keys "Control+a"` | 发送组合键 | `browser-use keys "Control+a"` |
| `browser-use select <index> "option"` | 选择下拉选项 | `browser-use select 2 "Option 1"` |

### 4. 标签页管理

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use switch <tab>` | 切换到指定索引的标签页 | `browser-use switch 1` |
| `browser-use close-tab` | 关闭当前标签页 | `browser-use close-tab` |
| `browser-use close-tab <tab>` | 关闭指定索引的标签页 | `browser-use close-tab 2` |

### 5. JavaScript 和数据提取

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use eval "js code"` | 执行 JavaScript 代码并返回结果 | `browser-use eval "document.title"` |
| `browser-use extract "query"` | 使用 LLM 提取数据（需要 API key） | `browser-use extract "all product prices"` |

### 6. Python 执行（持久化会话）

Python 会话在命令之间保持状态。`browser` 对象提供以下方法：

```bash
# 设置变量
browser-use python "x = 42"

# 访问变量
browser-use python "print(x)"  # 输出: 42

# 访问浏览器对象
browser-use python "print(browser.url)"

# 显示已定义的变量
browser-use python --vars

# 清除 Python 命名空间
browser-use python --reset

# 执行 Python 文件
browser-use python --file script.py
```

**browser 对象 API**:
- `browser.url` - 当前页面 URL
- `browser.title` - 页面标题
- `browser.goto(url)` - 导航到 URL
- `browser.click(index)` - 点击元素
- `browser.type(text)` - 输入文本
- `browser.screenshot(path)` - 截图
- `browser.scroll()` - 滚动页面
- `browser.html` - 获取页面 HTML

### 7. AI 代理任务（需要 API Key）

```bash
# 运行 AI 代理完成任务
browser-use run "Fill the contact form with test data"

# 指定最大步数
browser-use run "Extract all product prices" --max-steps 50
```

代理任务使用 LLM 自主完成复杂的浏览器任务。需要配置以下任一 API key：
- `BROWSER_USE_API_KEY`（推荐）
- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
- `GOOGLE_API_KEY`

### 8. 会话管理

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use sessions` | 列出所有活动会话 | `browser-use sessions` |
| `browser-use close` | 关闭当前会话 | `browser-use close` |
| `browser-use close --all` | 关闭所有会话 | `browser-use close --all` |

### 9. 服务器控制

| 命令 | 描述 | 示例 |
|------|------|------|
| `browser-use server status` | 检查服务器是否运行 | `browser-use server status` |
| `browser-use server stop` | 停止服务器 | `browser-use server stop` |
| `browser-use server logs` | 查看服务器日志 | `browser-use server logs` |

## 全局选项

| 选项 | 描述 | 默认值 |
|------|------|--------|
| `--session NAME` | 使用命名会话 | "default" |
| `--browser MODE` | 浏览器模式：chromium, real, remote | chromium |
| `--headed` | 显示浏览器窗口（chromium 模式） | false |
| `--profile NAME` | Chrome 配置文件（仅 real 模式） | - |
| `--json` | 以 JSON 格式输出 | false |
| `--api-key KEY` | 覆盖 API key | - |

**会话行为**: 所有不带 `--session` 的命令使用同一个 "default" 会话。浏览器在命令之间保持打开并被重用。使用 `--session NAME` 可以并行运行多个浏览器。

## 实用示例

### 示例 1: 表单提交

```bash
# 打开表单页面
browser-use open https://example.com/contact

# 查看页面元素
browser-use state
# 输出: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"

# 填写表单
browser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use input 2 "Hello, this is a test message."

# 提交表单
browser-use click 3

# 验证结果
browser-use state
```

### 示例 2: 数据提取（使用 JavaScript）

```bash
# 打开页面
browser-use open https://news.ycombinator.com

# 使用 JavaScript 提取数据
browser-use eval "Array.from(document.querySelectorAll('.titleline a')).slice(0,5).map(a => a.textContent)"
```

### 示例 3: 多会话工作流

```bash
# 启动工作会话
browser-use --session work open https://work.example.com

# 启动个人会话
browser-use --session personal open https://personal.example.com

# 检查工作会话
browser-use --session work state

# 检查个人会话
browser-use --session personal state

# 关闭所有会话
browser-use close --all
```

### 示例 4: Python 自动化

```bash
# 打开页面
browser-use open https://example.com/products

# 使用 Python 进行复杂操作
browser-use python "
products = []
for i in range(20):
    browser.scroll('down')
    browser.wait(0.5)
browser.screenshot('products.png')
"

# 输出结果
browser-use python "print(f'Captured {len(products)} products')"
```

### 示例 5: 使用真实浏览器（已登录会话）

```bash
# 使用你的 Chrome 浏览器（保留登录状态）
browser-use --browser real open https://gmail.com

# 已经登录！
browser-use state
```

### 示例 6: 可见浏览器调试

```bash
# 使用可见窗口进行调试
browser-use --headed open https://example.com

# 查看浏览器操作
browser-use click 5
browser-use type "test"
```

## 最佳实践

1. **始终先运行 `browser-use state`** 查看可用元素及其索引
2. **使用 `--headed` 进行调试** 可以看到浏览器的实际操作
3. **会话持久化** - 浏览器在命令之间保持打开状态
4. **使用 `--json` 进行程序化解析** 输出结果
5. **Python 变量持久化** - 在同一会话中，`browser-use python` 命令之间变量保持
6. **真实浏览器模式** 保留你的登录会话和扩展

## 故障排除

### 浏览器无法启动？

```bash
# 停止卡住的服务器
browser-use server stop

# 尝试使用可见窗口
browser-use --headed open <url>
```

### 找不到元素？

```bash
# 检查当前元素
browser-use state

# 元素可能在下方
browser-use scroll down

# 再次检查
browser-use state
```

### 会话问题？

```bash
# 检查活动会话
browser-use sessions

# 清理所有会话
browser-use close --all

# 重新开始
browser-use open <url>
```

## 工作原理

CLI 使用会话服务器架构：

1. 第一个命令启动后台服务器（浏览器保持打开）
2. 后续命令通过 Unix socket 通信（Windows 使用 TCP）
3. 浏览器在命令之间持久化，实现快速交互
4. 服务器按需自动启动，使用 `browser-use server stop` 停止

这使得命令延迟约为 50ms，而不是每次都等待浏览器启动。

## 清理

**完成后始终关闭浏览器**。完成浏览器自动化后运行：

```bash
browser-use close
```

## 命令别名

以下命令是等效的：

```bash
browser-use <command>
browseruse <command>
bu <command>
browser <command>
```

## API Key 配置

在 `.env` 文件中配置 API key：

```bash
# Browser-Use Cloud API（推荐）
BROWSER_USE_API_KEY=your-key

# 或使用其他 LLM 提供商
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_API_KEY=your-google-key
```

新用户注册 [Browser Use Cloud](https://cloud.browser-use.com/new-api-key) 可获得 $10 免费额度。

## 高级功能

### 使用代理（云端浏览器）

```bash
# 使用云端浏览器（自动支持代理和隐身模式）
browser-use --browser remote open https://example.com
```

### 自定义 Chrome 配置文件

```bash
# 使用特定的 Chrome 配置文件
browser-use --browser real --profile "Profile 1" open https://example.com
```

### JSON 输出用于脚本

```bash
# 获取 JSON 格式的输出
browser-use --json state

# 在脚本中解析
STATE=$(browser-use --json state)
echo $STATE | jq '.data.url'
```

## 测试验证

### 基本任务验证清单

- [ ] 导航到 URL
- [ ] 获取页面状态
- [ ] 点击元素
- [ ] 输入文本
- [ ] 提交表单
- [ ] 截图
- [ ] 滚动页面
- [ ] 执行 JavaScript
- [ ] 管理标签页
- [ ] 使用 Python 会话
- [ ] 关闭浏览器

### 测试脚本示例

```bash
#!/bin/bash

# 测试基本功能
echo "测试 1: 打开页面"
browser-use open https://example.com

echo "测试 2: 获取状态"
browser-use state

echo "测试 3: 截图"
browser-use screenshot test.png

echo "测试 4: 执行 JavaScript"
browser-use eval "document.title"

echo "测试 5: Python 会话"
browser-use python "print('Hello from Python')"

echo "测试 6: 关闭浏览器"
browser-use close

echo "所有测试完成！"
```

## 参考资源

- [官方文档](https://docs.browser-use.com)
- [GitHub 仓库](https://github.com/browser-use/browser-use)
- [示例代码](https://github.com/browser-use/browser-use/tree/main/examples)
- [Browser Use Cloud](https://cloud.browser-use.com)

---

**文档版本**: 基于 browser-use v0.11.5
**最后更新**: 2026-01-29