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 --helpOptions 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.devSupports 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.devCallers 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.devThe 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.devSee 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.ymlStart 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
| Option | Short form | Used by | Meaning |
|---|---|---|---|
--config <file> | -c | Configuration mode | Read a YAML configuration file. |
--authtoken <token> | None | http, tcp, reserve, configuration mode | Publisher API key. Highest credential precedence. |
--domain <domain> | -d | http, tcp, forward, reserve | Exact third or fourth level tubu.dev hostname. |
--email <email> | None | register | Required account email. |
--password <password> | None | register | Required account password. |
--help | -h | All modes | Print usage and exit. |
Environment and credentials
| Variable | Default | Meaning |
|---|---|---|
TUBU_TOKEN | Unset | Publisher API key when no flag or YAML token is supplied. |
TUBU_RELAY | https://api.tubu.dev | API 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.