Scroll to navigation

protonvpn-cli(1) command-line client for ProtonVPN protonvpn-cli(1)

NAME

ProtonVPN-CLI - command-line client for ProtonVPN

SYNOPSIS

protonvpn [COMMANDS] [ARGUMENTS] [OPTIONS]

DESCRIPTION

ProtonVPN-CLI is a user-friendly command-line tool for accessing the Swiss based privacy-focused ProtonVPN VPN service.

Need a ProtonVPN account to use it: can create one at https://protonvpn.com. Free accounts are available, although with limited features: only 3 countries (Japan, Netherlands, USA) are available with the free plan. It can also easily add an extra layer of privacy by activating Tor (needs paid plan).

COMMANDS

Initialize a ProtonVPN profile.
Connect to a ProtonVPN server.
Reconnect to the last server.
Disconnect the current session.
Show connection status.
Change ProtonVPN-CLI configuration.
Refresh OpenVPN configuration and server data.
Print some example commands.

ARGUMENTS

<servername>
Servername (CH#4, CH-US-1, HK5-Tor, JP-FREE#1, NL-FREE#2, US-FREE#3).

OPTIONS

Select the fastest ProtonVPN server.
Select a random ProtonVPN server.
Determine the country for fastest connect.
Connect to the fastest Secure-Core server.
Connect to the fastest torrent server.
Connect to the fastest Tor server.
Determine the protocol (UDP or TCP).
Show this help message.
Display version.

CONFIGURATION FILES

Configuration files are in user's home directory '~/.pvpn-cli'. The '~/.pvpn-cli' directory has the following files:

~/.pvpn-cli/connect.ovpn
~/.pvpn-cli/ovpn.log
~/.pvpn-cli/pvpn-cli.cfg
~/.pvpn-cli/pvpn-cli.log
~/.pvpn-cli/pvpnpass
~/.pvpn-cli/resolv.conf.backup
~/.pvpn-cli/serverinfo.json
~/.pvpn-cli/split_tunnel.txt

USAGE

protonvpn init

protonvpn (c | connect) [<servername>] [-p <protocol>]

protonvpn (c | connect) [-f | --fastest] [-p <protocol>]

protonvpn (c | connect) [--cc <code>] [-p <protocol>]

protonvpn (c | connect) [--sc] [-p <protocol>]

protonvpn (c | connect) [--p2p] [-p <protocol>]

protonvpn (c | connect) [--tor] [-p <protocol>]

protonvpn (c | connect) [-r | --random] [-p <protocol>]

protonvpn (r | reconnect)

protonvpn (d | disconnect)

protonvpn (s | status)

protonvpn configure

protonvpn refresh

protonvpn examples

protonvpn (-h | --help)

protonvpn (-v | --version)

EXTENSIVE USAGE

Initialize the ProtonVPN profile, before using ProtonVPN-CLI you need to initialize your profile. To do this, type:



    # protonvpn init
The client will ask you for your OpenVPN username and password.

You can find them at https://account.protonvpn.com/account, Account > OpenVPN / IKEv2 username.

Use the following credentials when connecting to ProtonVPN servers without application:



    OpenVPN / IKEv2 username    AaBbCcDdEeFfGg1234567890


    OpenVPN / IKEv2 password    0987654321gGfFeEdDcCbBaA
Follow the prompts and enter your OpenVPN credentials: 



    --- Please make sure to use the OpenVPN credentials ---


    Enter your ProtonVPN OpenVPN username: AaBbCcDdEeFfGg1234567890


    Enter your ProtonVPN OpenVPN password: 0987654321gGfFeEdDcCbBaA


    Confirm your ProtonVPN OpenVPN password: 0987654321gGfFeEdDcCbBaA
Next, you need to select your plan. If you are currently enjoying the 7-day free trial of ProtonVPN Plus, select 3) Plus. 



    Please choose your ProtonVPN Plan


    1) Free


    2) Basic


    3) Plus


    4) Visionary


    Your plan: 1
IMPORTANT: After your trial expires, you will need to reconfigure your plan to 1) Free. To set this up, enter protonvpn configure. Then select 2) ProtonVPN Plan. Finally, select 1) Free.

