Pangolin CLI

Pangolin CLI is the recommended way to run a client using a command line interface on Mac and Linux.

Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. With companion mode, connect in the Windows app and use the CLI for commands such as SSH, on the same account, without a second login.

Pangolin CLI supports running as a user device with authentication or a machine client.

The CLI stores its own defaults in a config file.

Refer to the documentation in the official repository for the available commands, default values, and more.

InstallCopy Anchor Link

Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always pulls the latest version, adding pangolin to your PATH:

curl -fsSL https://static.pangolin.net/get-cli.sh | bash

On Windows, download the latest installer, or choose to install the CLI from menu bar of the desktop app by choosing the "Install Pangolin CLI" option.

Binaries for all platforms are available in the GitHub releases for ARM and AMD64 (x86_64) architectures.

Installation StepsCopy Anchor Link

1. Download and install the Pangolin client

   Install Pangolin using the installation script:

   Copy Text

   curl -fsSL https://static.pangolin.net/get-cli.sh | bash

2. Log in with your Pangolin account

   Log in on your Pangolin Cloud account or your self-hosted Pangolin instance:

   Copy Text

   pangolin login

3. Start Pangolin

   When logged in as a Pangolin user, connect by running:

   Copy Text

   pangolin up

   To launch a machine client without logging in, use your client credentials:

   Copy Text

   pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach

   The --attach flag runs the client in the foreground instead of spawning it as a background process.

Machine ClientsCopy Anchor Link

Machine clients don't require a login and are built for machines like services to be able to connect to private resources. Like sites, they have an ID and a secret.

Run as a ServiceCopy Anchor Link

The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host.

sudo pangolin service install client \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://app.pangolin.net

Check the service status:

sudo pangolin service status client

And to get the logs:

sudo pangolin service logs client

Systemd Service (Pangolin CLI)Copy Anchor Link

Create a basic systemd service for Pangolin CLI:

[Unit]
Description=Pangolin CLI
After=network.target

[Service]
ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Docker (Pangolin CLI)Copy Anchor Link

You can run Pangolin CLI with Docker Compose. For example, a service in your docker-compose.yml might look like this using environment variables (recommended):

services:
  pangolin-cli:
    image: fosrl/pangolin-cli:latest
    container_name: pangolin-cli
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - CLIENT_ID=5n52gnzfgl3tdox
      - CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9

You can also pass the CLI args to the container:

services:
  pangolin-cli:
    image: fosrl/pangolin-cli:latest
    container_name: pangolin-cli
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    command:
      - up
      - --id
      - "5n52gnzfgl3tdox"
      - --secret
      - "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
      - --endpoint
      - https://app.pangolin.net
      - --attach

Docker Configuration Notes:

• network_mode: host brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to function properly
• cap_add: - NET_ADMIN is required to grant the container permission to manage network interfaces
• devices: - /dev/net/tun:/dev/net/tun is required to give the container access to the TUN device for creating WireGuard interfaces

Companion ModeCopy Anchor Link

Companion mode lets Pangolin CLI use the Windows desktop app for authentication and the tunnel. Log in and connect in the desktop app, then run CLI commands as that same account. You do not run pangolin login separately.

Companion mode is available on Windows only, and it requires Pangolin for Windows 0.11.0 or later. On macOS and Linux the CLI keeps its own login, and pangolin companion is not available. On Windows, companion mode is on by default.

SSH through the desktop connectionCopy Anchor Link

1. Log in and connect with the Windows client.
2. SSH to a private SSH resource:

pangolin ssh username@alias

The CLI uses the desktop app's session and the tunnel that app already opened. pangolin scp works the same way.

CommandsCopy Anchor Link

Enable companion mode. This takes effect on the next pangolin command:

pangolin companion enable

Turn it off and go back to a standalone CLI login:

pangolin companion disable

Check whether the desktop app session is ready:

pangolin companion status

When the desktop app is logged in, status looks like this:

Companion mode: enabled
Client: Pangolin Windows
Ready: yes

If the desktop app is not logged in, status reports Ready: no and tells you to open Pangolin and log in.

With companion mode off, status reports:

Companion mode: disabled
Auth source: standalone CLI

What stays in the desktop appCopy Anchor Link

While companion mode is on, the CLI reads accounts, the active organization, and exit node selection from the desktop app. Change those in the app.

These commands are blocked. The CLI tells you to use the desktop app, or to run pangolin companion disable:

• pangolin login
• pangolin logout
• pangolin select account
• pangolin select org
• pangolin select exit-node

Other commands, including pangolin ssh and pangolin scp, run with the desktop app's session. The desktop app has to be open and logged in. If it is not, the CLI asks you to start Pangolin for Windows 0.11.0 or later and log in.

You can also set disable_companion_mode in the CLI config file. true matches pangolin companion disable.

ConfigureCopy Anchor Link

Config FileCopy Anchor Link

The Pangolin CLI stores persistent settings in ~/.config/pangolin/config.json on every platform. When the CLI is run with sudo, it uses the home directory of the user who invoked sudo, so the same file applies with and without it. Run pangolin config path to print the exact location.

UpdateCopy Anchor Link

Find the latest version in the GitHub releases.

Automatic UpdatesCopy Anchor Link

If you already have Pangolin CLI installed, use the update command:

pangolin update

Or you can re-run the installation script:

curl -fsSL https://static.pangolin.net/get-cli.sh | bash

Manual UpdatesCopy Anchor Link

Download the latest binary for your system from GitHub releases and replace your existing binary.

wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin