PortLark CLI reference

portlark is the command-line client. It connects tunnels you created in the dashboard to services on your computer. It always connects to the official service at https://portlark.com; there is no option to point it at a different server.

Install and update

Platform	Installer	Installed to
Windows (x64, ARM64)	https://portlark.com/download/install-portlark.ps1	%LOCALAPPDATA%\PortLark\bin\portlark.exe
macOS (Apple silicon, Intel)	https://portlark.com/download/install-portlark.sh	~/.local/bin/portlark
Linux (x64, ARM64, ARMv7)	https://portlark.com/download/install-portlark.sh	~/.local/bin/portlark

The installers verify the SHA256 checksum before replacing a binary and need no administrator rights. To install somewhere else, set INSTALL_PATH (shell script) or pass -InstallPath (PowerShell script). To update, run the installer again. Manual downloads and checksums are on https://portlark.com/downloads.

The installers do not modify your PATH. Run the CLI by its full path, or add the install folder to your PATH. The examples below assume portlark is on your PATH.

Commands

Command	What it does
portlark	Connects using the saved configuration. If there is none, it starts setup.
portlark setup	Interactive sign-in and tunnel selection. Saves the configuration, then offers to connect.
portlark connect	Connects the tunnels in the saved configuration. Runs in the foreground until you press Ctrl+C.
portlark status	Shows the saved configuration. It does not contact the server.
portlark logout	Deletes the saved configuration from this computer.
portlark --token <token> --tunnel <id[,id...]>	Connects without a saved configuration.
portlark agent <subcommand>	Non-interactive commands for AI agents and scripts. See below.
portlark --version	Prints the client version, for example PortLark CLI 1.4.0.
portlark --help	Prints usage.

Flags can be written with one or two dashes (-version or --version).

setup

portlark setup

setup asks for:

1. Your PortLark email and password (not a client token).
2. Tunnel setup: Use existing tunnel lets you select one or more of your tunnels; Create new tunnel asks for the tunnel type (default http), a name, the local address (default 127.0.0.1:3000) and, for HTTP, a subdomain.

It then creates a client token for this computer (labeled with its hostname), saves the configuration, and asks Connect now? (default yes). Running setup again replaces the saved configuration. Old tokens stay valid until you revoke them in Dashboard → Client Tokens.

connect

portlark connect

The client prints Handshake OK followed by the access details of each tunnel:

[HTTP] my-app
  Local service: 127.0.0.1:3000
  Public URL: https://my-app.tunnel.portlark.com
  Public host: my-app.tunnel.portlark.com
  Public port: 443

The public address works only while the client is running. If no configuration exists, connect exits with no config found; run "portlark setup" first.

status

portlark status

Prints the configuration path, service URL, the number and IDs of the saved tunnels, when the configuration was created, and whether a token is present. The token itself is never printed.

logout

portlark logout

Deletes the local configuration file. It does not revoke the client token on the server; revoke it in Dashboard → Client Tokens if the computer is no longer trusted.

Connect with a token

portlark --token <client-token> --tunnel <tunnel-id>
portlark --token <client-token> --tunnel <tunnel-id-1>,<tunnel-id-2>

Uses a token you created in Dashboard → Client Tokens without saving anything. Both flags are required. Tunnel IDs are shown in the dashboard. Command-line arguments can be visible to other users on the same computer and are stored in shell history, so prefer setup on shared machines.

Agent commands

These commands are designed for AI coding agents and scripts. They never prompt, print only JSON to standard output, and manage one tunnel per credential. See Connect with your Agent for the full flow.

Command	What it does
portlark agent login --json	Starts browser authorization and returns a link and pairing code (authorization_pending), or authorized if this computer already has a valid credential.
portlark agent login --wait --json	Polls for your approval for up to about 30 seconds. Repeat while it returns authorization_pending.
portlark agent login --new --json	Starts a fresh authorization request, for example for another tunnel.
portlark agent redeem --code-stdin --json	Exchanges a one-time code read from standard input for a tunnel credential.
portlark agent up --id <tunnel-id> --json	Starts the tunnel in a background process and waits up to 25 seconds for it to connect.
portlark agent status --id <tunnel-id> --json	Reports the state of the background process.
portlark agent logs --id <tunnel-id> --json	Returns the last 32 KB of the tunnel log, with the credential redacted.
portlark agent stop --id <tunnel-id> --json	Stops the background process. The tunnel and its credential are kept.

--json and --background are accepted for compatibility: output is always JSON, and up always runs in the background. status returns:

Field	Meaning
state	stopped, connecting, connected or error
public_url	The tunnel's public address
local_addr	The local address the tunnel forwards to
local_reachable	Whether the client can open a TCP connection to local_addr
public_reachability	Always not_checked; verify the public URL yourself
error	A short error description, if any
log_path	Location of the tunnel log

Files and locations

What	Windows	macOS	Linux
Configuration (setup, connect)	%USERPROFILE%\.config\portlark\config.json	~/.config/portlark/config.json	~/.config/portlark/config.json
Agent credentials and logs	%APPDATA%\portlark\agent\	~/Library/Application Support/portlark/agent/	$XDG_CONFIG_HOME/portlark/agent/ (default ~/.config/portlark/agent/)

The configuration file contains your client token and the selected tunnel IDs. On macOS and Linux it is created with mode 0600 in a 0700 directory. The Agent directory is restricted to your user account (an ACL on Windows, mode 0700 elsewhere). Agent logs are rotated at 5 MB. Never share these files.

Exit codes

Code	Meaning
0	Success, or the tunnel was stopped with Ctrl+C
1	Runtime error, such as missing configuration, rejected token, failed handshake or lost connection
2	Invalid command or flags (usage is printed)

Agent commands exit with 0 on success and 1 on error. Errors are written to standard error as JSON, for example {"error":"profile not found; redeem the authorization code first"}.

Keep a tunnel running

The CLI does not install itself as a service. On Linux you can run it with systemd after completing portlark setup as the same user:

[Unit]
Description=PortLark tunnel
After=network-online.target
Wants=network-online.target

[Service]
User=youruser
ExecStart=/home/youruser/.local/bin/portlark connect
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

On Windows, Task Scheduler can start portlark.exe connect at logon. Agent-managed tunnels started with agent up keep running in the background but do not restart after a reboot.