CLI Commands¶

All interaction with Tunnel Whisperer happens through the tw binary. Commands are mode-aware: server-only commands fail with an error when the config is set to client, and vice versa.

Command reference¶

Command	Mode	Description
`tw serve`	server	Start the Tunnel Whisperer server (SSH, Xray, reverse tunnel, dashboard, gRPC API)
`tw connect`	client	Connect to a relay as a client and establish local port forwards
`tw dashboard`	any	Start the web dashboard with auto-start logic for server or client
`tw status`	any	Show current server/client status (connects to daemon via gRPC, falls back to local)
`tw create relay-server`	server	Interactively provision a relay server on a cloud provider
`tw create user`	server	Create a client user with tunnel access (interactive port mapping)
`tw create user --from <name>`	server	Create a user by copying port mappings from an existing user
`tw edit user <name>`	server	Edit a user's port mappings (interactive)
`tw list users`	server	List all configured users and their tunnel mappings
`tw delete user <name>`	server	Delete a user (with confirmation prompt)
`tw export user <name>`	server	Export a user's config bundle as a `.zip` file
`tw apply users [name...]`	server	Register users on the relay (all if no names specified)
`tw unregister user <name>`	server	Unregister a user from the relay (revoke access without deleting)
`tw app list`	server	List all application templates
`tw app create`	server	Create an application template (interactive)
`tw app edit <name>`	server	Edit an application template
`tw app delete <name>`	server	Delete an application template
`tw test relay`	any	Test connectivity to the relay server (DNS, HTTPS, WebSocket, SSH)
`tw relay ssh`	server	Open an interactive SSH shell on the relay server
`tw destroy relay-server`	server	Destroy the provisioned relay server via Terraform
`tw proxy`	any	Show the current outbound proxy setting
`tw proxy set <url>`	any	Set the outbound proxy URL
`tw proxy clear`	any	Remove the outbound proxy
`tw service install`	any	Install tw as a system service (Linux systemd / Windows SCM)
`tw service uninstall`	any	Remove the system service
`tw service start`	any	Start the system service
`tw service stop`	any	Stop the system service
`tw completion`	any	Generate a zsh completion script
`tw --version`	any	Print the version and exit

Global flags¶

Flag	Values	Default	Description
`--log-level`	`debug`, `info`, `warn`, `error`	`info`	Set the log verbosity level
`--version`, `-v`			Print the version and exit

The --log-level flag is persisted to the config file when specified explicitly. On subsequent runs without the flag, the saved value is used automatically.

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

# Later runs use the persisted level without needing the flag
tw serve

Mode enforcement¶

Tunnel Whisperer enforces a strict separation between server and client commands. The mode field in config.yaml determines which commands are available.

Mode mismatch error

Running a server command while configured in client mode (or vice versa) produces an error:

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

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

Dashboard auto-start¶

When launched with tw dashboard, the daemon automatically starts the appropriate service:

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 list users can communicate with the running daemon.

Running as a Service¶

Tunnel Whisperer can run as a system service on both Linux and Windows. The service runs tw dashboard, which auto-starts the server or client based on your config mode.

Linux (systemd)Windows (SCM)

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

The systemd unit is configured with Restart=on-failure and a 5-second restart delay.

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

The Windows service is set to start automatically on boot with automatic restart on failure.

Shell completion¶

Generate and install zsh completions:

# 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"