TgeBrowser CLI Command Line Tool

Supported from version v1.5.5 onwards.

tgebrowser is a standalone command line tool distributed with the TgeBrowser client, used to call TgeBrowser's Local API from the command line.

It does not launch the TgeBrowser client and does not require Node.js. Before using it, you need to start the TgeBrowser client, complete login, and enable Local API in the client.

Target Audience

This document is suitable for users who need to perform the following operations via command line:

Open, close, or query browser environments.
Query or manage environments, groups, proxies.
Use CLI with headless TgeBrowser client on Linux servers or in automation environments.

Download & Install

Install via npm (Recommended)

bash

npm install -g @tgebrowser/cli

After installation, the tgebrowser command is available in any directory.

Requirements

Node.js >= 18

Quick Start

After confirming the TgeBrowser client is running and Local API is enabled, you can execute commands directly.

bash

# Query client version
tgebrowser client-version

# Start an environment
tgebrowser start-browser envId=1

# Stop an environment
tgebrowser stop-browser envId=1

# List environments
tgebrowser env-list

If the client has "Local API Authentication" enabled, you need to pass the configured API Key:

bash

tgebrowser --local-api-key "your-api-key" start-browser envId=1

View help:

bash

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

Common Commands

Scenario	Command Example
Query version	`tgebrowser client-version`
Start environment	`tgebrowser start-browser envId=1`
Stop environment	`tgebrowser stop-browser envId=1`
List environments	`tgebrowser env-list`
List open envs	`tgebrowser env-open-list`
Create environment	`tgebrowser env-create --json '{"browserName":"test","fingerprint":{"os":"Windows"}}'`
Delete environment	`tgebrowser env-delete envId=1`
View help	`tgebrowser --help`

Prerequisites

The TgeBrowser graphical client must be running.
You must be logged in.
Local API must be enabled in the client.
If API authentication is enabled, you must pass the API Key via --local-api-key option or TGEBROWSER_API_KEY environment variable.
The default Local API address is http://127.0.0.1:50326. If the client uses a different port, specify it with -p.

Global Options

Global options must be placed before the subcommand:

bash

tgebrowser --local-api-key "your-api-key" start-browser envId=1

-p, --port `<n>`             Local API port
-H, --host `<h>`             Host (default: 127.0.0.1)
    --local-api-key `<key>`  Local API authentication key
    --timeout `<seconds>`    HTTP timeout in seconds (default: 30, 0 = no limit)
-j, --json `<json>`          Full JSON request body, overrides key=value
    --json-stdin           Read JSON request body from stdin
-h, --help                 Show help
-V, --version              Show version

Environment Variables

Environment Variable	Equivalent To
`TGEBROWSER_PORT`	`-p`
`TGEBROWSER_API_KEY`	`--local-api-key`
`TGEBROWSER_TIMEOUT`	`--timeout`

Timeout Control

By default, HTTP requests wait up to 30 seconds. To adjust:

bash

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

The --timeout unit is seconds. Default is 30; pass 0 for no limit.

Request Body Formats

CLI supports three request body formats: key=value for simple parameters, --json or --json-stdin for complex ones.

key=value

CLI converts key=value pairs after the subcommand into a JSON request body:

bash

tgebrowser start-browser envId=1 isHeadless=true

Conversion rules:

Input	JSON Type
`true` / `false`	boolean
`null`	null
`100` / `1.5`	number
`{...}` / `[...]`	object / array
Others	string

--json

For complex request bodies, use --json:

bash

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

--json-stdin

Read JSON from stdin:

bash

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

Client Info Commands

`client-version`

Get the current TgeBrowser client version. This command reads from local package.json first, falls back to the API status endpoint.

bash

tgebrowser client-version

Success response:

json

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

Subcommands

Each tgebrowser subcommand corresponds to a Local API endpoint. Command names are derived from the API path by removing /api/ and replacing / with -. For example, /api/browser/list becomes env-list.

1. Environment Management

`env-list`

Query environment list (paginated).

Param	Type	Required	Description
`current`	int	No	Page number, default 1
`pageSize`	int	No	Items per page, default 10
`groupId`	int	No	Group ID
`keyword`	string	No	Search keyword

