CLI Commands¶

All interaction with Tunnel Whisperer happens through the tw binary. The command tree is organized by role: tw relay … for the relay owner, tw server … for a server operator, tw client … for a client, plus role-neutral groups (config, proxy, service, status, dashboard, completion). Commands are mode-aware: a command gated to one role fails with an error when the active profile is configured for another (see Mode enforcement).

Global flags¶

Available on every command:

--log-level and --log-format are persisted to the config file when specified explicitly; later runs without the flag reuse the saved value:

# Set log level for this run and persist it
tw server start --log-level debug

# Later runs use the persisted level without needing the flag
tw server start

Top-level commands¶

tw relay (relay role)¶

Everything the relay owner does to the relay. All subcommands require mode: relay.

tw relay create flags¶

The manual flow generates an install script (tw-install-<domain>.sh, printed and saved to the current directory) that you run as root on your own VM — no Terraform, no cloud credentials. The Terraform flow requires terraform in PATH and prompts for provider credentials.

tw relay add-server flags¶

If the relay context uses the default daemon ports, the new server context is given free ones instead, so both contexts' daemons can run side by side on the same machine; the chosen ports are printed.

tw relay invite flags¶

tw relay un-enroll-server flags¶

tw server (server role)¶

All subcommands require mode: server.

To join a relay in the first place, use the top-level tw join against a code from the admin's tw relay invite — there is no tw server join-relay command. When the server is the relay admin's own machine, skip the invite exchange entirely: tw relay add-server does the whole thing in-process.

tw server user¶

tw server user invite flags:

tw server user invite alice -m 8080:80 -m 5432:5432
tw server user invite bob --from alice
tw server user invite carol -m 5432:5432 --ttl 1h

The command mints a one-time code, waits for the user to run tw join <relay-host> <code> on their own machine, and confirms a spoken authentication string before granting access. The client's SSH key and certificate are generated locally and never transit — there is no bundle file to send. See Users.

tw server app¶

Application templates are named, reusable bundles of port mappings.

tw client (client role)¶

All subcommands require mode: client.

tw join¶

tw join <relay-host> <code> [--name <ctx>]

Joins a relay using a one-time invite code from its operator (tw relay invite for a server tenant, tw server user invite for a client user). It's role-neutral and works even with no mode configured — the issuer's invite decides whether this machine becomes a server or a client.

The exchange is a SPAKE2 PAKE keyed by the code: once the key exchange completes, both sides display a short authentication string (SAS, format XXX-XXX). Read the displayed string aloud to the issuer — they approve only on an exact match, which defeats both code theft and MITM. On approval, the result is stored as a new context; on a fresh machine (no active profile yet) it's activated immediately, otherwise switch to it with tw config use-context <name>.

For the client role, port conflicts on this machine are checked during the join itself — if a granted local port is busy, you're prompted for a replacement before the context is stored.

tw config (contexts)¶

Contexts are kubectl-style stored profiles — each one a complete relay/server/ client identity (config, keys, certs). Switching contexts seals the current profile to disk and unseals the target. These commands work in any mode.

tw config import flags¶

tw status¶

tw status is ungated — it works on any machine, set up or not. It prints an identity header (active context name/ID, mode, user, relay, config file path), then the mode's live status: user counts, relay provisioning (with IP), and server/client component health (SSH, Xray, tunnel) when a daemon is running. Without a daemon it reports what it can from disk and tells you how to start one.

The role-scoped variants (tw relay status, tw server status, tw client status) show the same view but are gated to their mode.

If a running tw service's mode or relay differs from the active on-disk context (e.g. after tw config use-context), status prints a mismatch warning telling you to restart the service.

tw dashboard¶

Starts the web dashboard (default port 8080, from server.dashboard_port) and the gRPC API, then auto-starts the appropriate role:

• Server mode — if the relay is provisioned, the server starts automatically.
• Client mode — if xray.relay_host is set, the client connects automatically.

The dashboard also starts the gRPC API, so CLI commands like tw status and tw server user list talk to the running daemon instead of reading state from disk.

tw dashboard token¶

The dashboard requires a login token — there is no anonymous access. Print the current token to paste into the login page (or send as an Authorization: Bearer header):

tw dashboard token            # print the token
tw dashboard token --rotate   # generate a new token and invalidate all active sessions

The token is stored in a 0600 file (dashboard.token) in the config directory. The same token also gates /metrics.

tw proxy¶

Configure the outbound proxy used for all outbound connections. Works in all three modes.

Supported URL formats: socks5://host:port, socks5://user:pass@host:port, http://host:port, http://user:pass@host:port.

Mode enforcement¶

The mode field in config.yaml (relay, server, or client; the legacy value admin is read as relay) determines which commands are available. Running a command outside its allowed mode produces:

Error: this command requires server mode, but tw is configured in client mode

If mode is empty (not yet configured), all commands are allowed.

The mode field is tamper-evident: profiles carry a mode_auth signature over the mode and the profile's identity key. A present-but-invalid signature is refused with instructions to re-enroll/re-import/re-create; a missing signature on legacy profiles produces a one-time warning (a relay self-heals by re-signing). This is tamper-evidence only — the real role boundary is the relay's authorized_keys and the mTLS trust chain (see Security).

Running as a Service¶

Tunnel Whisperer can run as a system service on Linux (systemd), Windows (SCM), and macOS (launchd). The service runs tw dashboard (with the internal --run-as-service flag), which auto-starts the server or client based on the config mode.

sudo tw service install    # writes /etc/systemd/system/tw.service, enables it
sudo tw service start      # systemctl start tw
sudo tw service stop       # systemctl stop tw
sudo tw service uninstall  # stops, disables, removes the unit file

tw.exe service install    # registers service "tw" with the Service Control Manager
tw.exe service start      # starts the service
tw.exe service stop       # stops the service
tw.exe service uninstall  # removes the service

sudo tw service install    # writes /Library/LaunchDaemons/com.tunnelwhisperer.tw.plist
sudo tw service start      # launchctl load
sudo tw service stop       # launchctl unload
sudo tw service uninstall  # unloads and removes the plist

Shell completion¶

tw completion generates a zsh completion script:

# Load in current session
source <(tw completion)

# Persist across sessions (add to ~/.zshrc)
source <(tw completion)

# Or write to the zsh completions directory
tw completion > "${fpath[1]}/_tw"

Completion is dynamic for arguments that name local state — context names and IDs (tw config use-context/delete-context/export/rename-context), user names (tw server user delete/unregister/apply/single-session), enrolled server IDs (tw relay un-enroll-server), and app template names (tw server app edit/delete). Candidates come with descriptions (role, relay, port count, applied state) and are read purely from local files — completion never dials the relay or the daemon.