Skip to content

EN CLI Reference

dongle edited this page Nov 20, 2026 · 4 revisions

中文 | English

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.

Obtaining and Running

  • 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 ./cli

Important

The build tags MUST include with_gvisor, otherwise TUN fails with "gVisor is not included in this build". On Linux, TUN requires root.

Bundled CLI Mode in the Desktop Binary

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/--elevated launch 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 tui prints a message that an interactive terminal is required.
  • --serve (spawned by start) runs the resident service loop; the desktop binary supports it too.

Service Lifecycle

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)

Command Catalog

The complete catalog (identical to the snishaper help output).

Service Status

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

Proxy

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

TUN

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)

Certificate

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)

Rules and Configuration

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

config set write behavior

  • 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_port must be 1–65535; listen_address must 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 (listen_address)

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.

Update

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

JSON Argument Examples

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}'

TUI Panel

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.

Related Docs

Clone this wiki locally