Repository navigation
EN CLI Reference
SniShaper ships a cross-platform CLI (Windows / Linux / macOS, 12 build targets). The CLI shares the same backend and configuration files as the GUI.
- Download the CLI artifact for your platform from Releases (
build/bin/cli/<Platform>/<Arch>/) and run it — it opens the TUI panel by default. - No arguments opens the TUI; with a subcommand it executes that single command and exits.
snishaper # open the interactive panel (TUI)
snishaper <command> [args] # run a single command
- Building the headless CLI yourself (Linux example):
$env:GOOS='linux'; $env:CGO_ENABLED='0'
go build -tags "headless with_gvisor" -o build/bin/snishaper-linux ./cliImportant
The build tags MUST include with_gvisor, otherwise TUN fails with "gVisor is not included in this build". On Linux, TUN requires root.
The desktop (GUI) binary embeds the same CLI dispatcher, so commands can run without opening the graphical interface:
snishaper.exe --cli help # print the command help
snishaper.exe --cli status # service status
snishaper.exe version # known CLI verbs skip --cli (busybox style)
snishaper.exe --cli tun config # every other verb matches the standalone CLI
Rules:
- An explicit marker (
--cli,--serve) or a known CLI verb enters CLI mode; no arguments or GUI flags such as--startup/--elevatedlaunch the normal graphical interface. - Headless sessions (session 0 / services / SSH / automation) always fall back to CLI mode: with no arguments the help is printed and the process exits 0 — it never hangs waiting for terminal input. This also lets automated installers (winget's post-install executable validation) pass their checks.
- The interactive TUI is the default only for the standalone CLI binary; under the desktop binary's CLI mode
tuiprints a message that an interactive terminal is required. -
--serve(spawned bystart) runs the resident service loop; the desktop binary supports it too.
| Command | Description |
|---|---|
snishaper start [--autoproxy] |
Start the resident service in the background (--autoproxy enables the proxy right after start) |
snishaper stop |
Stop the resident service (asynchronous; the process takes a few seconds to exit) |
snishaper tui |
Open the interactive panel (not available while the service is running) |
snishaper autostart status|on [--with-proxy]|off |
Autostart for the CLI service (separate entry, does not affect the desktop app) |
The complete catalog (identical to the snishaper help output).
| Command | Description |
|---|---|
status |
Service / proxy / system proxy / TUN status |
status --json |
Same as a machine-readable JSON snapshot (consumed by the macOS menu bar app and other external tools) |
stats |
Upload / download traffic statistics |
ipv6 |
Check IPv6 availability |
diag |
Diagnostics (version / ports / system proxy / TUN / paths, JSON) |
selfcheck |
End-to-end self check: service, listening ports, proxied request, system proxy and TUN |
logs [N] |
Last N log lines (default 100) |
logs clear |
Clear the in-memory log buffer |
logs clean |
Delete historical log files (keeps the current one) |
logs files |
List historical log files |
logs show <file> |
Show a specific log file |
logs capture [on|off] |
View / toggle core log capture |
| Command | Description |
|---|---|
proxy on|off |
Start / stop the proxy (HTTP + SOCKS5) |
sysproxy on|off |
Enable / disable the system proxy |
mode get|set <mode> |
View / switch proxy mode (service must be running) |
port get|set <port> |
View / change the HTTP listen port |
port occupant [port] |
Show which process occupies the port |
port kill <pid> |
Kill the process occupying the port |
socks5 |
Mixed-port note (SOCKS5 shares the port with HTTP) |
migration status|on|off|server|test |
Session migration mode and migration server |
| Command | Description |
|---|---|
tun on |
Enable TUN (turns off the system proxy set by this app first) |
tun off |
Disable TUN (restores the previously disabled system proxy) |
tun status |
Show TUN status |
tun config [json] |
View / change TUN config (mtu / dns_hijack / auto_route / outbound_interface / stack) |
tun ifaces |
List network interfaces (physical / virtual, default route, auto-selection result) |
| Command | Description |
|---|---|
ca status |
Root certificate installation status |
ca install |
Install the root certificate into the system trust store (admin / root required) |
ca uninstall |
Uninstall the installed root certificate |
ca list |
List certificates installed by this app |
ca pem |
Print the CA certificate PEM |
ca export |
Export the CA certificate to ca.crt |
ca path |
Show the CA certificate file path |
ca regenerate |
Regenerate the root certificate (reinstall afterwards) |
| Command | Description |
|---|---|
config get [key] |
Read settings.json (whole file without a key) |
config set <key> <value> |
Modify settings.json (preserves the existing key's JSON type, see below) |
config export [path] |
Export rules and settings |
config import <path> |
Import rules and settings |
sites list|show|add|update|delete |
Site-group rules (add / update accept JSON) |
upstreams list|show|add|update|delete |
Upstream config (add / update accept JSON) |
dns list|show|add|update|delete|priority|test |
DNS nodes |
ech list|upsert|fetch|delete |
ECH config (fetch pulls fresh config from a domain) |
nat64 list|add|update|delete|test |
NAT64 config |
cf status|config|refresh|fetch|prune|health |
Cloudflare IP pool and config |
evolution status|start|stop|apply |
Rule evolution testing (start blocks until the test finishes) |
route get|set|status |
Auto-routing config |
-
Type preservation: changing an existing key keeps its current JSON type (boolean keys accept
true/false; numeric keys accept integers or decimals; string keys are written as-is). A type mismatch is an error; nothing is written. - New keys: for keys not present in the config, the type is inferred in the order boolean → integer → decimal → string.
-
Value validation:
listen_portmust be 1–65535;listen_addressmust be empty or a valid IP address (IPv4 / IPv6). A failed validation is an error; nothing is written. - Unknown keys: writing a key the config schema does not recognize prints a warning but still writes it (forward compatibility).
listen_address in settings.json controls the local proxy listen address (default 127.0.0.1):
snishaper config set listen_address 192.168.1.10 # listen on a specific interface only
snishaper config set listen_address 0.0.0.0 # listen on all IPv4 interfaces
snishaper config set listen_address :: # listen on all IPv6 interfaces
snishaper config set listen_address "" # reset to default (127.0.0.1)When set to 0.0.0.0 / :: (all interfaces), local consumers such as the system proxy and TUN still point at 127.0.0.1, so nothing else changes. After a change, the address field of status output and the HTTP listen: <address:port> line reflect the actual listen address.
| Command | Description |
|---|---|
update check |
Check for a new version and list assets |
update download [index|name] |
Download an update (defaults to the asset matching the current platform) |
update install [index|name|path] |
Install an update (the process may be replaced and restarted) |
update channel [name] |
View / switch the update channel |
update source [name] [prefix] |
View / switch the download source and custom prefix |
update measure |
Measure the latency of each download source |
Most write operations accept JSON arguments:
snishaper sites add '{"name":"Example","mode":"direct","domains":["a.com"]}'
snishaper dns add '{"name":"CF","url":"https://1.1.1.1/dns-query","enabled":true}'The TUI exposes exactly the same command set as the shell (they share one dispatcher) and additionally accepts Chinese aliases (e.g. 帮助, 启动, 停止, 系统代理 开|关, 清屏, 退出). Lifecycle commands (start / stop / tui) are shell-only.
- Home
- 完整使用指南
- CLI 命令参考
- 核心模式详解
- 智能分流详解
- 规则自定义指南
- 界面配置指南
- 证书重新安装
- macOS 菜单栏应用
- Linux 软件包
- 代码结构
- Snishaper-Core 核心库
- CI 与 PR 自动化
- 便携式自动更新器
- 常见问题与排障
- Home
- Usage Guide
- CLI Reference
- Core Proxy Modes
- Auto Routing
- Custom Rules Guide
- GUI Configuration
- Certificate Installation
- macOS Menu Bar App
- Linux Packages
- Code Structure
- Snishaper-Core Library
- CI & PR Automation
- Portable Auto-Updater
- FAQ