bash

tgebrowser env-list
tgebrowser env-list current=1 pageSize=20
tgebrowser env-list keyword="test"

`env-open-list`

Query currently running browser environments. No parameters required.

bash

tgebrowser env-open-list

`env-create`

Create a new browser environment.

Param	Type	Required	Description
`browserName`	string	Yes	Environment name
`fingerprint`	object	Yes	Fingerprint config
`proxy`	object	No	Proxy config
`proxyId`	int	No	Existing proxy ID
`groupId`	int	No	Group ID
`remark`	string	No	Remark
`Cookie`	string	No	Cookie string
`startInfo`	object	No	Startup config
`accountInfo`	array	No	Account info

bash

# Simple creation
tgebrowser env-create browserName="Test Env" fingerprint.os=Windows

# Full creation (recommended with --json)
tgebrowser env-create --json '{
  "browserName": "Shop Environment",
  "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 marketing"
}'

`env-update`

Update an existing environment. Requires envId or userIndex.

bash

tgebrowser env-update envId=1 browserName="Updated Name"

`env-delete`

Delete a single environment.

bash

tgebrowser env-delete envId=1

`env-delete-batch`

Batch delete multiple environments.

bash

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

`update-cookie`

Update the cookie for a specific environment.

bash

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

`batch-update`

Batch update a specific field across multiple environments.

bash

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

`mobile-devices`

Query available mobile devices.

bash

tgebrowser mobile-devices
tgebrowser mobile-devices os=Android

2. Browser Control

`start-browser`

Start/open a browser environment.

Param	Type	Required	Description
`envId`	int	Yes	Environment ID
`args`	array of strings	No	Extra launch arguments
`port`	int	No	Custom debugging port
`proxy`	object	No	Override proxy at launch

bash

tgebrowser start-browser envId=1

# With extra arguments
tgebrowser start-browser --json '{
  "envId": 1,
  "args": ["--headless=new", "--disable-gpu"]
}'

`stop-browser`

Stop a running browser environment.

bash

tgebrowser stop-browser envId=1

`stop-all-browsers`

Stop all running browser environments. No parameters required.

bash

tgebrowser stop-all-browsers

3. Cache Management

`clear-cache`

Clear local cache for a specific environment.

bash

tgebrowser clear-cache envId=1

`clear-cache-batch`

Batch clear local cache for multiple environments.

bash

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

4. Group Management

`group-list`

Query group list (paginated).

bash

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

`group-create`

Create a new group.

bash

tgebrowser group-create name="New Group"

`group-update`

Update group info. Requires group ID.

bash

tgebrowser group-update id=1 name="Updated Group"

`group-delete`

Delete a group. Requires group ID.

bash

tgebrowser group-delete id=1

5. Proxy Management

`proxy-list`

Query proxy list (paginated).

bash

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

`proxy-create`

Create a new proxy.

bash

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

`proxy-update`

Update proxy info. Requires proxy ID.

bash

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

`proxy-delete`

Delete a proxy. Requires proxy ID.

bash

tgebrowser proxy-delete id=1

`proxy-options`

Query IP checker options.

bash

tgebrowser proxy-options

`proxy-detect`

Test proxy connectivity and get exit IP info.

bash

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

`proxy-detect-quick`

Quick connectivity test (no IP lookup).

bash

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

6. User-Agent Tools

`ua-generate`

Batch generate User-Agent strings.

Param	Type	Required	Description
`platform`	string	No	`android` / `ios` / `mixed` (default: mixed)
`count`	int	No	Count, 1-100, default 1
`androidVersion`	string	No	Android version, e.g. `14`
`iosVersion`	string	No	iOS version, e.g. `18`
`chromeVersion`	int	No	Chrome major version, 100-150
`type`	string	No	`wechat` / `chrome` / `safari` (default: wechat)

bash

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

`ua-random`

Generate a single random UA.

bash

tgebrowser ua-random platform=android type=chrome

7. Window Management

`window-sort`

Auto-layout all open browser windows based on screen size.

bash

tgebrowser window-sort

`window-sort-custom`

Custom layout of browser windows.

