CLI Reference

tunnl CLI — single static binary, no runtime dependencies

Installation

Linux / macOS

curl -sSL https://tunnl.sh/install.sh | sh

The script detects your OS and architecture, downloads the correct binary from GitHub Releases, verifies the SHA256 checksum, and installs to /usr/local/bin/tunnl.

Download directly

Download the appropriate binary from the GitHub releases page:

Platform	Binary
Linux x86_64	`tunnl-linux-amd64`
Linux ARM64	`tunnl-linux-arm64`
macOS Intel	`tunnl-darwin-amd64`
macOS Apple Silicon	`tunnl-darwin-arm64`
Windows x86_64	`tunnl-windows-amd64.exe`

🍏

macOS: Binaries are unsigned pending Apple notarization. You may need to allow the binary in System Settings → Privacy & Security after first run.

Point the CLI at your server

After installation, configure the CLI to point at your self-hosted server:

tunnl login --server https://webhooks.example.com

Or set the server URL once in the config:

tunnl config set server https://webhooks.example.com

Flags

--no-color is recognized before any subcommand and applies globally. The flags --server and --token are available on the default tunnel command and tunnl login, but not on every subcommand.

Flag	Scope	Description
`--no-color`	All commands	Disable ANSI color output. Also respected via the `NO_COLOR` environment variable.
`--server <url>`	Default tunnel, `login`	Override the server URL for this invocation. Overrides the config file.
`--token <token>`	Default tunnel	Override the API token. Useful in CI/CD pipelines.

tunnl <port>

Start a tunnel to localhost:<port>.

tunnl --port 3000                                       # tunnel to localhost:3000
tunnl --port 3000 --subdomain myapp                    # request a specific subdomain
tunnl --port 3000 --subdomain myapp --server https://your.domain.com

Flag	Description
`--subdomain <name>`	Request a specific subdomain. The server assigns one randomly if omitted. The server may reject the request if the subdomain is already in use.
`--server <url>`	Server URL. Overrides the stored config.

The tunnel stays open until you press Ctrl+C. The CLI reconnects automatically with exponential backoff if the connection drops.

Authenticate to a tunnl server. Prompts for your email and password at the terminal (password input is hidden). Your credentials must already exist on the server — create an account via the web dashboard first.

tunnl login --server https://webhooks.example.com
tunnl login --server https://webhooks.example.com --device   # headless / SSH

Flag	Description
`--server <url>`	Required on first login. The server URL is saved to the config file and used for subsequent commands.
`--device`	Use device flow (RFC 8628) for headless and SSH environments. Prints a URL and code to enter on another device.

After login, the JWT is stored at ~/.tunnl/config.json.

tunnl logout

Clear stored credentials. Removes the token from ~/.tunnl/config.json.

tunnl logout

tunnl whoami

Print the email address of the currently authenticated user.

tunnl whoami
# you@example.com

tunnl inspect

Open the interactive TUI request inspector.

tunnl inspect

The inspector shows a live stream of requests. Keyboard navigation:

Key	Action
`j` / `k` or `↓` / `↑`	Move selection up/down
`Enter`	Open request details
`r`	Replay selected request
`e`	Export selected request as curl command
`/`	Filter requests
`q` / `Ctrl+C`	Quit

tunnl mcp

Start the MCP (Model Context Protocol) server over stdio. Used by AI coding agents to query tunnel traffic.

tunnl mcp

The MCP server reads credentials from ~/.tunnl/config.json or the TUNNL_TOKEN environment variable. It does not start a tunnel — it queries existing tunnel data via the server API.

See the MCP Server Guide for setup instructions for Claude Desktop and Cursor.

tunnl update

Check for a newer version and update in place.

tunnl update

The updater downloads the new binary, verifies the SHA256 checksum, executes the binary to verify it runs, and replaces the current binary atomically. Uses sudo if needed to write to /usr/local/bin.

tunnl version

Print the installed CLI version, git commit, build date, and Go version, then exit.

tunnl version
# tunnl version 1.1.0
# Git commit: abc1234
# Built:      2026-03-02T00:00:00Z
# Go version: go1.24.0

Config File

The CLI stores configuration at ~/.tunnl/config.json. You can edit this file directly or use tunnl login to populate it.

{
  "server_url": "https://webhooks.example.com",
  "token": "eyJ...",
  "user_email": "you@example.com"
}

Field	Description
`server_url`	The URL of your self-hosted tunnl server. Set by `tunnl login --server <url>`.
`token`	JWT or API key used for authentication. Set by `tunnl login`.
`user_email`	Stored for display purposes only. Set by `tunnl login`.

Environment Variables

Environment variables override the config file. Useful for CI/CD and Docker environments.

Variable	Description
`TUNNL_SERVER`	Override the server URL. Equivalent to passing `--server <url>` to every command.
`TUNNL_TOKEN`	Override the authentication token. Use a long-lived API key (generated in the dashboard) for CI/CD pipelines. Equivalent to `--token <token>`.

💡

CI/CD usage: Set TUNNL_SERVER and TUNNL_TOKEN as secrets in your CI environment. The CLI will authenticate automatically without a config file.