The Private Internet Access desktop client includes a command-line interface that can be used to control some functionality of the PIA client from scripts.
Invoking piactl
Windows
On Windows, specify the full path to
piactl.exe
or change into the PIA installation directory and invoke it. For example:
"C:\Program Files\Private Internet Access\piactl.exe" --help
"C:\Program Files\Private Internet Access\piactl.exe" connect
Or:
cd "C:\Program Files\Private Internet Access"
piactl --help
piactl connect
We do not recommend adding the PIA installation directory to PATH on Windows, as this would also add the DLLs shipped by PIA to PATH.
The rest of this article will use
piactl
in example commands, substitute the full path on Windows as needed.
Mac and Linux
On Mac and Linux,
piactl
is symlinked into /usr/local/bin
at installation time if possible, so normally piactl
is sufficient from a command line. For example:
piactl --help
piactl connect
This requires that:
There isn't already a file called
piactl
in/usr/local/bin
/usr/local/bin
is already in yourPATH
(PIA does not alterPATH
)On Linux, the directory
/usr/local/bin
must already exist.
Otherwise, the full path to
piactl
can be used - on Mac: /Applications/Private Internet Access.app/Contents/MacOS/piactl
; on Linux: /opt/piavpn/bin/piactl
.
Help
piactl --help
displays usage information.
Usage: piactl [options] command [parameters...]
Command-line interface to the PIA client. Some commands, such as connect, require that the graphical client is also running.
Options:
--timeout, -t <seconds> Sets timeout for one-shot commands.
--debug, -d Prints debug logs to stderr.
--help, -h Displays this help.
-v, --version Displays version information.
Arguments:
command Command to execute
parameters Parameters for the command
Commands:
connect
Connects to the VPN, or reconnects to apply new settings.
The PIA client must be running to use this command.
(The PIA daemon is inactive when the client is not running.)
disconnect
Disconnects from the VPN.
get
usage: get <type>
Get information from the PIA daemon.
Available types:
- debuglogging - State of debug logging setting
- portforward - Forwarded port number if available, or the status of the request to forward a port
- region - Currently selected region (or "auto")
- regions - List all available regions
- vpnip - Current VPN IP address
resetsettings
Resets settings to the defaults.
set
usage: set <type> <value>
Change settings in the PIA daemon.
Available types:
- debuglogging - Enable or disable debug logging.
- region - Select a region (or "auto")
Options
These options control general behavior of
piactl
.
Option | Description |
---|---|
| Specifies the timeout used for one-shot commands (default is 5 seconds). If the PIA daemon doesn't respond before this timeout, piactl exits unsuccessfully. |
| Displays debug output while executing |
| Displays the help text. |
| Displays the version of |
Commands
piactl
supports several commands:
Command | Description |
---|---|
| Causes PIA to connect to the VPN, if it isn't already connected. |
| Causes PIA to disconnect from the VPN, if it is connected. |
| Gets information about PIA settings or state. |
| Resets settings to the defaults. This only resets daemon settings (those that control the VPN connection), like protocols, ports, exclusions, etc. Graphical client settings (like the window type and icon theme) are not affected. |
| Sets some of the values obtainable with get . |
The PIA client must be running to use the connect
command. Otherwise, piactl
will print a message and exit. This is currently required because the daemon is inactive when the graphical client is not running, and so the daemon can disconnect if the user logs out.
get
/set
types
Type | Can set? | Description | Values |
---|---|---|---|
| Yes | Whether debug logging is enabled | true or false |
| No | When connected, the forwarded port, or the status of the request to forward a port | Forwarded port value, or state indicator: Inactive , Attempting , Failed , Unavailable |
| Yes | The current selected region | Region identifier (see |
| No | Lists all available regions | Lists |
| No | The current VPN IP address, if connected and the address is known | IP address, or Unknown |