PIA Desktop: Command Line Interface

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
background
usage: background <enable|disable>
 Allow the killswitch and/or VPN connection to remain active in the background when the GUI client is not running.
 When enabled, the PIA daemon will stay active even if the GUI client is closed or has not been started.
 This allows `piactl connect` to be used even if the GUI client is not running.
 Disabling background activation will disconnect the VPN and deactivate killswitch if the GUI client is not running.
 Disabling background activation will disconnect the VPN and deactivate killswitch if the GUI client is not running.
   
 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.)
   
 dedicatedip
 usage (add): dedicatedip add <token_file>
  usage (remove): dedicatedip remove <region_id>
 Add or remove a Dedicated IP.
 To add, put the dedicated IP token in a text file (by itself), and specify that file on the command line:
 DIP20000000000000000000000000000
 (This ensures the token is not visible in the process command line or environment.)
 To remove, specify the dedicated IP region ID, as shown by `piactl get regions`, such as
 `dedicated-sweden-000.000.000.000`.
   
 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

 login
 usage: login
 Log in to your PIA account.
 Put your username and password on separate lines in a text file,
 and specify that file on the command line:
 p0000000
 (yourpassword)
   
 logout
 Log out your PIA account on this computer.
   
 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")

Commands

piactl supports several commands: 

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  

`monitor` Types

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