CLI reference

peerlify is the command-line client for the Peerlify service (peerlify-daemon) running on the same machine. Each command sends one request to the service and prints the answer. The service does the actual work: it holds the device's keys, talks to the control plane, and runs the network adapter.

The installer puts peerlify on your PATH on Windows, macOS and Linux. See Install the client.

Commands

General behavior

• Commands and options are case-insensitive: peerlify STATUS works.
• -h or --help after a command prints its usage. peerlify --help prints all commands.
• Only status, list peers, list networks, acls, telemetry and exit-point list accept --json. JSON output is a single line.
• Errors go to standard error.

Exit codes

On Linux, peerlify update returns the exit code of the package-manager update script, which can be any value.

Who can run commands

Every command runs without administrator rights. The client doesn't limit commands to administrators: anyone who can sign in to the computer can change its Peerlify connection. The only exception is installing an update, which needs administrator or root rights. On computers several people use, limit who can sign in. See Device security.

When the service can't be reached

If the service isn't running, most commands print two lines and exit with 1 (the exit-point commands print only the first line, without the channel name):

Unable to reach the daemon on the named pipe \\.\pipe\peerlify-daemon: <reason>
Check that the service is running: sc query peerlify-daemon

Unable to reach the daemon on the socket /var/run/peerlify/daemon.sock: <reason>
Check that the background service is running: sudo launchctl print system/com.peerlify.daemon

Unable to reach the daemon on the socket /run/peerlify/daemon.sock: <reason>
Check that the service is running: systemctl status peerlify-daemon

While the connection is paused

After peerlify stop, these commands still work: status, version, start, stop, login, update, list peers, exit-point list and exit-point status. The others are refused. The refusal currently arrives inside the "Unable to reach the daemon" message, ending with:

peerlify is not running. Run `peerlify start` to bring the data plane back online.

The service is running in this case. Run peerlify start.

peerlify login

Sign this device in to a network.

peerlify login
peerlify login --auth-key=<KEY> [--hostname=<NAME>]

Without a key, the command prints a link and exits:

Open the link below in your browser, sign in, and pick a network:

  https://web.peerlify.com/login-device?code=K7M4QX2D

(link expires 14:32:10)

The daemon will pick up the session automatically. Run `peerlify list networks` to verify.

Open the link on any computer, sign in, choose the network and click Approve. The link is valid for 15 minutes. The service checks for completion every 3 seconds and connects on its own. If the link expires unused, nothing is printed; run peerlify login again.

With a key, the device joins the network the key was created in, as the person who created the key:

Active User: Alice Example
Email: alice@example.com
Network: #k3x9q2m7pa

If the key has tags, the device joins as a shared resource instead:

Enrolled as a shared resource (owned by a tag; no user). `network swap` is disabled.
Network: #k3x9q2m7pa

Notes:

• login signs out any current session first. Running it on a connected device disconnects it until sign-in completes.
• login also resumes a paused service.
• An empty --auth-key=, for example from an unset variable in a script, fails with --auth-key is empty. Pass the key as --auth-key=<KEY>, or run 'peerlify login' with no options to sign in through the browser.
• --hostname only names a device when it first joins the network. If another device in the network already has the name, Peerlify adds -1, -2 and so on. A device that is already in the network keeps its name; rename it on the Devices page.
• Errors from the server are printed as is, for example Auth key has expired. or This network has reached its plan's device limit. Remove a device or upgrade the plan, then sign in again. See Sign-in and enrollment problems.

peerlify logout

Sign this device out.

peerlify logout

The service revokes the session, deletes the stored session token, removes the network adapter and waits for a new peerlify login. It keeps the device's keys, so signing in again restores the same device with the same name and address.

A device that joined with an Ephemeral auth key is instead removed from the network when it logs out. Signing in again enrolls it as a new device. See Ephemeral devices.

Output:

Logged out. Run `peerlify login --auth-key <key>` to log back in.

The suggested command is missing the =. Use peerlify login --auth-key=<key>, or peerlify login for the browser flow.

peerlify start and peerlify stop

Resume or pause this device's connection to the network.

peerlify start
peerlify stop

• stop removes the network adapter, tells the control plane the device is offline and stops all network activity. The device stays signed in.
• start brings it back. Reconnection continues in the background.

The choice is remembered across restarts. A newly installed client is already started.

These commands don't stop the operating-system service. To restart the service itself, see Troubleshooting the client.

Output: Peerlify started; data plane converging in background., Peerlify is already running., Peerlify stopped. or Peerlify is already stopped.

peerlify status

Show the service's state. Works while paused.

peerlify status [--json]

Daemon:       running
Version:      2.7.1.173
Auto-update:  enabled (network policy)
Signed in:    alice@example.com
Network:      k3x9q2m7pa
Address:      100.100.0.7
Data plane:   active
Peers:        4 reachable

--json prints the service's full status as one JSON object, or {} if the service hasn't reported a status yet. Fields that scripts usually need:

For example, to wait for an address after signing in with a key:

until [ -n "$(peerlify status --json | jq -r '.assignedIp // empty')" ]; do sleep 2; done

peerlify version

Show the CLI version and, if the service answers, its version. Always exits 0.

peerlify version
peerlify --version

peerlify 2.7.1.173
daemon 2.7.1.173

If the service is unreachable, the second line is daemon unreachable.

peerlify list peers

List the devices in the active network that this device may connect to.

peerlify list peers [-s] [--json]

build-server.k3x9q2m7pa.peerlify.net (100.100.0.12) - p2p (198.51.100.23:41641)
prod-db.k3x9q2m7pa.peerlify.net (100.100.0.15) - ERPFServer (203.0.113.10:5879)
laptop.k3x9q2m7pa.peerlify.net (100.100.0.3) - disconnected

Each peer is shown by its full name and address. With -s, the state is one of:

The list includes peers that an access rule lets this device connect to, and peers it may shadow. Peers that can only connect to this device aren't listed. This device itself is never listed.

If the access policy hasn't arrived, the command prints Access policy has not been received from the control plane yet. The same message appears while the connection is paused or signed out. An empty policy prints No clients found.

peerlify list networks

List every network the signed-in person belongs to, whether or not this device has joined it.

peerlify list networks [--json]

ACTIVE  JOINED  NETWORK     NAME             DEVICE  IP           STATUS
  *       *     k3x9q2m7pa  Example Corp     laptop  100.100.0.3  Issued
                p8w2e5r1tz  Alice's Network                       Unspecified

Columns are padded to fit their contents, so widths vary.

Requires a signed-in session. Shared (tagged) devices see This user isn't in any networks yet.

peerlify network swap

Move this device to another network you belong to.

peerlify network swap <networkId>

<networkId> is the 10-character ID from peerlify list networks. Network names are not accepted.

Swapped to network #p8w2e5r1tz.

• If the device hasn't been in that network, it joins it, subject to the network's device limit and device approval.
• All of the device's sessions are replaced by one for the new network.
• A device that was denied or revoked in the target network stays that way.
• Shared (tagged) devices can't swap: This device is a shared (tagged) resource and cannot switch networks.

peerlify ping

Send test messages to a peer and report how each one traveled.

peerlify ping <peer> [-c <count>] [-t] [--timeout <duration>] [--until-direct] [--only-results]
peerlify ping -A [options]

<peer> is an overlay address, a device name, the full name from list peers, or a device ID. Names work on every platform, including Linux.

pong from build-server.k3x9q2m7pa.peerlify.net (100.100.0.12) via 198.51.100.23:41641 in 14.7ms
pong from prod-db.k3x9q2m7pa.peerlify.net (100.100.0.15) via RELAY(203.0.113.10:5879) in 67.8ms
ping "prod-db" timed out

