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

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 |

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

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

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