Helper Commands

stellar-helper is the privileged helper used by the desktop app. Most users should control it from Stellar. Use the CLI when debugging, testing routes, or operating the helper daemon directly.

Global flags

  • --log LEVEL: set log verbosity. Supported levels include quiet, info, verbose, debug, very-verbose, and very-very-verbose.
  • stellar-helper version: print the helper version, build, and environment.

Running stellar-helper with no command starts the RPC daemon, the same as stellar-helper rpc.

Login

stellar-helper login

Prompts for email/mobile/username and password, then stores the authorization token for later helper requests.

Connect

stellar-helper connect --area HKG --proxyMode allowlist --computerMode off
stellar-helper connect --server HOST:PORT --token TOKEN --sn cloudflare.com --proxyMode global

connect applies a connection request. If a daemon is already reachable, the command sends the request to the daemon; otherwise it runs the proxy in the current process.

Useful flags:

  • --area AREA: connect using a known area code.
  • --lineIndex N: choose a line from the fetched line list without interactive input.
  • --server HOST:PORT: connect to a specific proxy server.
  • --token TOKEN: token for direct server connection.
  • --sn NAME: server name used for TLS/SNI; default is cloudflare.com.
  • --proxyMode MODE or -p MODE: HTTP mode. Use off, allowlist, denylist, global, or transparent.
  • --computerMode MODE or -c MODE: PC/TUN mode. Use off, allowlist, denylist, global, or gbd.
  • --httpProxyPort PORT: local HTTP proxy port. Default is 8668.
  • --socksProxyPort PORT: local SOCKS5 proxy port. Default is 1080.
  • --shareHttp: listen for HTTP proxy clients from other devices.
  • --proxyChina: proxy China-region traffic.
  • --no-routes: run HTTP/SOCKS only and skip route mutation.
  • --local: force in-process mode even if a daemon socket is reachable.

Debug-only flags:

  • --hijack-https: enable HTTPS MITM inspection.
  • --hijack-regex REGEX: limit HTTPS hijacking to matching hosts.

RPC daemon

stellar-helper rpc
stellar-helper rpc --listenAddr /tmp/stellar-helper.sock

Starts the daemon RPC server. By default it listens on /tmp/stellar-helper.sock on macOS/Linux and :43210 on Windows.

Flags:

  • --listenAddr or -l: override the daemon socket or address.
  • --ws: enable the debug WebSocket log server on :8888.

Daemon control

ctl talks to an already running daemon. It does not start one.

stellar-helper ctl ping
stellar-helper ctl state
stellar-helper ctl state --json
stellar-helper ctl set-timeout 30

Subcommands:

  • ping: check daemon reachability.
  • version: print the daemon-reported version.
  • state: print route state, selected domain, proxy port, latency, packet loss, and traffic counters.
  • reselect-domain: ask the daemon to choose a fresh API domain.
  • restore-route: restore the system default route.
  • reset-routes: clear stale routes and restore the default route.
  • reset-network: force the default interface down/up.
  • restart-service: ask the daemon to restart itself through the service manager.
  • set-timeout MINUTES: set the daemon auto-stop timeout.

Use --socket PATH with any ctl command to override the daemon socket.

Route tools

stellar-helper routes --list-links
stellar-helper routes --flush --dry-run
stellar-helper routes --reset

Route commands are for repair and debugging. Some flags modify system routes and may require administrator privileges.

  • --list-links: list network interfaces.
  • --flush or -f: clear non-default routes.
  • --dry-run: print route operations without applying them.
  • --reset or -r: remove stale routes and restore the default route.