Skip to main content

PIA Desktop: Command Line Interface - Knowledgebase / Technical / Application Settings and Features / Application & Features - PIA Support Portal

PIA Desktop: Command Line Interface

Authors list

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.

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 your PATH (PIA does not alter PATH
  • 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:
 - connectionstate - VPN connection state
 values: Disconnected, Connecting, StillConnecting, Connected, Interrupted, Reconnecting, StillReconnecting, DisconnectingToReconnect, Disconnecting
 - debuglogging - State of debug logging setting
 - portforward - Forwarded port number if available, or the status of the request to forward a port
 values: [forwarded port], Inactive, Attempting, Failed, Unavailable
 - region - Currently selected region (or "auto")
 - regions - List all available regions
 - vpnip - Current VPN IP address

 monitor
 usage: monitor <type>
 Monitors the PIA daemon for changes in a specific setting or state value.
  When a connection is established, the current value is printed.
  When a change is received, the new value is printed.
  Available types:
  - connectionstate - VPN connection state
  values: Disconnected, Connecting, Still Connecting, Connected, Interrupted, Reconnecting, Still Reconnecting, Disconnecting To Reconnect, Disconnecting
  - debuglogging - State of debug logging setting
  - portforward - Forwarded port number if available, or the status of the request to forward a port
  values: [forwarded port], Inactive, Attempting, Failed, Unavailable
  - region - Currently selected region (or "auto")
  - vpnip - Current VPN IP address

 resetsettings
 Resets daemon settings to the defaults (ports/protocols/etc.)
 Client settings (themes/icons/layouts) can't be set with the CLI.

 set
 usage: set <type> <value>
 Change settings in the PIA daemon.
  Available types:
  - region - Select a region (or "auto")


Option Description
--timeout <sec>-t <sec> 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.
--debug / -d Displays debug output while executing piactl.
--help / -h Displays the help text.
--version / -v Displays the version of piactl.

  

Commands

piactl supports several commands: 

Command
Description
background

connect Causes PIA to connect to the VPN, if it isn't already connected.
disconnect Causes PIA to disconnect from the VPN, if it is connected.
get <type> Gets information about PIA settings or state.
resetsettings 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.
set <type> <value>  Sets some of the values obtainable with get.
monitor  <type> Monitors the PIA daemon for changes in a specific setting or state value.

    

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

`connectionstate`

No

VPN connection state

Disconnected, Connecting, Still Connecting, Connected, Interrupted, Reconnecting, Still Reconnecting, Disconnecting To Reconnect, Disconnecting

`debuglogging`

Yes

Whether debug logging is enabled

`true` or `false`

`portforward`

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`

`region`

Yes

The current selected region

Region identifier (see `get regions`) or `auto` for automatic region

`regions`

No

Lists all available regions

Lists `auto` and all region identifiers

`vpnip`

No

The current VPN IP address, if connected and the address is known

IP address, or `Unknown`


`monitor` Types

Type

Description

Values

`connectionstate`

VPN connection state

Disconnected, Connecting, StillConnecting, Connected, Interrupted, Reconnecting, StillReconnecting, DisconnectingToReconnect, Disconnecting

`debuglogging`

State of debug logging setting

True or False

`portforward`

When connected, the forwarded port, or the status of the request to forward a port

[forwarded port], Inactive, Attempting, Failed, Unavailable

`region`

The current selected region

Currently selected region (or "auto")

`vpnip`

The current VPN IP address, if connected and the address is known

Current VPN IP address

  *Note* The current monitor command will continue running until it is manually stopped by pressing Ctrl+C *Note*