Now, you need to choose which default transmission protocol you want to use. UDP is typically the faster option, while TCP is a more reliable protocol that's better suited for unstable connections and in restricted networks. The default selection is UDP.



    Choose the default OpenVPN protocol.


    OpenVPN can act on two different protocols: UDP and TCP.


    UDP is preferred for speed but might be blocked in some networks.


    TCP is not as fast but a lot harder to block.


    Input your preferred protocol. (Default: UDP)


    1) UDP


    2) TCP


    Your choice: 2
Finally, confirm your input with y 



    You entered the following information:


    Username: AaBbCcDdEeFfGg1234567890


    Password: ************************


    Tier: Free


    Default protocol: TCP


    Is this information correct? [Y/n]: Y


    Writing configuration to disk...


    Done! Your account has been successfully initialized.
Connect to ProtonVPN 



    You are now ready to connect to ProtonVPN. For example, you can let ProtonVPN-CLI find


    the fastest server for you. Just type protonvpn connect -f and a connection will be established.
List of all Commands
Initialize ProtonVPN profile.
Select a ProtonVPN server and connect to it.
Connect to a specified server.
Connect to a random server.
Connect to the fastest server.
Connect to the fastest P2P server.
Connect to the fastest server in a specified country.
Connect to the fastest Secure Core server.
Reconnect or connect to the last server used.
Disconnect the current session.
Print connection status.
Change CLI configuration.
Refresh OpenVPN configuration and server data.
Print example commands.
Display version.
Show help message.

All connect options can be used with the -p flag to explicitly specify which transmission protocol is used for that connection (either udp or tcp).

Command Explanations You can see the full list of commands by running protonvpn --help and a list of examples by running protonvpn examples.

Most of the commands need to be run as root, so use su - with the commands in this guide!

Before using any other commands, you need to initialize your profile:



    # protonvpn init
To connect to a server, you always need the connect option (or just c): 



    # protonvpn connect
Running the above command will give you a menu that lets you select the country, server, and transmission protocol interactively. If you specify a server name after connect, you can connect directly to the server of your choice: 



    # protonvpn connect JP-FREE#1


    # protonvpn connect JP-FREE#2


    # protonvpn connect JP-FREE#3


    # protonvpn connect NL-FREE#1


    # protonvpn connect NL-FREE#2


    # protonvpn connect NL-FREE#3


    # protonvpn connect US-FREE#1


    # protonvpn connect US-FREE#2


    # protonvpn connect US-FREE#3
The server name can be written in several ways. For example, usny6, us-ny-6 or usny-06 are all valid formats.

To connect to the fastest server, you can use the --fastest or -f flag:



    # protonvpn c --fastest


    # protonvpn c -f
You can use the --random or -r flag to connect to a random server: 



    # protonvpn c -r
There are several other variables to keep in mind when you want to connect to the “fastest” server. You can connect to the fastest server in a country, the fastest Secure Core server, the fastest P2P-enabled server, or the fastest Tor server.

Fastest server in a country (replace UK with the code of the desired country, e.g. US for USA, JP for Japan, AU for Australia, etc.):



    # protonvpn c --cc UK
Fastest Secure Core server: 



    # protonvpn c --sc
Fastest P2P/torrent server: 



    # protonvpn c --p2p
Fastest Tor server: 



    # protonvpn c --tor
All connection methods (except the interactive menu) can be used with the -p flag to choose a transmission protocol. Possible values are either TCP or UDP. If that flag is not used, your connection will use the default transmission protocol you specified during the initialization:

Connect to the fastest server with TCP:



    # protonvpn c -f -p TCP
Connect to a random server with UDP: 



    # protonvpn c -rp UDP
To disconnect the VPN, you need to use the disconnect or d option: 



    # protonvpn disconnect


    # protonvpn d
If you're having trouble with your connection, e.g., because you switched networks or your device woke up from sleeping, you can easily reconnect to the last server with the reconnect or r option: 



    # protonvpn reconnect


    # protonvpn r
If you want to see the status and information of your current connection, you can use the status or s option: 



    # protonvpn status


    # protonvpn s




       Status:       Connected


       Time:         0:35:22


       IP:           89.39.107.198


       Server:       NL-FREE#1


       Features:     Normal


       Protocol:     TCP


       Kill Switch:  Disabled


       Country:      Netherlands


       City:         None


       Load:         70%


       Received:     190.85 KB


       Sent:         11.72 KB
