pinggy

Pinggy CLI

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

Key features

• 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
• 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

Requirements

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

Installation

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

• Using npm:

 npm install -g pinggy

After install, verify:

  pinggy --help

Quick start

• 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 [e-mail]

• Start HTTP tunnel with web debugger on 4300:

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

• Use a token and region/domain-like arg: pinggy [e-mail] -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.

Usage

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).

Options

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.

Port Forwarding

Flag	Description	Example
-R, --R	Local port forwarding (SSH-style)	-R0:localhost:3000
-L, --L	Web debugger address (SSH-style)	-L4300:localhost:4300

Connection

Flag	Description	Example
-p, --server-port	Pinggy server port (default: 443)	--server-port 8080
--type	Type of connection (e.g., tcp)	--type tcp
-l, --localport	Local endpoint [protocol:][host:]port	--localport https://localhost:8000
-d, --debugger	Port for web debugger	-d 4300
--token	Token for authentication	--token abc123
--force	Forcefully close existing tunnels and establish a new tunnel	--force

Logging

Flag	Description
--loglevel	Logging level: ERROR, INFO, DEBUG
--logfile	Path to log file
--v	Print logs to stdout
--vv	Detailed logs (Node.js SDK + Libpinggy)
--vvv	Enable logs from CLI, SDK, and Libpinggy

Config

Flag	Description
--saveconf <file>	Create configuration file with provided options
--conf <file>	Load configuration from file (CLI flags override)

File server

Flag	Description
--serve <path>	Serve files from a local directory via simple web server

AutoReconnect

Flag	Description
--autoreconnect, -a	Automatically reconnect tunnel on failure (enabled by default; pass false to disable)

Remote control

Flag	Description
--remote-management <token>	Enable remote tunnel management
--manage <addr>	Remote management server (default: dashboard.pinggy.io)
--NoTui	Disable TUI in remote management mode

Misc

Flag	Description
--version	Print version and exit
-h, --help	Show help and exit

Extended options

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

Remote management

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

Logging

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.

Saving and loading configuration

• Save current options to a file:

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

• Use a config as base and override with flags:

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

File server mode

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

Signals and shutdown

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

Versioning

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

License

Apache License Version 2.0