webcli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

webcli — Headless Browser CLI

webcli — 无头浏览器CLI

You have access to a headless browser via the

webcli

command. Use it to navigate websites, read content, interact with elements, and take screenshots.

你可以通过

webcli

命令访问无头浏览器，用它来导航网站、读取内容、与元素交互以及截取屏幕截图。

Prerequisites

前提条件

bash

npm install -g @erdinccurebal/webcli
npx playwright install chromium

Homepage: https://erdinccurebal.github.io/webcli/ Repository: https://github.com/erdinccurebal/webcli

bash

npm install -g @erdinccurebal/webcli
npx playwright install chromium

主页: https://erdinccurebal.github.io/webcli/ 代码仓库: https://github.com/erdinccurebal/webcli

Commands Reference

命令参考

Navigation

webcli go <url>                    # Navigate to URL (auto-starts daemon)
webcli go <url> -w networkidle     # Wait for network to settle
webcli go <url> -t mytab           # Open in named tab
webcli back                        # Go back in history
webcli forward                     # Go forward
webcli reload                      # Reload current page

bash

webcli go <url>                    # 导航至指定URL（自动启动守护进程）
webcli go <url> -w networkidle     # 等待网络稳定
webcli go <url> -t mytab           # 在指定名称的标签页中打开
webcli back                        # 后退
webcli forward                     # 前进
webcli reload                      # 重新加载当前页面

Reading Page Content

读取页面内容

bash

webcli source                      # Get full visible text of the page
webcli links                       # List all links (text + href)
webcli forms                       # List all forms with their inputs
webcli html <selector>             # Get innerHTML of element
webcli attr <selector> <attribute> # Get element attribute value

bash

webcli source                      # 获取页面的全部可见文本
webcli links                       # 列出所有链接（文本+链接地址）
webcli forms                       # 列出所有表单及其输入字段
webcli html <selector>             # 获取元素的innerHTML
webcli attr <selector> <attribute> # 获取元素的属性值

Interaction

交互操作

bash

webcli click "<visible text>"      # Click element by visible text
webcli clicksel "<css selector>"   # Click element by CSS selector
webcli fill "<selector>" "<value>" # Fill an input field (preferred for forms)
webcli type "<text>"               # Type with keyboard (for focused element)
webcli select "<selector>" "<val>" # Select dropdown option
webcli press Enter                 # Press keyboard key (Enter, Tab, Escape...)
webcli focus "<selector>"          # Focus an element

bash

webcli click "<visible text>"      # 通过可见文本点击元素
webcli clicksel "<css selector>"   # 通过CSS选择器点击元素
webcli fill "<selector>" "<value>" # 填充输入字段（表单优先使用此命令）
webcli type "<text>"               # 模拟键盘输入（针对已聚焦的元素）
webcli select "<selector>" "<val>" # 选择下拉选项
webcli press Enter                 # 按下键盘按键（Enter、Tab、Escape等）
webcli focus "<selector>"          # 聚焦到指定元素

Waiting

等待操作

bash

webcli wait "<selector>"           # Wait for CSS selector to be visible
webcli waitfor "<text>"            # Wait for text to appear on page
webcli sleep 2000                  # Sleep for N milliseconds

bash

webcli wait "<selector>"           # 等待CSS选择器对应的元素可见
webcli waitfor "<text>"            # 等待文本出现在页面上
webcli sleep 2000                  # 休眠N毫秒

Screenshots

屏幕截图

bash

webcli screenshot                  # Take screenshot (returns path)
webcli screenshot -o page.png      # Save to specific file

bash

webcli screenshot                  # 截取屏幕截图（返回文件路径）
webcli screenshot -o page.png      # 保存到指定文件

Browser Settings

浏览器设置

bash

webcli viewport 1920 1080          # Change viewport size
webcli useragent "<string>"        # Change user agent

bash

webcli viewport 1920 1080          # 修改视口尺寸
webcli useragent "<string>"        # 修改用户代理

Tab & Daemon Management

标签页与守护进程管理

bash

webcli tabs                        # List open tabs
webcli quit                        # Close current tab
webcli quit -t mytab               # Close specific tab
webcli status                      # Show daemon info (PID, uptime, tabs)
webcli stop                        # Stop daemon and close browser

