browse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Browse Browser Automation

Browse 浏览器自动化

Control Chrome browser via CLI.

通过CLI控制Chrome浏览器。

CLI Quick Reference

CLI快速参考

bash

browse --help                    # Full help
browse <group>                   # Group help (tab, scroll, page, wait, dialog, emulate, form, perf)
browse --list                    # All 60+ tools
browse --find <term>             # Search tools

bash

browse --help                    # Full help
browse <group>                   # Group help (tab, scroll, page, wait, dialog, emulate, form, perf)
browse --list                    # All 60+ tools
browse --find <term>             # Search tools

Core Workflow

核心工作流

bash

undefined

bash

undefined

1. Open new tab with URL

browse tab.new "https://example.com"

2. Read page to get element refs (currently visible)

browse page.read

3. Click by ref or coordinates

browse click --ref "e1" browse click --x 100 --y 200

4. Type text

browse type --text "hello"

5. Screenshot

browse screenshot --output /tmp/shot.png

undefined

browse screenshot --output /tmp/shot.png

undefined

Navigation

页面导航

bash

undefined

bash

undefined

Open new tab (preferred for new pages)

browse tab.new "https://example.com"

Navigate in current tab (only when tab is already open)

browse navigate "https://other-page.com"


**Use `tab.new`** to open a new page or start a task.
**Use `navigate`** only to change URL in an already open tab.

browse navigate "https://other-page.com"


**使用`tab.new`** 打开新页面或启动任务。
**使用`navigate`** 仅用于在已打开的标签页中更改URL。

Tab Management

标签页管理

bash

browse tab.list
browse tab.new "https://google.com"
browse tab.switch 12345
browse tab.close 12345

bash

browse tab.list
browse tab.new "https://google.com"
browse tab.switch 12345
browse tab.close 12345

Named tabs (aliases)

browse tab.name myapp # Name current tab browse tab.switch myapp # Switch by name browse tab.named # List named tabs

undefined

browse tab.name myapp # Name current tab browse tab.switch myapp # Switch by name browse tab.named # List named tabs

undefined

Window Management

窗口管理

bash

browse window.list                              # List all windows
browse window.new                               # New window
browse window.new --url "https://example.com"   # New window with URL
browse window.new --incognito                   # New incognito window
browse window.focus 12345                       # Focus window by ID
browse window.close 12345                       # Close window
browse window.resize --width 1920 --height 1080 # Resize current window

bash

browse window.list                              # List all windows
browse window.new                               # New window
browse window.new --url "https://example.com"   # New window with URL
browse window.new --incognito                   # New incognito window
browse window.focus 12345                       # Focus window by ID
browse window.close 12345                       # Close window
browse window.resize --width 1920 --height 1080 # Resize current window

Input Methods

输入方式

bash

undefined

bash

undefined

CDP method (real events) - default

browse type --text "hello" browse click --x 100 --y 200

JS method (DOM manipulation) - for contenteditable

browse type --text "hello" --selector "#input" --method js

Keys

browse key Enter browse key "cmd+a" browse key.repeat --key Tab --count 5 # Repeat key presses

undefined

browse key Enter browse key "cmd+a" browse key.repeat --key Tab --count 5 # Repeat key presses

undefined

Page Inspection

页面检查

bash

browse page.read                 # Accessibility tree with refs (viewport only)
browse page.read --ref e5        # Get specific element details
browse page.read --all           # All elements (may hit 50K char limit on large pages)
browse page.text                 # Full page text content (no limit)
browse page.state                # Modals, loading state, scroll info

When to use which:

page.text
- Get full page text content. No size limit. Best for reading/understanding page content.
page.read
- Get element refs for visible viewport. Use when you need to interact (click, type).
page.read --all
- All elements with refs. Can fail on large pages (50K char limit).

Note:

page.read

returns only elements in the visible viewport. Refs remain valid for off-screen elements - you can still

click e5

even after scrolling. Use

scroll.to --ref e5

to bring an element into view.

bash

browse page.read                 # Accessibility tree with refs (viewport only)
browse page.read --ref e5        # Get specific element details
browse page.read --all           # All elements (may hit 50K char limit on large pages)
browse page.text                 # Full page text content (no limit)
browse page.state                # Modals, loading state, scroll info

