tunnelbyte [region] [-- <cmd>...] [flags]
tunnelbyte <command> [flags]
Commands
| Command | Purpose |
|---|
tunnelbyte [region] | Bring up a tunnel. The primary command. |
tunnelbyte regions | List exit regions. |
tunnelbyte signup | Upgrade anonymous → free account. |
tunnelbyte login | Link this device to an existing account. |
tunnelbyte logout | Delete the cached token. |
tunnelbyte token | Print the cached API token (for $(...) substitution). |
tunnelbyte upgrade | Add a card; go paid. |
tunnelbyte billing | Open the billing portal. |
tunnelbyte version | Print version info. |
Global flags
| Flag | Default | Purpose |
|---|
--region | (auto) | Override the region (skips persistence). |
--all | off | System-wide routing (one-time sudo prompt). See routing modes. |
-v, --verbose | off | Verbose output. |
-h, --help | | Help for any command. |
There’s also --api-url (or TUNNELBYTE_API_URL) for pointing the CLI at a non-default API host. Useful for self-hosting or local dev only. Run tunnelbyte --help for the canonical list.
Where state lives
Layout follows platform conventions:
| OS | Path |
|---|
| Linux | $XDG_CONFIG_HOME/tunnelbyte/ (fallback ~/.config/tunnelbyte/) |
| macOS | ~/Library/Application Support/tunnelbyte/ |
token - bearer token (anonymous device-bound or account-linked).region - last successful auto-pick. Delete to re-geolocate.tier - last-seen tier; drives the “tier changed” banner on upgrade.browser-profiles/<app>/<region>/ - per-(browser, region) Chromium user-data-dir. Created on first launch of tunnelbyte fsn -- brave and friends. Logins / bookmarks / extensions persist there across re-runs.
The directory is mode 0700; individual files are 0600. Deleting any of them is harmless - the next invocation rebuilds.
Exit codes
| Code | Meaning |
|---|
| 0 | Tunnel torn down cleanly (Ctrl-C, server expired, etc.). |
| 1 | Generic error. See stderr. |
| 2 | Quota exhausted at session create. The error payload shows the breakdown (tier, bytes_used, session_seconds, resets_at). See tiers. |
| 3 | Session was terminated by the server while running (quota hit mid-session, idle handshake timeout, or 30-day safety ceiling). The reason prints to stderr; see the Status response for the taxonomy. |
| other | The wrapped child’s own exit code is propagated when you use the -- <cmd> form. |
