Pinggy CLI

Create secure, shareable tunnels to your localhost and manage them from the command line. Pinggy CLI supports HTTP(S), TCP, UDP, TLS, and TLSTCP tunnels, and it can also be used for remote Remote Devices.

Installation

Pinggy CLI is available for Windows, Mac, and Linux. Global install is recommended for the system-wide pinggy command.

Install using npm:

npm install -g pinggy

Or download Pinggy CLI from here.

After install, verify the command:

pinggy --help

Getting Started

Before starting a tunnel, navigate to the directory where the Pinggy CLI is installed. You can start a tunnel by running:

./pinggy <options>

Pinggy CLI supports the same options as our SSH command. You can customize the command on our home page.

Example:

./pinggy -p 443 -R0:localhost:3000 -L4300:localhost:4300

This starts a tunnel that forwards connections to local port 3000. It also starts the web debugger on port 4300.

Pinggy CLI also supports more user-friendly options to set up simple tunnels.

Example:

./pinggy -l https://localhost:443

This starts a tunnel that forwards connections to a local HTTPS server running on localhost:443.

HTTP(S) Tunnel

To share a local HTTP server running on port 8008, use -l http://localhost:8080. You may add a token using --token MYTOK.

./pinggy -l http://localhost:8080
./pinggy --token MYTOK -l http://localhost:8080

To share a local HTTPS server running on port 8443, use -l https://localhost:8443.

./pinggy -l https://localhost:8443

TCP Tunnel

To start a TCP tunnel, use --type tcp and specify a port using -l.

./pinggy --type tcp -l 8000

UDP Tunnel

To start a UDP tunnel, use --type udp and specify a port using -l.

./pinggy --type udp -l 8000

TLS Tunnel

To start a TLS tunnel, use --type tls and specify a port using -l.

./pinggy --type tls -l 8000

Common workflows

Save a tunnel config

pinggy config save my-tunnel -l 3000 token@pro.pinggy.io

Start a saved tunnel

pinggy start my-tunnel
pinggy start my-tunnel -l 4000

Start multiple tunnels or all auto-start tunnels

pinggy start tunnel1 tunnel2

Mark a tunnel as auto-start

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

Start all tunnels that are set to auto start:

pinggy start --all

Use remote management

pinggy --remote-management <API KEY>

Start remote management as well as start the tunnels set to auto start:

pinggy start --all --remote-management <API KEY>

Key features

• HTTP, TCP, UDP, TLS, and 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, and more
• 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 for viewing tunnel statistics, requests, and responses in real time

Pinggy CLI specific options

Pinggy’s CLI allows you to configure the tunnel with various user-friendly options. Here is a list of options available for the Pinggy CLI:

Type: --type

Specify the type of tunnel you want to create. The available options are http, tcp, tls, udp, and tlstcp. If nothing is specified, the default type is http.

--type <type>

Local Port: --localport or -l

Specify the local port along with host and protocol, if present, to forward the tunnel to. The default is localhost.

--localport <protocol><host>:<port>

For example:

--localport django_server:8000
--localport https://my.domain:445
-l 777

Debugger Port: --debugger or -d

Specify the port on which the web debugger will run.

--debugger <port>

Token: --token

Provide the token for authentication.

--token <token>

Usage

Basic syntax:

pinggy [options] [user@domain]

• user@domain is optional. Domain can be any valid domain supported by the service backend, for example ap.free.pinggy.io. And user is a combination of token and tunnel mode, like token+tcp.

Options

The CLI supports both SSH-style flags and more descriptive long flags. Below is a consolidated list of public options. For the most up-to-date help, run pinggy --help.

Port Forwarding

Connection

Logging

Config

File server

AutoReconnect

Remote control

Misc

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 enforces HTTPS-only, HTTP redirected to HTTPS.
• x:passpreflight or x:allowpreflight allows CORS preflight to pass unchanged.
• x:reverseproxy disables built-in reverse-proxy header injection.
• x:xff adds X-Forwarded-For.
• x:fullurl or x:fullrequesturl includes the original request URL.
• w:<cidr>[,<cidr>...] whitelists IPs, IPv4 CIDR.
• k:<token> sets Bearer token(s) for auth, repeatable.
• b:<user:pass> adds Basic Auth credentials, repeatable.
• a:<Key:Val> adds a header.
• u:<Key:Val> updates a header.
• r:<Key> removes a 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 qr+force@free.pinggy.io x:noreverseproxy x:passpreflight x:xff --saveconf myconfig.json

• Use a config as base and override with flags:

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

Config management

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 and macOS, %APPDATA%/pinggy/tunnels/ on Windows.

Save a tunnel config

pinggy config save my-tunnel -l 3000 token@pro.pinggy.io

Save with auto-start enabled

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

List all saved configs

pinggy config list

View details of a saved config

pinggy config show my-tunnel
pinggy config show my-tunnel other-tunnel

Update a saved config

pinggy config update my-tunnel -l 4000

Enable or disable auto-start

pinggy config auto my-tunnel
pinggy config noauto my-tunnel
pinggy config auto tunnel1 tunnel2

Delete a saved config

pinggy config delete my-tunnel
pinggy config delete tunnel1 tunnel2

Shorthand: view config details

pinggy config my-tunnel

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

Starting saved tunnels

Start a saved tunnel

pinggy start my-tunnel

Start with runtime overrides

pinggy start my-tunnel -l 4000

Start multiple tunnels

pinggy start tunnel1 tunnel2

Start all auto-start tunnels

pinggy start --all

Start with remote management

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

Start with logging enabled

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

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

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.