适用场景对比：

page.text
- 获取完整页面文本内容，无大小限制，最适合读取或理解页面内容。
page.read
- 获取可见视口中的元素引用，用于交互操作（点击、输入）场景。
page.read --all
- 获取所有元素的引用，但在大型页面上可能因50K字符限制而失败。

注意：

page.read

仅返回可见视口中的元素，但引用对屏幕外元素依然有效——即使元素滚出视野，你仍可执行

click e5

操作。可使用

scroll.to --ref e5

将元素滚动到视野内。

Scrolling

页面滚动

bash

browse scroll down               # Scroll down (default amount)
browse scroll up                 # Scroll up
browse scroll down --amount 5    # Scroll down more (1-10)
browse scroll.bottom             # Scroll to bottom of page
browse scroll.top                # Scroll to top of page
browse scroll.to --ref e5        # Scroll element into view
browse scroll.info               # Get scroll position

bash

browse scroll down               # Scroll down (default amount)
browse scroll up                 # Scroll up
browse scroll down --amount 5    # Scroll down more (1-10)
browse scroll.bottom             # Scroll to bottom of page
browse scroll.top                # Scroll to top of page
browse scroll.to --ref e5        # Scroll element into view
browse scroll.info               # Get scroll position

Waiting

等待操作

bash

browse wait 2                    # Wait 2 seconds
browse wait.element ".loaded"    # Wait for element
browse wait.network              # Wait for network idle
browse wait.url "/success"       # Wait for URL pattern
browse wait.dom --stable 100     # Wait for DOM stability
browse wait.load                 # Wait for page load complete

bash

browse wait 2                    # Wait 2 seconds
browse wait.element ".loaded"    # Wait for element
browse wait.network              # Wait for network idle
browse wait.url "/success"       # Wait for URL pattern
browse wait.dom --stable 100     # Wait for DOM stability
browse wait.load                 # Wait for page load complete

Dialog Handling

对话框处理

bash

browse dialog.info               # Get current dialog type/message
browse dialog.accept             # Accept (OK)
browse dialog.accept --text "response"  # Accept prompt with text
browse dialog.dismiss            # Dismiss (Cancel)

bash

browse dialog.info               # Get current dialog type/message
browse dialog.accept             # Accept (OK)
browse dialog.accept --text "response"  # Accept prompt with text
browse dialog.dismiss            # Dismiss (Cancel)

Device/Network Emulation

设备/网络模拟

bash

undefined

bash

undefined

Network throttling

browse emulate.network slow-3g # Presets: slow-3g, fast-3g, 4g, offline browse emulate.network reset # Disable throttling

CPU throttling

browse emulate.cpu 4 # 4x slower browse emulate.cpu 1 # Reset

Device emulation

browse emulate.device "iPhone 14" browse emulate.device --list # List available devices

Geolocation

browse emulate.geo --lat 37.7749 --lon -122.4194 browse emulate.geo --clear

undefined

browse emulate.geo --lat 37.7749 --lon -122.4194 browse emulate.geo --clear

undefined

Form Automation

表单自动化

bash

browse page.read                 # Get element refs first

bash

browse page.read                 # Get element refs first

Fill by ref

browse form.fill --data '[{"ref":"e1","value":"John"},{"ref":"e2","value":"john@example.com"}]'

Checkboxes: true/false

browse form.fill --data '[{"ref":"e7","value":true}]'

undefined

browse form.fill --data '[{"ref":"e7","value":true}]'

undefined

File Upload

文件上传

bash

browse upload --ref e5 --files "/path/to/file.txt"
browse upload --ref e5 --files "/path/file1.txt,/path/file2.txt"

bash

browse upload --ref e5 --files "/path/to/file.txt"
browse upload --ref e5 --files "/path/file1.txt,/path/file2.txt"

Network Inspection

网络检查

bash

browse network                   # List captured requests
browse network --stream          # Real-time network events
browse network.body --id "req-123"  # Get response body
browse network.clear             # Clear captured requests

bash

browse network                   # List captured requests
browse network --stream          # Real-time network events
browse network.body --id "req-123"  # Get response body
browse network.clear             # Clear captured requests

Console