Param	Type	Required	Description
`type`	string	Yes	`box` (grid) / `diagonal` (staggered)
`width`	number	Yes	Window width
`height`	number	Yes	Window height
`col`	int	Yes	Columns per row
`startX`	number	Yes	Starting X coordinate
`startY`	number	Yes	Starting Y coordinate
`spaceX`	number	Yes	Horizontal spacing
`spaceY`	number	Yes	Vertical spacing
`offsetX`	number	Yes	X offset
`offsetY`	number	Yes	Y offset

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`

Hide the TgeBrowser main window and system tray icon.

bash

tgebrowser window-hide

`window-show`

Show the TgeBrowser main window and system tray icon.

bash

tgebrowser window-show

FAQ

CLI Connection Failed

Confirm the TgeBrowser client is running.
Confirm Local API is enabled in the client.
If using a custom port, specify the correct port with -p.
If API authentication is enabled, pass the correct key with --local-api-key.

How to Use on Linux Server?

TgeBrowser supports Linux AppImage headless mode. After starting, use tgebrowser to call Local API:

bash

./TgeBrowser.AppImage \
  --no-sandbox \
  --headless=true \
  --app-id="your-app-id" \
  --app-secret="your-app-secret" \
  --login-group-code=your-group-code

Headless mode does not show the login page or main interface, but still starts the local service and provides Local API.

Request Timed Out?

Default timeout is 30 seconds. For time-consuming operations (creating environments, starting browsers), increase the timeout:

bash

tgebrowser --timeout 120 start-browser envId=1

Timeout only means the CLI stops waiting for HTTP response, not that the client-side operation has been cancelled. It's recommended to check the final result via status query afterward.

TgeBrowser CLI Command Line Tool ​

Target Audience ​

Download & Install ​

Install via npm (Recommended) ​

Requirements ​

Quick Start ​

Common Commands ​

Prerequisites ​

Global Options ​

Environment Variables ​

Timeout Control ​

Request Body Formats ​

key=value ​

--json ​

--json-stdin ​

Client Info Commands ​

client-version ​

Subcommands ​

1. Environment Management ​

env-list ​

env-open-list ​

env-create ​

env-update ​

env-delete ​

env-delete-batch ​

update-cookie ​

batch-update ​

mobile-devices ​

2. Browser Control ​

start-browser ​

stop-browser ​

stop-all-browsers ​

3. Cache Management ​

clear-cache ​

clear-cache-batch ​

4. Group Management ​

group-list ​

group-create ​

group-update ​

group-delete ​

5. Proxy Management ​

proxy-list ​

proxy-create ​

proxy-update ​

proxy-delete ​

proxy-options ​

proxy-detect ​

proxy-detect-quick ​

6. User-Agent Tools ​

ua-generate ​

ua-random ​

7. Window Management ​

window-sort ​

window-sort-custom ​

window-hide ​

window-show ​

FAQ ​

CLI Connection Failed ​

How to Use on Linux Server? ​

Request Timed Out? ​

TgeBrowser CLI Command Line Tool

Target Audience

Download & Install

Install via npm (Recommended)

Requirements

Quick Start

Common Commands

Prerequisites

Global Options

Environment Variables

Timeout Control

Request Body Formats

key=value

--json

--json-stdin

Client Info Commands

`client-version`

Subcommands

1. Environment Management

`env-list`

`env-open-list`

`env-create`

`env-update`

`env-delete`

`env-delete-batch`

`update-cookie`

`batch-update`

`mobile-devices`

2. Browser Control

`start-browser`

`stop-browser`

`stop-all-browsers`

3. Cache Management

`clear-cache`

`clear-cache-batch`

4. Group Management

`group-list`

`group-create`

`group-update`

`group-delete`

5. Proxy Management

`proxy-list`

`proxy-create`

`proxy-update`

`proxy-delete`

`proxy-options`

`proxy-detect`

`proxy-detect-quick`

6. User-Agent Tools

`ua-generate`

`ua-random`

7. Window Management

`window-sort`

`window-sort-custom`

`window-hide`

`window-show`

FAQ

CLI Connection Failed

How to Use on Linux Server?

Request Timed Out?