bash

webcli tabs                        # 列出所有打开的标签页
webcli quit                        # 关闭当前标签页
webcli quit -t mytab               # 关闭指定名称的标签页
webcli status                      # 显示守护进程信息（PID、运行时间、标签页）
webcli stop                        # 停止守护进程并关闭浏览器

Global Options

全局选项

All commands support:

```
-t, --tab <name>
```
— target a specific tab (default: "default")
```
--json
```
— output as structured JSON
```
--timeout <ms>
```
— command timeout (default: 30000)

所有命令均支持：

```
-t, --tab <name>
```
— 目标指定标签页（默认值："default"）
```
--json
```
— 以结构化JSON格式输出
```
--timeout <ms>
```
— 命令超时时间（默认值：30000）

Best Practices

最佳实践

General workflow

通用工作流

```
webcli go <url>
```
to navigate
```
webcli source
```
to read the page content
Use
```
webcli click
```
,
```
webcli fill
```
,
```
webcli press
```
to interact
```
webcli source
```
again to see the result
```
webcli screenshot
```
if user wants visual confirmation

使用
```
webcli go <url>
```
导航至目标页面
使用
```
webcli source
```
读取页面内容
使用
```
webcli click
```
、
```
webcli fill
```
、
```
webcli press
```
进行交互操作
再次使用
```
webcli source
```
查看操作结果
如果用户需要视觉确认，使用
```
webcli screenshot
```

Form filling

表单填充

Always use
```
webcli fill
```
for input fields — it properly sets React/Vue controlled inputs
Use
```
webcli click
```
or
```
webcli clicksel
```
for buttons
Use
```
webcli press Enter
```
to submit forms
After submitting, use
```
webcli sleep 1000
```
then
```
webcli source
```
to check the result

始终使用
```
webcli fill
```
填充输入字段——它能正确设置React/Vue的受控输入框
使用
```
webcli click
```
或
```
webcli clicksel
```
点击按钮
使用
```
webcli press Enter
```
提交表单
提交后，使用
```
webcli sleep 1000
```
然后
```
webcli source
```
检查结果

Multi-tab browsing

多标签页浏览

bash

webcli go https://site-a.com -t research
webcli go https://site-b.com -t reference
webcli source -t research          # Read from specific tab
webcli source -t reference

bash

webcli go https://site-a.com -t research
webcli go https://site-b.com -t reference
webcli source -t research          # 读取指定标签页的内容
webcli source -t reference

Error recovery

错误恢复

If a command times out, try
```
webcli sleep 2000
```
then retry
If an element is not found, use
```
webcli source
```
to check what's on the page
If the daemon seems stuck, use
```
webcli stop
```
then retry the command
Use
```
webcli wait "<selector>"
```
before interacting with dynamically loaded content

如果命令超时，尝试先执行
```
webcli sleep 2000
```
再重试
如果未找到元素，使用
```
webcli source
```
检查页面上的内容
如果守护进程似乎卡住，使用
```
webcli stop
```
然后重新执行命令
与动态加载的内容交互前，使用
```
webcli wait "<selector>"
```
等待元素加载完成

Important Notes

重要说明

Always read the page with
```
webcli source
```
before trying to interact — understand what's on the page first
Prefer
```
webcli fill
```
over
```
webcli type
```
for form inputs
Prefer
```
webcli click
```
(by text) over
```
webcli clicksel
```
(by selector) when possible — it's more robust
Use
```
webcli sleep
```
between rapid interactions to let pages update
The daemon persists between commands — no need to re-navigate unless the page changes

在尝试交互前，务必先用
```
webcli source
```
读取页面内容——先了解页面上的元素
填充表单输入框时优先使用
```
webcli fill
```
而非
```
webcli type
```
可能的话，优先使用
```
webcli click
```
（通过文本）而非
```
webcli clicksel
```
（通过选择器）——它的鲁棒性更强
在快速交互之间使用
```
webcli sleep
```
，让页面有时间更新
守护进程会在命令之间保持运行——除非页面发生变化，否则无需重新导航