控制台

bash

browse console                   # Get console messages
browse console --stream          # Real-time console
browse console --stream --level error  # Errors only

bash

browse console                   # Get console messages
browse console --stream          # Real-time console
browse console --stream --level error  # Errors only

JavaScript Execution

JavaScript执行

bash

browse js "return document.title"
browse js "document.querySelector('.btn').click()"

bash

browse js "return document.title"
browse js "document.querySelector('.btn').click()"

Iframe Handling

Iframe处理

bash

browse frame.list                # List frames with IDs
browse frame.js --id "FRAME_ID" --code "return document.title"

bash

browse frame.list                # List frames with IDs
browse frame.js --id "FRAME_ID" --code "return document.title"

Performance

性能监控

bash

browse perf.metrics              # Current metrics snapshot
browse perf.start                # Start trace
browse perf.stop                 # Stop and get results

bash

browse perf.metrics              # Current metrics snapshot
browse perf.start                # Start trace
browse perf.stop                 # Stop and get results

Screenshots

截图

bash

browse screenshot                           # To stdout (base64)
browse screenshot --output /tmp/shot.png    # Save to file
browse screenshot --selector ".card"        # Element only
browse screenshot --full-page               # Full page scroll capture

bash

browse screenshot                           # To stdout (base64)
browse screenshot --output /tmp/shot.png    # Save to file
browse screenshot --selector ".card"        # Element only
browse screenshot --full-page               # Full page scroll capture

Cookies & Storage

Cookie与存储

bash

browse cookies                   # List cookies for current page
browse cookies --domain .google.com
browse cookie.set --name "token" --value "abc123"
browse cookie.delete --name "token"

bash

browse cookies                   # List cookies for current page
browse cookies --domain .google.com
browse cookie.set --name "token" --value "abc123"
browse cookie.delete --name "token"

History & Bookmarks

历史记录与书签

bash

browse history --query "github" --max 20
browse bookmarks --query "docs"
browse bookmark.add --url "https://..." --title "My Bookmark"

bash

browse history --query "github" --max 20
browse bookmarks --query "docs"
browse bookmark.add --url "https://..." --title "My Bookmark"

Health Checks & Smoke Tests

健康检查与冒烟测试

bash

browse health --url "http://localhost:3000"
browse smoke --urls "http://localhost:3000" "http://localhost:3000/about"
browse smoke --urls "..." --screenshot /tmp/smoke

bash

browse health --url "http://localhost:3000"
browse smoke --urls "http://localhost:3000" "http://localhost:3000/about"
browse smoke --urls "..." --screenshot /tmp/smoke

Error Diagnostics

错误诊断

bash

undefined

bash

undefined

Auto-capture screenshot + console on failure

browse wait.element ".missing" --auto-capture --timeout 2000

Saves to /tmp/browse-error-*.png

undefined

undefined

Common Options

通用选项

bash

--tab-id <id>         # Target specific tab
--json                # Raw JSON output  
--auto-capture        # Screenshot + console on error
--timeout <ms>        # Override default timeout

bash

--tab-id <id>         # Target specific tab
--json                # Raw JSON output  
--auto-capture        # Screenshot + console on error
--timeout <ms>        # Override default timeout

Tips

使用技巧

First CDP operation is slow (~5-8s) - debugger attachment overhead, subsequent calls fast
Use refs from page.read for reliable element targeting over CSS selectors
JS method for contenteditable - Modern editors (Notion, etc.) need
```
--method js
```
Named tabs for multi-step tasks -
```
tab.name app
```
then
```
tab.switch app
```
Auto-capture for debugging -
```
--auto-capture
```
saves diagnostics on failure

首次CDP操作速度较慢（约5-8秒）- 这是调试器附加的overhead导致，后续调用会显著加快
优先使用page.read返回的refs 定位元素，比CSS选择器更可靠
contenteditable元素使用JS方式 - 现代编辑器（如Notion等）需要添加
```
--method js
```
参数
多步骤任务使用命名标签页 - 先执行
```
tab.name app
```
命名，再用
```
tab.switch app
```
快速切换
调试时启用自动捕获 -
```
--auto-capture
```
参数会在执行失败时自动保存截图和控制台信息，便于诊断