TgeBrowser CLI 命令行工具

从 v1.5.5 版本开始支持 CLI 命令行工具。

tgebrowser 是随 TgeBrowser 客户端分发的独立命令行工具，用于通过命令行调用 TgeBrowser 客户端的 Local API。

它不会启动 TgeBrowser 客户端，也不依赖 Node.js。使用前需要先启动 TgeBrowser 客户端、完成登录，并在客户端中开启 Local API。

适用对象

本文档适合需要通过命令行完成以下操作的用户：

打开、关闭或查询浏览器环境。
查询或管理环境、分组、代理。
在 Linux 服务器或自动化环境中配合无头 TgeBrowser 客户端使用 CLI。

下载与安装

通过 npm 安装（推荐）

bash

npm install -g @tgebrowser/cli

安装后即可在任意目录使用 tgebrowser 命令。

环境要求

Node.js >= 18

快速开始

确认 TgeBrowser 客户端已经启动并开启 Local API 后，可以直接在命令行中执行。

bash

# 查询客户端版本
tgebrowser client-version

# 打开环境
tgebrowser start-browser envId=1

# 关闭环境
tgebrowser stop-browser envId=1

# 查询环境列表
tgebrowser env-list

如果客户端开启了「本地 API 安全认证」，需要传入客户端里配置的 API Key：

bash

tgebrowser --local-api-key "你的API Key" start-browser envId=1

查看帮助：

bash

tgebrowser --help
tgebrowser help start-browser
tgebrowser start-browser --help

常用命令速查

场景	命令示例
查询客户端版本	`tgebrowser client-version`
打开环境	`tgebrowser start-browser envId=1`
关闭环境	`tgebrowser stop-browser envId=1`
查询环境列表	`tgebrowser env-list`
查询运行环境	`tgebrowser env-open-list`
创建环境	`tgebrowser env-create --json '{"browserName":"test","fingerprint":{"os":"Windows"}}'`
删除环境	`tgebrowser env-delete envId=1`
查看帮助	`tgebrowser --help`

使用前提

TgeBrowser 图形客户端必须已经启动。
当前账号必须已登录。
客户端里的 Local API 必须已开启。
如果开启了本地 API 安全认证，使用 CLI 时必须传入 API Key 参数（使用 --local-api-key 选项或设置 TGEBROWSER_API_KEY 环境变量）。
Local API 默认地址是 http://127.0.0.1:50326。如果客户端使用了其它端口，可以用 -p 手动指定。

全局选项

全局选项需要放在子命令前面，例如：

bash

tgebrowser --local-api-key "你的API Key" start-browser envId=1

-p, --port `<n>`             Local API 端口
-H, --host `<h>`             主机，默认 127.0.0.1
    --local-api-key `<key>`  Local API 安全认证密钥
    --timeout `<seconds>`    HTTP 请求超时秒数，默认 30 秒，0 表示不限制
-j, --json `<json>`          整段 JSON 请求体，覆盖 key=value
    --json-stdin           从标准输入读取 JSON 请求体
-h, --help                 显示帮助
-V, --version              显示版本

等价环境变量

环境变量	说明
`TGEBROWSER_PORT`	等价 `-p`
`TGEBROWSER_API_KEY`	等价 `--local-api-key`
`TGEBROWSER_TIMEOUT`	等价 `--timeout`

超时控制

默认情况下，HTTP 请求最多等待 30 秒。如果希望调整等待时间，可以使用 --timeout：

bash

tgebrowser --timeout 60 browser-status
TGEBROWSER_TIMEOUT=60 tgebrowser browser-status

--timeout 的单位是秒。未传时默认 30 秒；传入 0 表示不限制 HTTP 请求等待时间。

请求体写法

CLI 支持三种请求体写法：简单参数推荐使用 key=value，复杂参数推荐使用 --json 或 --json-stdin。

key=value

CLI 会把子命令后的 key=value 转成 JSON 请求体：

bash

tgebrowser start-browser envId=1 isHeadless=true

转换规则：

