CLI Reference

Global flags, exit codes, environment variables, and config file location for the justtunnel CLI.

The justtunnel CLI is a single static binary that opens tunnels, manages auth, and operates worker tunnels for teams. This reference documents every command and flag that ships with the binary today.

If you're new here, start with Your first tunnel — this section is the lookup table you come back to once you know the basics.

Commands

justtunnel [port]

Open a tunnel from a local port to a public HTTPS URL.

justtunnel auth

justtunnel logout

Remove the stored API key from the local config.

justtunnel status

Show the active account, plan, and tunnel count.

justtunnel version

Print the binary's version, commit, and build date.

justtunnel context

Switch between personal and team contexts.

justtunnel worker

Manage long-lived worker tunnels for teams.

Global flags

These flags are persistent — they work on the root command and every subcommand.

Flag	Type	Default	Description
`--config <path>`	string	`~/.config/justtunnel/config.yaml`	Path to the config file.
`--context <name>`	string	(from config)	Override the active context for this invocation. Either `personal` or `team:<slug>`.

Per-command flags are documented on each command's page.

Config file

The CLI reads its config from ~/.config/justtunnel/config.yaml by default (override with --config). The file holds the API token written by justtunnel auth, the active context, the server URL, and your default log-level and max-reconnect-attempts.

Most users never edit this file by hand — justtunnel auth, justtunnel context use, and justtunnel logout keep it in sync. If you do edit it, the CLI re-reads it on the next invocation.

Environment variables

Variable	Purpose
`JUSTTUNNEL_AUTH_TOKEN`	Fallback API token used when no token is saved in the config file. Useful for CI.

The CLI also respects standard signals: SIGINT (Ctrl-C) and SIGTERM trigger a graceful shutdown.

Exit codes

Every command returns an exit code your shell or supervisor can key on.

Code	Meaning
0	Success — command completed, or the tunnel was closed cleanly with Ctrl-C.
1	Failure — generic error (auth, network, server, validation, supervisor failure, etc.).

The CLI uses two exit codes today. Specific failure modes are surfaced as structured error messages on stderr. Scripts that need to branch on a particular failure should grep the message rather than rely on a code beyond 0/1.

TUI vs non-TTY mode

When stdout is a terminal, justtunnel <port> launches an interactive TUI that supports multiple tunnels via slash commands. When stdout is piped (CI, log capture, supervisors), the same command falls back to the original single-tunnel mode and prints a status banner followed by request logs. This fallback is automatic — you do not need a flag to choose between them.