A small interactive CLI wrapper for VPN command-line tools.

Originally built for ProtonVPN Free, but designed to be easily adaptable to other VPN providers by swapping backend commands.

1. Features
2. Example: Country Selection
3. Requirements
4. Setup after cloning
5. Installation
6. Uninstall
7. ProtonVPN Setup (Reference Provider)
8. Usage
9. Provider Configuration
10. Supported VPN Providers
11. Repository Structure
12. Design Philosophy
13. License

• Interactive country selection (arrow keys + Enter via fzf)
• Direct connect via country code
• Simple alias-free CLI (vpn connect)
• Provider-based design (ProtonVPN as reference)
• Install / Uninstall scripts with interactive dependency checks

Use ↑ / ↓ to navigate, type to filter, Enter to select.

• Bash (must be available on the system)
• fzf (interactive selector) – if not installed, install.sh can install it for you
• A supported VPN CLI tool (e.g., protonvpn-cli) – if not installed, install.sh can install it for you

💡 Note: You normally do not need to install these manually. Running install.sh will check for missing dependencies and offer to install them automatically.

You can clone directly into ~/.config/vpn-cli to simplify provider management:

mkdir -p ~/.config/vpn-cli
git clone https://github.com/alxmtzr/vpn-cli.git ~/.config/vpn-cli

Make all scripts executable:

chmod +x ~/.config/vpn-cli/vpn \
         ~/.config/vpn-cli/install.sh \
         ~/.config/vpn-cli/uninstall.sh \
         ~/.config/vpn-cli/providers/*.sh

Optional: create a config file:

echo 'PROVIDER="protonvpn"' > ~/.config/vpn-cli/config

~/.config/vpn-cli/install.sh

• Checks for dependencies (fzf, protonvpn-cli) individually
• Prompts to install missing dependencies
• Installs vpn globally to /usr/local/bin

sudo cp ~/.config/vpn-cli/vpn /usr/local/bin/vpn

After installation, the vpn command is available globally. No alias required.

Run the uninstall script:

~/.config/vpn-cli/uninstall.sh

• Removes the vpn command
• Checks if fzf or protonvpn-cli are installed and prompts to uninstall each
• Supports zypper / apt / pacman

Or manually:

sudo rm /usr/local/bin/vpn

To use the ProtonVPN provider, you must have a ProtonVPN Free account.

Login once with your ProtonVPN credentials:

vpn login

⚠️ Note: Without a ProtonVPN account, the ProtonVPN provider will not work.

vpn --help

vpn connect

• Use ↑ / ↓ to navigate
• Type to filter
• Press Enter to connect
• Press Esc to cancel

vpn connect US
vpn connect NL

vpn disconnect

vpn status

The VPN backend is abstracted via provider scripts.

Default provider:

~/.config/vpn-cli/providers/protonvpn.sh

To support another VPN provider:

1. Copy an existing provider script (e.g., protonvpn.sh) to a new file (e.g., mullvad.sh)
2. Replace connect / disconnect / status commands
3. Adjust available countries if needed

Example:

vpn_provider_connect() {
    nordvpn connect "$1"
}

vpn-cli/                 # Root of the project
├── vpn                  # Main CLI script (global executable)
├── install.sh           # Installation script
├── uninstall.sh         # Uninstallation script
├── README.md            # Project README
├── LICENSE              # MIT License
├── providers/           # Folder containing provider scripts
│   └── protonvpn.sh
├── assets/              # Images for README
│   ├── protonvpn-logo.png
│   └── country-selection.png
└── config/              # Optional user config (created by user)
    └── config           # e.g., PROVIDER="protonvpn"

Cloning directly into ~/.config/vpn-cli simplifies usage and provider management.

• Simple Bash
• No heavy frameworks
• Interactive but scriptable
• One command, predictable behavior
• Provider-based for easy extension

MIT