Skip to content

CLI reference

Command syntax, options, credentials and process behavior for the Tubu CLI.

Invocation

Run the CLI with npx tubu-cli. Follow the Quick start for setup.

npx tubu-cli --help

Options take separate values, for example --domain my-app.tubu.dev. Use --help or -h to display usage.

http

npx tubu-cli http <port|url> --domain <domain> [--authtoken <token>]

Publish an HTTP or HTTPS target through a public HTTPS domain. A port means http://127.0.0.1:<port>. A URL must use http:// or https:// and contain only an origin, with an optional trailing slash.

npx tubu-cli http 3000 -d my-app.tubu.dev

Supports HTTP/1.1, SSE and WebSocket Upgrade. Configure routes, rewrites and shared secrets through YAML.

tcp

npx tubu-cli tcp <port|url> --domain <domain> [--authtoken <token>]

Publish a TCP target. A port means tcp://127.0.0.1:<port>. A URL must use tcp:// and include an explicit port.

npx tubu-cli tcp tcp://192.168.1.20:22 -d my-ssh.tubu.dev

Callers use forward to reach the tunnel. TCP tunnels do not accept HTTP secrets, routes or rewrites.

forward

npx tubu-cli forward <port> -d <domain>

Run on the caller machine. Bind an IPv4 loopback listener and forward each incoming connection to a published TCP tunnel over a secure WebSocket.

npx tubu-cli forward 2222 -d my-ssh.tubu.dev

The listener port must be 1 through 65535. The listener always binds to 127.0.0.1. Use -d or --domain to select the tunnel. This command does not accept --authtoken. The target application provides authentication.

reserve

npx tubu-cli reserve --domain <domain> [--authtoken <token>]

Reserve an exact Tubu hostname and wait up to five minutes for HTTPS readiness. No target argument is accepted. A timeout or cancellation does not release the reservation.

npx tubu-cli reserve -d my-app.tubu.dev

See Reserve a domain for fourth level names and expiration.

register

npx tubu-cli register --email <email> --password <password>

Create an account, enter the verification code sent to your email at the Code prompt, and receive an API key. A password must contain at least 12 characters.

npx tubu-cli register --email you@example.com --password 'REPLACE_WITH_YOUR_PASSWORD'

Replace both example values. This command accepts only --email and --password. You can also register on the website.

Configuration file

npx tubu-cli --config <file> [--authtoken <token>]
npx tubu-cli -c tubu.yml

Start all tunnels in the selected file. The path is relative to your working directory. No file is discovered automatically. --config cannot be combined with positional commands, --domain, --email or --password.

Configuration is read once. Restart the publisher after edits. See the Configuration reference.

Options

CLI options
OptionShort formUsed byMeaning
--config <file>-cConfiguration modeRead a YAML configuration file.
--authtoken <token>Nonehttp, tcp, reserve, configuration modePublisher API key. Highest credential precedence.
--domain <domain>-dhttp, tcp, forward, reserveExact third or fourth level tubu.dev hostname.
--email <email>NoneregisterRequired account email.
--password <password>NoneregisterRequired account password.
--help-hAll modesPrint usage and exit.

Environment and credentials

CLI environment variables
VariableDefaultMeaning
TUBU_TOKENUnsetPublisher API key when no flag or YAML token is supplied.
TUBU_RELAYhttps://api.tubu.devAPI origin override for development or testing.

The first supplied credential wins: --authtoken, YAML authtoken, then TUBU_TOKEN. A supplied invalid or empty credential fails validation; it does not fall back. YAML is validated before a flag can override it.

TUBU_RELAY must be an HTTP or HTTPS origin without credentials, a path other than /, query or fragment. Plain HTTP is accepted only for localhost, 127.0.0.1 or [::1]. For normal use, leave it unset. A nonlocal override changes the API origin; TCP callers still use the published domain for their data connection.

Exit and errors

Usage and startup failures print a message prefixed with tubu: to stderr and set exit code 1. --help and completed account or reservation commands exit successfully. Publishing and forward remain active until stopped.

Ctrl+C or SIGTERM closes active resources. A lost publisher connection fails the process. The CLI does not reconnect or replay interrupted sessions. Individual failed TCP caller connections close while the listener remains available.

Publishers show one monthly traffic bar for the account that owns the API key. Usage includes all account tunnels and refreshes every 5 seconds. Terminal output updates in place; redirected output prints changed values. If usage is unavailable, tunnels continue and the CLI retries at the next refresh.

The old --token, --tunnel and --hostname flags are not supported. Use --authtoken and an explicit http or tcp command.