Virtual Browser

主题

CLI 模式 ​

CLI（Command Line Interface）模式允许通过命令行启动 Virtual Browser 的本地 API 服务，获取端口与 api-key，供脚本、CI/CD 或第三方工具无人值守调用。

专业版功能

CLI 模式与 REST API 一样，仅专业版（会员）可用。启动前请确保已登录有效会员账号，或通过参数传入 Token。

适用场景 ​

  • 自动化脚本批量调用 Virtual Browser API
  • CI/CD 或定时任务调度
  • 本地服务化运行，供外部系统接入
  • 快速检查 API 服务是否在运行

使用前准备 ​

  1. 已安装 Virtual Browser（Windows 或 macOS）
  2. 已开通专业版会员
  3. 建议先在图形界面登录一次，或启动时传入 Token

快速开始 ​

启动 CLI 服务（默认后台） ​

Windows：

bash
VirtualBrowser.exe --cli

macOS：

bash
"/Applications/Virtual Browser.app/Contents/MacOS/Virtual Browser" --cli

--cli 默认以后台模式启动。启动后建议使用 --cli-print 查询端口与 api-key。

前台启动（调试） ​

bash
VirtualBrowser.exe --cli --cli-foreground

前台模式占用当前终端，便于查看日志。

JSON 输出 ​

bash
VirtualBrowser.exe --cli --cli-json
VirtualBrowser.exe --cli-print --cli-json

自动化场景建议统一使用 --cli-json，便于解析 port、apiKey、alive 等字段。

使用账号或 Token 登录 ​

bash
# 用户名密码
VirtualBrowser.exe --cli --username=YOUR_USERNAME --password=YOUR_PASSWORD

# 短参数
VirtualBrowser.exe --cli -u YOUR_USERNAME -p YOUR_PASSWORD

# Token
VirtualBrowser.exe --cli --token=YOUR_TOKEN
VirtualBrowser.exe --cli --x-token=YOUR_TOKEN

查询运行状态 ​

bash
VirtualBrowser.exe --cli-print
VirtualBrowser.exe --cli-print --cli-json

参数说明 ​

参数说明
--cli启动 CLI API 服务（默认后台）
--cli-foreground / --foreground前台模式，占用当前终端
--cli-print打印当前 CLI 实例信息
--cli-jsonJSON 格式输出
--username=... / -u ...登录用户名
--password=... / -p ...登录密码
--token=... / --x-token=...登录 Token
--cli-silent / --silent / -q静默输出
--cli-verbose / -v详细输出
--help / -h帮助信息

常见问题 ​

提示「需要会员鉴权」 ​

CLI 仅对专业版开放。请在 GUI 登录会员账号，或通过 --username/--password、--token 传入有效凭证。

提示「已有实例在运行」 ​

Virtual Browser 为单实例应用。若 GUI 或其他 CLI 已在运行，需先关闭，或使用 --cli-print 查看当前实例。

如何判断启动成功？ ​

执行 --cli-print --cli-json，确认返回中包含 port、apiKey，且 alive 为 true。随后将 http://localhost:{port} 与 api-key 用于后续 API 调用。

相关文档 ​