CLI reference

The command-line tool is underpass on macOS and Linux (with tailnet as a second name) and tailnet.exe on Windows, in C:\Program Files\Tailnet. This page writes it as underpass.

text

underpass <command> [flags]

Run underpass <command> -h for a command's flags. Errors are printed as tailnet: <message> and exit with status 1.

How commands reach the service

When the background service is installed (Windows installer, or the macOS and Linux install command), up, down, status, logout, set and serve talk to it. You don't need sudo for that:

Linux: after the installer adds you to the tailnet group (log out and back in once)
macOS and Windows: for the signed-in user

Without the service, or when you pass a flag that only a standalone run uses (--auth-key, --state-dir, --config-only, --interface, --port, --engine, --hostname), up runs the tunnel itself, in the foreground, until you stop it. That needs sudo or an administrator prompt.

Commands

Command	Does
`up`	Connect: sign in through the browser, or join with `--auth-key`
`status`	Show this machine and the other devices
`down`	Disconnect; the machine stays registered
`logout`	Disconnect and forget this machine's login
`run`	Keep the tunnel up using the saved registration, with no service
`set`	Subnet routes and exit nodes
`serve`	Host a service port
`cert`	Get an HTTPS certificate for this machine's name
`service`	Install, remove or check the background service (Windows, macOS)
`uninstall`	Remove the app (Windows, macOS)
`daemon`	Run the background service (used by the service itself)
`version`	Print the version

up

Connects this machine.

bash

underpass up

Through the service, a machine that isn't signed in prints a link and waits:

text

To add this machine to your tailnet, open:

	https://app.getunderpass.com/…

Waiting for approval...
Connected as laptop (100.64.0.7).

If device approval is on, it says Logged in. An admin needs to approve this machine in the dashboard... until an admin does.

Flag	Default	Description
`--auth-key`	`$TAILNET_AUTH_KEY`	Join with an auth key instead of the browser. Runs standalone
`--hostname`	The machine's hostname	Name to register with
`--server`	`https://coord.getunderpass.com`	Coordination server URL (or `$TAILNET_SERVER`)
`--engine`	`userspace`	`userspace`: built-in WireGuard with direct connections and relay fallback. `system`: the OS's WireGuard (Linux, Windows), direct connections only
`--interface`	`tailnet0`	Tunnel interface name
`--port`	`41642`	WireGuard listen port
`--state-dir`	See State	Where keys and the login are stored
`--config-only`	`false`	Only write a WireGuard config file; needs no admin rights
`--advertise-routes`, `--advertise-exit-node`, `--exit-node`, `--accept-routes`		Same as `set`

status

bash

underpass status

text

100.64.0.7  laptop.underpass.internal  connected  (https://coord.getunderpass.com)
Relay: https://relay… (connected)

ADDRESS      NAME       OS       PATH                     LATENCY  HANDSHAKE  ROUTES
100.64.0.21  db-prod    linux    direct 203.0.113.7:41642  11.2 ms  4s ago     -
100.64.0.12  pi-garage  linux    relay                    38.6 ms  9s ago     192.168.1.0/24

The first line's state is one of connected, connecting, disconnected, waiting for login, logged out or waiting for an admin to approve this machine. A Problem: line explains anything that's wrong.

Column	Shows
`PATH`	`direct <address:port>`, `relay`, or `offline`
`LATENCY`	Round trip, like `11.2 ms`
`HANDSHAKE`	Time since the last WireGuard handshake
`ROUTES`	What the device offers: `exit node`, subnets, or `-`

down

bash

underpass down

Prints Disconnected. Run 'underpass up' to reconnect. The machine stays in your network.

logout

bash

underpass logout

Signs this machine out and forgets its login. Its keys are kept, so signing in again brings back the same name and address. Prints Logged out. Run 'underpass up' to log in again.

run

bash

sudo underpass run

Keeps the tunnel up using a saved registration, without the service, for example under your own systemd unit after up --auth-key (see Add a server). Takes --state-dir, --engine and --config-only. Without a saved registration it says not registered: run 'underpass up --auth-key ...' first.

set

Changes routing. A running client picks changes up within a few seconds.

Flag	Default	Description
`--advertise-routes`	none	Subnets to route for your network, comma-separated (`192.168.1.0/24`). `""` stops. An admin approves them. See Subnet routes
`--advertise-exit-node`	`false`	Offer this machine as an exit node
`--exit-node`	none	Send internet traffic through this machine (its name or address). `""` goes direct
`--accept-routes`	`true`	Use subnets other machines route

Advertising routes and exit nodes works on Linux, macOS and Windows with the default engine. With no flags, set prints the current settings.

serve

Hosts a port of a service on this machine.

bash

underpass serve --service=svc:grafana --tcp=443 127.0.0.1:3000   # start
underpass serve --service=svc:grafana --tcp=443 off              # stop
underpass serve status                                           # list

Flag	Description
`--service`	The service, like `svc:web`. It must exist in the dashboard first
`--tcp`	The service's port, like `443`

The last argument is where the app listens: a port (3000, meaning 127.0.0.1:3000) or host:port. The machine serves once an admin approves it under Services.

cert

Gets a trusted HTTPS certificate for this machine's full name. See HTTPS certificates.

Flag	Description
`--cert-file`	Also copy the certificate (PEM chain) here
`--key-file`	Also copy the private key (PEM) here
`--state-dir`	Where the machine's login is stored

service

Windows (administrator) and macOS (sudo):

bash

underpass service install     # install and start the background service
underpass service uninstall   # remove it; keys are kept
underpass service status      # installed / running / not installed

On Linux the service is the systemd unit tailnetd: sudo systemctl enable --now tailnetd.

uninstall

bash

underpass uninstall [--remove-keys]

Removes the app on Windows and macOS. --remove-keys also deletes this machine's keys. On Linux, see Install.

daemon

Runs the background service. You don't run this yourself; the installed service does.

Flag	Default	Description
`--state-dir`		Where keys and the login are stored
`--listen`	`127.0.0.1:41112` (Windows), `127.0.0.1:41113` (macOS, Linux)	Local API address, localhost only
`--token-file`		Where the local API token is written for the apps

version

bash

underpass version

Prints the name and version, like underpass 0.7.0.

State

Each machine keeps its keys and login in a state folder, readable only by the system:

	Background service	Standalone (`up`, `run`, `cert`)
Linux, macOS	`/var/lib/tailnetd`	`/var/lib/tailnet` (as root)
Windows	`%ProgramData%\TailnetService`	`%ProgramData%\tailnet`

Environment variables

Variable	Used by	Meaning
`TAILNET_AUTH_KEY`	`up` (standalone)	Default for `--auth-key`
`TAILNET_SERVER`	`up`	Default for `--server`
`UNDERPASS_NO_UP=1`	Install command	Install without connecting
`UNDERPASS_DOWNLOAD`	Install command	Download from another base URL