Create secure, shareable tunnels to your localhost and manage them from the command line.

• HTTP, TCP, UDP, TLS, TLSTCP tunnels to localhost
• SSH-style and user-friendly flags
• Web debugger for HTTP tunnels
• Extended options for auth, header manipulation, IP allowlists, CORS handling, etc.
• Remote management via secure WebSocket connection (works with Pinggy Dashboard)
• Configurable logging to file and/or stdout
• Save and load configuration files
• Config store for saving, listing, updating, and starting named tunnel configs
• Auto-start support for launching saved tunnels automatically
• Simple file server mode for quickly sharing local files
• Built-in TUI (Text User Interface) for viewing tunnel statistics, requests, and responses in real time

• Node.js 18+ (recommended). The CLI uses modern ESM and WebSocket features.
• A network connection that allows outgoing WebSocket/HTTPS traffic.

Global install is recommended for system-wide "pinggy" command.

• Using npm:

 npm install -g pinggy

After install, verify:

  pinggy --help

• Start a basic HTTP tunnel to localhost:3000:

 pinggy -R0:localhost:3000

• Start a TCP tunnel (e.g., SSH on port 22):

  pinggy -R0:localhost:8000 [email protected]

• Start HTTP tunnel with web debugger on 4300:

pinggy -R0:localhost:8000 -L4300:localhost:4300

• Use a token and region/domain-like arg: pinggy [email protected] -p 3000. For more info read docs

The CLI prints generated public URLs (HTTP/HTTPS or TCP) and keeps running until you press Ctrl+C.

Basic syntax: pinggy [options] [user@domain]

• user@domain is optional. Domain can be any valid domain supported by the service backend (e.g., ap.example.com).

The CLI supports both SSH-style flags and more descriptive long flags. Below is a consolidated list (only public ones are shown here). For the most up-to-date help, run pinggy --help.

Extended options provide advanced controls. Specify them as positional values like x:https or w:192.168.1.0/24 alongside other CLI flags.

• x:https Enforce HTTPS-only (HTTP redirected to HTTPS).
• x:passpreflight | x:allowpreflight Allow CORS preflight to pass unchanged.
• x:reverseproxy Disable built-in reverse-proxy header injection.
• x:xff Add X-Forwarded-For.
• x:fullurl | x:fullrequesturl Include original request URL.
• w:[,...] Whitelist IPs (IPv4 CIDR).
• k: Set Bearer token(s) for auth (repeatable).
• b:user:pass Add Basic Auth credentials (repeatable).
• a:Key:Val Add header.
• u:Key:Val Update header.
• r: Remove header.

Examples:

• Enforce HTTPS and XFF for local HTTPS server on 8443: pinggy x:https x:xff -l https://localhost:8443

• Allow only a local subnet: pinggy w:192.168.1.0/24 -l 8080

To generate advanced CLI arguments, use Configure from Pinggy.io

You can control tunnels remotely using a secure WebSocket connection.

• Start remote management with a token:

 pinggy --remote-management <API KEY>

• Specify a management server (default is wss://dashboard.pinggy.io):

 pinggy --remote-management <API KEY> --manage wss://custom.example.com

You can control logs via CLI flags (which override environment variables). If logfile is provided, the log directory will be created if it does not exist.

• To log to file and stdout at INFO level:

  pinggy -p 3000 --logfile ~/.pinggy/pinggy.log --loglevel INFO --v

If you provide --v, --vv, or --vvv without specifying a log level, the default log level is INFO.

• Save current options to a file:

  pinggy -p 443 -L4300:localhost:4300 -t -R0:127.0.0.1:8000 [email protected]   x:noreverseproxy x:passpreflight x:xff --saveconf myconfig.json

• Use a config as base and override with flags:

pinggy --conf ./myconfig.json -p 8080

The CLI includes a built-in config store for saving, listing, and starting tunnel configurations. Configs are persisted as JSON files in your platform's config directory (~/.config/pinggy/tunnels/ on Linux/macOS, %APPDATA%/pinggy/tunnels/ on Windows).

pinggy config save my-tunnel -l 3000 [email protected]

pinggy config save my-tunnel --auto -l 3000

pinggy config list

pinggy config show my-tunnel
pinggy config show my-tunnel other-tunnel    # View multiple configs

pinggy config update my-tunnel -l 4000

pinggy config auto my-tunnel
pinggy config noauto my-tunnel
pinggy config auto tunnel1 tunnel2           # Multiple configs at once

pinggy config delete my-tunnel
pinggy config delete tunnel1 tunnel2         # Delete multiple

pinggy config my-tunnel                      # Same as: pinggy config show my-tunnel

Configs can be looked up by name (exact match) or by configId prefix (partial match).

pinggy start my-tunnel

pinggy start my-tunnel -l 4000

pinggy start tunnel1 tunnel2

pinggy start --all

pinggy start --all --remote-management <API_KEY>
pinggy start tunnel1 tunnel2 --remote-management <API_KEY>

pinggy start my-tunnel --vvv
pinggy start --all --logfile /tmp/pinggy.log --loglevel DEBUG

Note: Runtime overrides (-l, --type, --token, etc.) can only be used when starting a single tunnel. For multiple tunnels, update the saved config first with pinggy config update.

Serve a local directory quickly over a tunnel: pinggy --serve /path/to/files Optionally combine with other flags (auth, IP whitelist) as needed.

Press Ctrl+C to stop. The CLI traps SIGINT and gracefully stops active tunnels before exiting.

This package follows semantic versioning. See package.json for the current version.

Apache License Version 2.0