webcli — Headless Browser CLI
You have access to a headless browser via the webcli command. Use it to navigate websites, read content, interact with elements, take screenshots, and get accessibility snapshots.
Prerequisites
CODEBLOCK0
Homepage: https://webcli.erdinc.curebal.dev/
Repository: https://github.com/erdinccurebal/webcli
Commands Reference
Navigation
CODEBLOCK1
Reading Page Content
CODEBLOCK2
Accessibility Snapshot (Recommended for AI agents)
CODEBLOCK3
The snapshot assigns deterministic refs to interactive elements. Use these refs in other commands:
CODEBLOCK4
Interaction
CODEBLOCK5
Waiting
CODEBLOCK6
Screenshots & PDF
CODEBLOCK7
Console & Errors
CODEBLOCK8
Dialog Handling
CODEBLOCK9
Frame (iframe) Switching
CODEBLOCK10
Storage (localStorage)
CODEBLOCK11
State Management
CODEBLOCK12
Browser Settings
CODEBLOCK13
Cookie Management
CODEBLOCK14
Tab & Daemon Management
CODEBLOCK15
Global Options
All commands support:
- -
-t, --tab <name> — target a specific tab (default: "default") - INLINECODE2 — output as structured JSON
- INLINECODE3 — command timeout (default: 30000)
Best Practices
Recommended workflow for AI agents
- 1.
webcli go <url> to navigate - INLINECODE5 to get accessibility tree with refs
- Use refs for interaction:
webcli click @e1, INLINECODE7 - INLINECODE8 again to see updated state
- INLINECODE9 if user wants visual confirmation
Alternative workflow (text-based)
- 1.
webcli go <url> to navigate - INLINECODE11 to read the page content
- Use
webcli click, webcli fill, webcli press to interact - INLINECODE15 again to see the result
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
Multi-tab browsing
CODEBLOCK16
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
Important Notes
- - Always read the page with
webcli source or webcli snapshot before trying to interact - Prefer
webcli snapshot + refs for the most reliable element targeting - Prefer
webcli fill over webcli type for form inputs - Prefer
webcli click (by text) over webcli clicksel (by selector) when possible - 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 — 无头浏览器命令行工具
您可以通过 webcli 命令访问无头浏览器。使用它来浏览网站、阅读内容、与元素交互、截取屏幕截图以及获取无障碍快照。
前置条件
bash
npm install -g @erdinccurebal/webcli
npx playwright install chromium
主页：https://webcli.erdinc.curebal.dev/
仓库：https://github.com/erdinccurebal/webcli
命令参考
导航
bash
webcli go
# 导航到URL（自动启动守护进程）
webcli go -w networkidle # 等待网络稳定
webcli go -t mytab # 在命名标签页中打开
webcli back # 返回上一页
webcli forward # 前进到下一页
webcli reload # 重新加载当前页面
读取页面内容
bash
webcli source # 获取页面完整可见文本
webcli links # 列出所有链接（文本 + 链接地址）
webcli forms # 列出所有表单及其输入项
webcli html <选择器> # 获取元素的innerHTML
webcli attr <选择器> <属性> # 获取元素属性值
webcli eval # 执行JavaScript并返回结果
webcli title # 获取页面标题
webcli url # 获取当前URL
webcli value <选择器> # 获取输入框/文本域的值
webcli count <选择器> # 统计匹配元素的数量
webcli box <选择器> # 获取边界框（x, y, w, h）
webcli styles <选择器> [属性..] # 获取计算后的CSS样式
webcli visible <选择器> # 检查元素是否可见
webcli enabled <选择器> # 检查元素是否启用
webcli checked <选择器> # 检查复选框是否被选中
无障碍快照（推荐AI代理使用）
bash
webcli snapshot # 获取带引用的无障碍树（@e1, @e2...）
webcli snapshot --all # 包含非交互元素
webcli snapshot --max-depth 5 # 限制树深度
快照会为交互元素分配确定性引用。在其他命令中使用这些引用：
bash
webcli snapshot # 获取树：[按钮 @e1] 提交，[文本框 @e2] 邮箱
webcli fill @e2 user@example.com # 使用引用填充
webcli click @e1 # 使用引用点击
交互
bash
webcli click <可见文本> # 通过可见文本点击元素
webcli click @e1 # 通过快照引用点击元素
webcli clicksel # 通过CSS选择器点击元素
webcli dblclick <文本> # 通过可见文本双击元素
webcli hover <选择器> # 悬停在元素上
webcli fill <选择器> <值> # 填充输入字段（推荐用于表单）
webcli type <文本> # 使用键盘输入（针对已聚焦元素）
webcli select <选择器> <值> # 选择下拉选项
webcli press Enter # 按下键盘键（Enter, Tab, Escape...）
webcli focus <选择器> # 聚焦元素
webcli check <选择器> # 选中复选框
webcli uncheck <选择器> # 取消选中复选框
webcli drag <起始> <目标> # 在选择器之间拖放
webcli upload <选择器> <文件> # 上传文件到input[type=file]
webcli scroll down 500 # 滚动页面（上/下/左/右，像素）
等待
bash
webcli wait <选择器> # 等待CSS选择器可见
webcli waitfor <文本> # 等待文本出现在页面上
webcli sleep 2000 # 休眠N毫秒
截图与PDF
bash
webcli screenshot # 截取全页截图（返回路径）
webcli screenshot -o page.png # 保存到指定文件
webcli screenshot --no-full # 仅视口截图
webcli screenshot --annotate # 带编号交互元素的截图
webcli pdf # 将页面保存为PDF
webcli pdf -o page.pdf # 将PDF保存到指定文件
控制台与错误
bash
webcli console on # 开始捕获控制台消息
webcli console off # 停止捕获
webcli console # 显示捕获的控制台消息
webcli errors # 显示页面错误
对话框处理
bash
webcli dialog accept # 接受警告/确认对话框
webcli dialog accept 输入文本 # 接受带文本的提示对话框
webcli dialog dismiss # 关闭对话框
框架（iframe）切换
bash
webcli frame <选择器> # 切换到iframe
webcli frame main # 切换回主框架
存储（localStorage）
bash
webcli storage get # 获取所有localStorage
webcli storage get mykey # 获取指定键
webcli storage set mykey myvalue # 设置值
webcli storage clear # 清除所有localStorage
状态管理
bash
webcli state save session.json # 保存cookies + localStorage + sessionStorage
webcli state load session.json # 恢复完整浏览器状态
浏览器设置
bash
webcli viewport 1920 1080 # 更改视口大小
webcli useragent <字符串> # 更改用户代理
webcli device iPhone 14 # 模拟设备（视口 + UA）
webcli network on # 开始记录网络请求
webcli network off # 停止记录
webcli network # 显示网络日志
Cookie管理
bash
webcli cookie export # 导出cookies为JSON
webcli cookie import <文件> # 从JSON文件导入cookies
标签页与守护进程管理
bash
webcli tabs # 列出打开的标签页
webcli quit # 关闭当前标签页
webcli quit -t mytab # 关闭指定标签页
webcli status # 显示守护进程信息（PID，运行时间，标签页）
webcli stop # 停止守护进程并关闭浏览器
全局选项
所有命令支持：
- - -t, --tab <名称> — 指定目标标签页（默认：default）
- --json — 输出为结构化JSON
- --timeout <毫秒> — 命令超时时间（默认：30000）
最佳实践
AI代理推荐工作流程
- 1. webcli go 导航
- webcli snapshot 获取带引用的无障碍树
- 使用引用进行交互：webcli click @e1，webcli fill @e2 值
- 再次使用 webcli snapshot 查看更新后的状态
- 如果用户需要视觉确认，使用 webcli screenshot
替代工作流程（基于文本）
- 1. webcli go 导航
- webcli source 读取页面内容
- 使用 webcli click、webcli fill、webcli press 进行交互
- 再次使用 webcli source 查看结果
表单填写
- - 始终使用 webcli fill 填写输入字段——它能正确设置React/Vue受控输入
- 按钮使用 webcli click 或 webcli clicksel
- 使用 webcli press Enter 提交表单
- 提交后，使用 webcli sleep 1000 然后 webcli source 检查结果
多标签页浏览
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
错误恢复
- - 如果命令超时，尝试 webcli sleep 2000 然后重试
- 如果找不到元素，使用 webcli source 检查页面上有什么
- 如果守护进程似乎卡住，使用 webcli stop 然后重试命令
- 在与动态加载内容交互前，使用 webcli wait <选择器>
重要说明
- - 在尝试交互之前，始终使用 webcli source 或 webcli snapshot 读取页面
- 优先使用 webcli snapshot + 引用以获得最可靠的目标元素定位
- 表单输入优先使用 webcli fill 而非 webcli type
- 尽可能优先使用 webcli click
