Vigo/hermes-proton
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hermes-proton/skills/proton-vpn/references/commands.md
Templeton Face da7dac8301
feat(vpn): Proton VPN Hermes skill — CLI wrapper tools 
Builds the proton-vpn skill per ARCHITECTURE.md section 6 with 9 tools:

Tools:
- proton_vpn_connect — connect with fastest/random/country/city/P2P/Tor/SC selection
- proton_vpn_disconnect — disconnect current session
- proton_vpn_status — check connection status (parse CLI output)
- proton_vpn_servers — list servers with filters (country, features)
- proton_vpn_killswitch — enable/disable kill switch
- proton_vpn_config — view/modify DNS, NetShield, protocol
- proton_vpn_login — initiate browser OAuth login
- proton_vpn_logout — clear credentials
- proton_vpn_refresh — refresh server list and config

Implementation:
- Python subprocess wrapper around official protonvpn-cli v1.0+
- Human-readable CLI output parsed into structured JSON
- Privilege check (protonvpn group) before privileged operations
- 30-60s timeouts with graceful error handling
- dispatch() entry point for Hermes tool routing

Also includes:
- scripts/install.sh — distro-aware dependency installer
- references/commands.md — CLI quick reference
- .gitignore — exclude __pycache__, env, debug files

Deviations from ARCHITECTURE.md noted in docs:
- CLI uses 'login' (browser OAuth), not 'init'
- No --json output — parsed from tables
- Install via Proton repos, not PyPI
2026-06-08 18:29:53 +02:00

3.7 KiB
Raw Blame History

protonvpn-cli Reference — Commands Quick Reference

Official Proton VPN Linux CLI (v1.0.0+) Source: https://github.com/ProtonVPN/proton-vpn-cli Support: https://protonvpn.com/support/linux-cli

Installation

# Debian/Ubuntu
curl -fsSL 'https://repo.protonvpn.com/debian/dists/stable/main/signed.key' | \
  sudo gpg --dearmor -o /usr/share/keyrings/protonvpn.gpg
echo "deb [signed-by=/usr/share/keyrings/protonvpn.gpg] https://repo.protonvpn.com/debian stable main" | \
  sudo tee /etc/apt/sources.list.d/protonvpn.list
sudo apt update && sudo apt install protonvpn-cli

# Fedora
sudo dnf install protonvpn-cli

# Arch (AUR)
yay -S protonvpn-cli

Login / Logout

Command Description
protonvpn-cli login [username] Authenticate via browser OAuth
protonvpn-cli logout Clear credentials

Connect / Disconnect

Command Description
protonvpn-cli connect [servername] Connect to specific server
protonvpn-cli connect --fastest Connect to lowest-latency server
protonvpn-cli connect --random Connect to random server
protonvpn-cli connect --country US Connect to fastest server in country
protonvpn-cli connect --city "New York" Connect to fastest server in city
protonvpn-cli connect --p2p Connect to fastest P2P server
protonvpn-cli connect --tor Connect to fastest Tor server
protonvpn-cli connect --free Connect to free server
protonvpn-cli connect --secure-core Connect to Secure Core server
protonvpn-cli connect --protocol wireguard Specify protocol
protonvpn-cli connect --persistent Auto-reconnect if VPN drops
protonvpn-cli disconnect Disconnect current session

All connect options can be combined with -p udp or -p tcp to specify protocol (for OpenVPN mode).

Status & Info

Command Description
protonvpn-cli status Show connection status, server, uptime, IP
protonvpn-cli servers List all servers with features and load

Settings & Config

Command Description
protonvpn-cli config --list Show current configuration
protonvpn-cli settings --killswitch on Enable kill switch
protonvpn-cli settings --killswitch off Disable kill switch
protonvpn-cli settings --netshield on Enable NetShield (block malware)
protonvpn-cli settings --netshield off Disable NetShield
protonvpn-cli settings --netshield strict Strict NetShield mode
protonvpn-cli settings --custom-dns 1.1.1.1 Set custom DNS
protonvpn-cli settings --protocol wireguard Set preferred protocol
protonvpn-cli settings --dnsleak-protection on Enable DNS leak protection
protonvpn-cli settings --dnsleak-protection off Disable DNS leak protection
protonvpn-cli refresh Refresh server list and config

General

Command Description
protonvpn-cli --help Show help
protonvpn-cli --version Show version
protonvpn-cli --debug Enable verbose debug logging

Logs & Files

  • Logs: ~/.cache/Proton/VPN/logs/
  • Config: ~/.config/Proton/VPN/
  • Settings DB: ~/.config/Proton/VPN/settings.json

Requirements

  • Python 3
  • systemd-resolved (for DNS leak protection)
  • gnome-keyring (for credential storage)
  • NetworkManager (for connection profiles)
  • WireGuard kernel module (preferred protocol) or OpenVPN

Known Limitations (v1.0.1)

  • No headless support (requires gnome-keyring + NetworkManager)
  • Cannot run alongside Proton VPN GUI app
  • Split tunneling is not yet available
  • First login requires a browser for OAuth
  • Kill switch uses iptables (may conflict with other firewall rules)