If you want to change the settings you selected during initialization, you can do this with the configure option, just follow the prompts to change your username/password, default protocol and so on: 



    # protonvpn configure




       What do you want to change?


       1) Username and Password


       2) ProtonVPN Plan


       3) Default Protocol


       4) DNS Management


       5) Kill Switch


       6) Split Tunneling


       7) Purge Configuration


       Please enter your choice or leave empty to quit:

FEATURES

DNS Management

DNS Leak Protection



  ProtonVPN-CLI features a DNS Leak Protection feature, which makes sure that your online traffic uses ProtonVPN's DNS Servers.


  This prevents third parties (like your ISP) from being able to see your DNS queries (and, therefore, your browsing history).


  ProtonVPN-CLI accomplishes this by updating the /etc/resolv.conf file when you connect to a VPN server,


  and makes sure that only ProtonVPN's DNS Server is written in this file.


  It will also backup the previous state of /etc/resolv.conf to revert all changes upon disconnection.


  Please note that if you change your network (e.g., if you connect to a different WiFi hotspot) without first disconnecting,


  /etc/resolv.conf will likely be updated, which would remove ProtonVPN's DNS Servers.


  This could cause DNS leaks, so to keep your data safe, use protonvpn reconnect after changing your network.
Enabling DNS Leak Protection 



  To enable DNS Leak Protection, use the protonvpn configure command, then press 4 to choose DNS Management.


  Then press 1 to choose that you want to enable DNS Leak Protection.


  After you activate this feature, your DNS queries will be secure.
Custom DNS 



  You can also make a custom DNS server your default for all your ProtonVPN connections. ProtonVPN-CLI lets you add up to 3 custom DNS Servers.
Enabling Custom DNS 



  To configure custom DNS Servers, use the protonvpn configure command, then press 4 to choose DNS Management.


  Then press 2 to choose that you want to configure a custom DNS Server.


  Now enter the IP addresses of up to 3 DNS Servers you want to use and confirm with Enter.
Disabling DNS Management 



  If you don't want ProtonVPN-CLI to do any changes to your DNS, you can do this as well.


  This will cause ProtonVPN-CLI to not touch /etc/resolv.conf and your device will always use the DNS servers configured by you or through your network.
Disabling any DNS management 



  To enable DNS Leak Protection use the protonvpn configure command, then press 4 to choose DNS Management. Then press 3 to disable any DNS management.
IPv6 Leak Protection 



  ProtonVPN-CLI features an IPv6 Leak Protection feature. It makes sure that your IPv6 address is not leaked when you connect to a ProtonVPN server.


  This feature is enabled by default, and for security reasons, it can't be disabled.


  It works by detecting the IPv6 address, backing it up, and removing it from the default interface.


  When disconnecting, it adds the IPv6 address back to the default interface and deletes the backup.
Enabling Kill Switch 



  To enable Kill Switch, open the configuration menu with protonvpn configure, then select 5 for Kill Switch and


  confirm the activation with either 1 or 2, depending on your preference.


  1 will block access from your directly connected network (e.g. public WiFi) and is recommended for laptops that may connect to untrusted networks.


  2 will allow access from your directly connected network and is for computers that don't leave a secure and trusted LAN, like your home network.


  On the next connection Kill Switch will be enabled.


  Note: Kill Switch only activates on unexpected connection drops. It will not persist through reboots and not activate when calling protonvpn disconnect.


  To simulate the Kill Switch, kill the OpenVPN process while connected with pkill openvpn.
Split Tunneling 



  ProtonVPN-CLI features IP-based split tunneling. This means that you can exclude specific IP addresses or IP ranges from being routed through the VPN tunnel.


  Note: Split Tunneling does not work when the Kill Switch is enabled.
Enable Split Tunneling 



  To enable Split Tunneling, open the configuration menu with protonvpn configure, then select Split Tunneling with 6. Then confirm with y.


  Now add the IPs you want to exclude (one IP at a time) or IP ranges in CIDR notation.


  If you want to have a big list of IPs or ranges that you want to exclude, it is recommended to add one IP via the method mentioned above.


  This will create the file ~/.pvpn-cli/split_tunnel.txt. You can then paste the IPs or networks in CIDR notation in this file, one IP/network per line.


  Then call protonvpn refresh to update the OpenVPN template with your excluded IP addresses.

AUTHOR

ProtonVPN-CLI was written by Proton Technologies AG and contributors.

This manual page was written by Francisco Vilmar Cardoso Ruviaro for the Debian project (but may be used by others).

22 June 2020 protonvpn-cli-2.2.4