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
This commit is contained in:
Templeton Peck 2026-06-08 18:29:53 +02:00
parent 8fdf219337
commit da7dac8301
Signed by: face
GPG key ID: 8696A18EFB764ADE
6 changed files with 1454 additions and 0 deletions

View file

@ -0,0 +1,102 @@
# 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
```bash
# 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)