输入	JSON 类型
`true` / `false`	boolean
`null`	null
`100` / `1.5`	number
`{...}` / `[...]`	object / array
其它	string

--json

复杂请求体建议直接使用 --json：

bash

tgebrowser env-create --json '{
  "browserName": "店铺环境-01",
  "fingerprint": {
    "os": "Windows",
    "kernel": "135",
    "canvas": true,
    "webrtc": "replace"
  },
  "proxy": {
    "protocol": "socks5",
    "host": "127.0.0.1",
    "port": 1080
  }
}'

--json-stdin

也可以从标准输入读取 JSON：

bash

echo '{"envId":1}' | tgebrowser start-browser --json-stdin

客户端信息命令

`client-version`

获取当前 TgeBrowser 客户端版本号。该命令优先读取本地 package.json，若不可用则调用 API 状态接口。

bash

tgebrowser client-version

成功时返回：

json

{
  "code": 0,
  "msg": "Success",
  "data": {
    "name": "TgeBrowser",
    "version": "1.5.4",
    "rendererVersion": "1.6.6"
  }
}

子命令

tgebrowser 的每个子命令都对应一个 Local API 接口。命令名由 API 路径去掉 /api/ 后将 / 替换为 - 得到，例如 /api/browser/list 对应 env-list。

下面按功能分组列出当前 CLI 支持的子命令。

1. 浏览器环境管理

`env-list`

查询环境列表（分页）。

参数	类型	必填	说明
`current`	int	否	当前页，默认 1
`pageSize`	int	否	每页条数，默认 10
`groupId`	int	否	分组 ID
`keyword`	string	否	搜索关键词

bash

tgebrowser env-list
tgebrowser env-list current=1 pageSize=20
tgebrowser env-list keyword="测试"

`env-open-list`

查询当前正在运行的浏览器环境，无需参数。

bash

tgebrowser env-open-list

`env-create`

创建一个新的浏览器环境。

参数	类型	必填	说明
`browserName`	string	是	环境名称
`fingerprint`	object	是	指纹配置
`proxy`	object	否	代理配置
`proxyId`	int	否	已有代理 ID
`groupId`	int	否	分组 ID
`remark`	string	否	备注
`Cookie`	string	否	Cookie 字符串
`startInfo`	object	否	启动配置
`accountInfo`	array	否	账号信息

bash

# 简单创建
tgebrowser env-create browserName="测试环境" fingerprint.os=Windows

# 完整创建（推荐使用 --json）
tgebrowser env-create --json '{
  "browserName": "店铺环境-01",
  "fingerprint": {
    "os": "Windows",
    "kernel": "135",
    "canvas": true,
    "audioContext": true,
    "speechVoices": true,
    "clientRects": true,
    "resolution": "1920x1080",
    "ram": 8,
    "cpu": 4,
    "language": "en-US",
    "timezone": "Europe/Amsterdam",
    "webrtc": "replace"
  },
  "proxy": {
    "protocol": "socks5",
    "host": "127.0.0.1",
    "port": 1080,
    "username": "user",
    "password": "pass"
  },
  "remark": "Facebook营销环境"
}'

`env-update`

更新已有环境配置。需要指定 envId 或 userIndex。

bash

tgebrowser env-update envId=1 browserName="修改后的名称"

`env-delete`

删除单个环境。

bash

tgebrowser env-delete envId=1

`env-delete-batch`

批量删除多个环境。

bash

tgebrowser env-delete-batch --json '{"envIds": [1, 2, 3]}'

`update-cookie`

更新指定环境的 Cookie。

bash

tgebrowser update-cookie envId=1 cookie="[{\"domain\":\".example.com\",\"name\":\"sid\",\"value\":\"abc\"}]"

`batch-update`

批量更新多个环境的某个字段。

bash

tgebrowser batch-update --json '{"envIds":[1,2,3],"field":"remark","value":"批量备注"}'

`mobile-devices`

查询可用的移动设备列表。

bash

tgebrowser mobile-devices
tgebrowser mobile-devices os=Android

2. 浏览器控制

`start-browser`

