Documentation / CLI Reference

CLI Reference

Complete reference for all stunl command-line options

Basic Usage

stunl [flags] [port]

# Examples:
$ stunl 3000                    # Tunnel port 3000
$ stunl -port 3000              # Same as above
$ stunl -port 3000 -id myapp    # With custom ID

Core Flags

Flag	Description	Default
`-port`	Local port to tunnel	`3000`
`-host`	Local host to tunnel	`localhost`
`-protocol`	Protocol: `http`, `tcp`, or `udp`	`http`
`-id`	Custom tunnel ID (subdomain)	`auto-generated`
`-domain`	Domain to use (e.g., localshare.io)	`stunl.io`
`-root`	Use root domain instead of subdomain	`false`
`-key`	API key for Pro features	`$STUNL_API_KEY`
`-server`	Tunnel server address	`grpc.stunl.com`

Multi-Port Flags

Flag	Description
`-ports`	Multi-port mappings. Format: `name:port:protocol[@public_port]`
`-routing-strategy`	Routing: `path`, `subdomain`, `header`, `mixed`, `round_robin`, `least_connections`
`-routing-rules`	JSON file containing custom routing rules
`-public-port`	Request specific public port for TCP/UDP (10001-19999)

Multi-port syntax examples

# Basic: name:port:protocol
$ stunl -ports "web:3000:http,api:8080:http"

# With TCP services
$ stunl -ports "web:3000:http,db:5432:tcp"

# With reserved public ports
$ stunl -ports "web:3000:http,db:5432:tcp@15432,cache:6379:tcp@16379"

Authentication Flags

Flag	Description	Tier
`-password`	Password protect the tunnel (Basic Auth)	Pro
`-oauth`	OAuth provider: `github`, `google`, `microsoft`	Pro
`-oauth-allow-domain`	Restrict to email domain(s)	Pro
`-oauth-allow-email`	Restrict to specific email(s)	Pro
`-oauth-github-org`	Require GitHub org membership	Pro
`-oauth-github-team`	Require GitHub team membership (org/team)	Pro

End-to-End Encryption Flags

Flag	Description
`-e2e`	Enable end-to-end encryption (TLS passthrough)
`-e2e-cert`	Path to certificate file for E2E TLS (PEM)
`-e2e-key`	Path to private key file for E2E TLS (PEM)
`-autocert`	Request Let's Encrypt certificate (requires custom domain)

E2E examples

# Auto-generate self-signed certificate
$ stunl -port 3000 -e2e

# Use your own certificate
$ stunl -port 3000 -e2e -e2e-cert cert.pem -e2e-key key.pem

# Auto-provision Let's Encrypt certificate
$ stunl -port 3000 -domain myapp.example.com -e2e -autocert

TLS Configuration Flags

Flag	Description	Default
`-cert`	Client certificate for mTLS authentication	-
`-key-file`	Client private key for mTLS	-
`-ca`	CA certificate for server verification	-
`-skip-verify`	Skip TLS certificate verification ⚠️	`false`
`-insecure`	Disable TLS encryption ⚠️	`false`

⚠️ Security Warning

Using -insecure or -skip-verify is dangerous and should only be used for local development. These flags require STUNL_ALLOW_INSECURE=true environment variable.

Connection Flags

Flag	Description	Default
`-grpc-port`	gRPC server port	`9090`
`-timeout`	Connection timeout (e.g., 30s, 1m)	`30s`
`-max-retries`	Maximum connection retry attempts	`3`
`-security`	Security protocol version: v1.0, v1.1, v2.0	`v2.0`

Configuration Management

Flag	Description
`-init-config`	Create example configuration file at ~/.stunl/config.yaml
`-show-config`	Show current configuration (merged from all sources)
`-version`	Show version information
`-plain`	Plain text output (no colors, for scripts/logging)

Environment Variables

Variable	Description
`STUNL_API_KEY`	API key for authentication (replaces `-key`)
`STUNL_SERVER`	Tunnel server address (replaces `-server`)
`STUNL_ALLOW_INSECURE`	Required to enable `-insecure` or `-skip-verify`

Configuration File

stunl reads configuration from ~/.stunl/config.yaml. Generate an example with -init-config.

~/.stunl/config.yaml

api_key: "st_live_your_key_here"
domain: "localshare.io"
server: "grpc.stunl.com"
grpc_port: 9090
host: "localhost"
port: 3000
protocol: "http"
tunnel_id: "myapp"
timeout: "30s"
max_retries: 3

Configuration Precedence

Command-line flags → Environment variables → Config file → Defaults

Logs

Logs are written to ~/.stunl/logs/ with timestamped filenames.

# View latest log
$ ls -la ~/.stunl/logs/
$ tail -f ~/.stunl/logs/stunl_20260120_143052.log