via <address:port> means the reply came over a direct UDP path; via RELAY(...) means it came through a relay. Pings wait one second between attempts. Pinging also starts direct-path discovery, so a peer that answers through the relay at first often switches to direct.

A ping to a peer that the access policy doesn't let you reach is reported as a timeout or as Ping target '<peer>' was not found in the active daemon peers.

Exit code: 0 if at least one reply arrived.

peerlify telemetry

Show the device's relay, its local addresses, and the state of each peer connection.

peerlify telemetry [--json]

Device            : laptop (LAPTOP)
DNS               : laptop.k3x9q2m7pa.peerlify.net
Short DNS         : laptop
Local UDP port    : 62713
Relay             : ca-central-1 (203.0.113.10:5879) (connected=True)
Local endpoints   : 192.168.1.20:62713, 198.51.100.7:62713
Peers             : 1

  Peer             State        Transport    Endpoint              RTT        Uptime     Handshake  UDP Cands
  ---------------- ------------ ------------ --------------------- ---------- ---------- ---------- ----------
  BUILD-SERVER     p2p          udp          198.51.100.23:41641   14.2 ms    2h7m       yes        4

• Column widths vary with the contents.
• Relay is this device's home relay only. Telemetry doesn't list other relays or their latency.
• Excluded local appears when addresses are excluded from peer connections. See Client configuration.
• Peers counts peers this device has an open connection object for, not the size of the network.
• --json returns the same data, including relayEndpoint, relayRegion, relayConnected, localEndpoints and a peers array with state, transport, transportEndpoint and roundTripTimeMs.

Fails with Data plane is not active. while signed out. While paused, it's refused like other commands (see While the connection is paused).

peerlify acls

Show the access rules this device has received, or check whether it may connect to a peer.

peerlify acls [--json]
peerlify acls --query=<peer> [--json]

Without --query, the command prints the network ID, this device's ID and address, and the Inbound ACL and Outbound ACL it holds, as JSON. Person-based selectors appear as device IDs because the control plane expands them. See How rules are evaluated.

With --query, it checks this device's outbound rules toward the peer and appends:

Query: build-server
Resolved target: build-server.k3x9q2m7pa.peerlify.net (100.100.0.12) [k3x9q2m7pa]
Connection possible: yes
Reason: accept:Admins SSH to servers (tcp/22)

The exit code is 1 when the answer is no.

peerlify exit-point

Route this device's internet traffic through another device, or offer this device for that. See Use an exit point.

peerlify exit-point list [--json]
peerlify exit-point status
peerlify exit-point use <peer>
peerlify exit-point off
peerlify exit-point advertise on|off

use refuses an exit point this device isn't allowed to use (see Access → Exit points), with the error code exit_point_acl_denied. use and off are refused while a network policy requires an exit point for this device. The option --allow-lan is accepted for compatibility and ignored: local network traffic always stays local.

peerlify configure

Change local settings of the service.

peerlify configure --debug-logs=true|false
peerlify configure --update-channel=stable|unstable

Both options also accept a space instead of =, and can be combined.

The service writes the setting to its configuration file. Current limitations:

• Linux: the service can't write /etc/peerlify/appsettings.json, so the command fails. Edit the file as root and restart the service instead.
• Windows: the setting is stored in C:\Program Files\Peerlify\appsettings.json, which an upgrade may replace.
• macOS: stored in /Library/Application Support/Peerlify/appsettings.json and kept across upgrades.

See Client configuration.

peerlify update

Install a newer version of the client.

peerlify update [--check] [--force] [--version <x.y.z.b>] [--channel stable|unstable] [--arch x64|x86|arm64]

A version that differs from the installed one only in the fourth (build) number is treated as the same release and skipped; --force installs it anyway. A fleet-wide pinned version published by Peerlify is installed even if it is older.

peerlify update

sudo peerlify update

sudo peerlify update

See Keep the client up to date.