启动/打开一个浏览器环境。

参数	类型	必填	说明
`envId`	int	是	环境 ID
`args`	字符串数组	否	额外启动参数
`port`	int	否	自定义远程调试端口
`proxy`	object	否	启动时临时覆盖代理

bash

tgebrowser start-browser envId=1

# 带额外参数
tgebrowser start-browser --json '{
  "envId": 1,
  "args": ["--headless=new", "--disable-gpu"]
}'

`stop-browser`

关闭一个正在运行的浏览器环境。

bash

tgebrowser stop-browser envId=1

`stop-all-browsers`

关闭所有正在运行的浏览器环境，无需参数。

bash

tgebrowser stop-all-browsers

3. 缓存管理

`clear-cache`

清除指定环境的本地缓存。

bash

tgebrowser clear-cache envId=1

`clear-cache-batch`

批量清除多个环境的本地缓存。

bash

tgebrowser clear-cache-batch --json '{"envIds": [1, 2, 3]}'

4. 分组管理

`group-list`

查询分组列表（分页）。

bash

tgebrowser group-list
tgebrowser group-list current=1 pageSize=50

`group-create`

创建新分组。

bash

tgebrowser group-create name="新分组"

`group-update`

更新分组信息，需要指定分组 ID。

bash

tgebrowser group-update id=1 name="修改后的分组名"

`group-delete`

删除分组，需要指定分组 ID。

bash

tgebrowser group-delete id=1

5. 代理管理

`proxy-list`

查询代理列表（分页）。

bash

tgebrowser proxy-list
tgebrowser proxy-list current=1 pageSize=20

`proxy-create`

创建新代理。

bash

tgebrowser proxy-create --json '{
  "name": "Socks5代理",
  "protocol": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "username": "user",
  "password": "pass"
}'

`proxy-update`

更新代理信息，需要指定代理 ID。

bash

tgebrowser proxy-update id=1 host="new-host.com" port=1081

`proxy-delete`

删除代理，需要指定代理 ID。

bash

tgebrowser proxy-delete id=1

`proxy-options`

查询 IP 检测渠道选项。

bash

tgebrowser proxy-options

`proxy-detect`

测试代理连通性并获取出口 IP 信息。

bash

tgebrowser proxy-detect --json '{
  "protocol": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "username": "user",
  "password": "pass"
}'

`proxy-detect-quick`

快速测试代理连通性（不查询 IP 信息）。

bash

tgebrowser proxy-detect-quick --json '{
  "protocol": "socks5",
  "host": "127.0.0.1",
  "port": 1080
}'

6. User-Agent 工具

`ua-generate`

批量生成 User-Agent 字符串。

参数	类型	必填	说明
`platform`	string	否	`android` / `ios` / `mixed`（默认 mixed）
`count`	int	否	数量，1-100，默认 1
`androidVersion`	string	否	Android 版本，如 `14`
`iosVersion`	string	否	iOS 版本，如 `18`
`chromeVersion`	int	否	Chrome 主版本号，100-150
`type`	string	否	`wechat` / `chrome` / `safari`（默认 wechat）

bash

tgebrowser ua-generate platform=android count=5 type=chrome

`ua-random`

生成单个随机 UA。

bash

tgebrowser ua-random platform=android type=chrome

7. 窗口管理

`window-sort`

自动排列所有打开的浏览器窗口（基于屏幕大小）。

bash

tgebrowser window-sort

`window-sort-custom`

自定义排列浏览器窗口。

参数	类型	必填	说明
`type`	string	是	`box`（网格）/ `diagonal`（错层）
`width`	number	是	窗口宽度
`height`	number	是	窗口高度
`col`	int	是	每行窗口数
`startX`	number	是	起始 X 坐标
`startY`	number	是	起始 Y 坐标
`spaceX`	number	是	水平间距
`spaceY`	number	是	垂直间距
`offsetX`	number	是	X 偏移
`offsetY`	number	是	Y 偏移

bash

tgebrowser window-sort-custom --json '{
  "type": "box",
  "width": 600,
  "height": 500,
  "col": 3,
  "startX": 10,
  "startY": 10,
  "spaceX": 20,
  "spaceY": 20,
  "offsetX": 0,
  "offsetY": 0
}'

`window-hide`

隐藏 TgeBrowser 主窗口和系统托盘图标。

bash

tgebrowser window-hide

`window-show`

显示 TgeBrowser 主窗口和系统托盘图标。

bash

tgebrowser window-show

常见问题

CLI 连接失败

确认 TgeBrowser 客户端已经启动。
确认客户端中已开启 Local API。
如果使用了自定义端口，通过 -p 参数指定正确端口。
如果开启了 API Key 认证，通过 --local-api-key 传入正确密钥。

如何在 Linux 服务器上使用？

TgeBrowser 支持 Linux AppImage 无头模式启动，启动后可使用 tgebrowser 调用 Local API：

bash

./TgeBrowser.AppImage \
  --no-sandbox \
  --headless=true \
  --app-id="你的 app_id" \
  --app-secret="你的 app_secret" \
  --login-group-code=你的团队code

无头模式不会展示登录页和主界面，但仍会启动本地服务并提供 Local API。

超时了怎么办？

默认超时 30 秒。对于耗时操作（如创建环境、启动浏览器），可以增加超时时间：

bash

tgebrowser --timeout 120 start-browser envId=1

超时只表示 CLI 停止等待 HTTP 响应，不代表客户端内部操作已取消。建议随后通过状态查询确认最终结果。

TgeBrowser CLI 命令行工具 ​

适用对象 ​

下载与安装 ​

通过 npm 安装（推荐） ​

环境要求 ​

快速开始 ​

常用命令速查 ​

使用前提 ​

全局选项 ​

等价环境变量 ​

超时控制 ​

请求体写法 ​

key=value ​

--json ​

--json-stdin ​

客户端信息命令 ​

client-version ​

子命令 ​

1. 浏览器环境管理 ​

env-list ​

env-open-list ​

env-create ​

env-update ​

env-delete ​

env-delete-batch ​

update-cookie ​

batch-update ​

mobile-devices ​

2. 浏览器控制 ​

start-browser ​

stop-browser ​

stop-all-browsers ​

3. 缓存管理 ​

clear-cache ​

clear-cache-batch ​

4. 分组管理 ​

group-list ​

group-create ​

group-update ​

group-delete ​

5. 代理管理 ​

proxy-list ​

proxy-create ​

proxy-update ​

proxy-delete ​

proxy-options ​

proxy-detect ​

proxy-detect-quick ​

6. User-Agent 工具 ​

ua-generate ​

ua-random ​

7. 窗口管理 ​

window-sort ​

window-sort-custom ​

window-hide ​

window-show ​

常见问题 ​

CLI 连接失败 ​

如何在 Linux 服务器上使用？ ​

超时了怎么办？ ​

TgeBrowser CLI 命令行工具

适用对象

下载与安装

通过 npm 安装（推荐）

环境要求

快速开始

常用命令速查

使用前提

全局选项

等价环境变量

超时控制

请求体写法

key=value

--json

--json-stdin

客户端信息命令

`client-version`

子命令

1. 浏览器环境管理

`env-list`

`env-open-list`

`env-create`

`env-update`

`env-delete`

`env-delete-batch`

`update-cookie`

`batch-update`

`mobile-devices`

2. 浏览器控制

`start-browser`

`stop-browser`

`stop-all-browsers`

3. 缓存管理

`clear-cache`

`clear-cache-batch`

4. 分组管理

`group-list`

`group-create`

`group-update`

`group-delete`

5. 代理管理

`proxy-list`

`proxy-create`

`proxy-update`

`proxy-delete`

`proxy-options`

`proxy-detect`

`proxy-detect-quick`

6. User-Agent 工具

`ua-generate`

`ua-random`

7. 窗口管理

`window-sort`

`window-sort-custom`

`window-hide`

`window-show`

常见问题

CLI 连接失败

如何在 Linux 服务器上使用？

超时了怎么办？