proton-cli

Unofficial unified Proton command-line client (VPN + Authenticator + Contacts + Calendar + Drive + Settings + Mail) with one install and shared sign-in UX.

Not an official Proton product. Not affiliated with Proton AG.

Install

Requires Bun ≥ 1.1 at runtime (even when installing via npm).

bun add -g @bkramer/proton-cli
# or
npm install -g @bkramer/proton-cli

From GitHub:

bun install -g github:brandonkramer/proton-cli

From a clone

git clone https://github.com/brandonkramer/proton-cli.git
cd proton-cli
bun install
bun link

Requirements

• Bun ≥ 1.1
• Proton account in Single Password Mode
• TOTP if you use 2FA (FIDO2/security keys are not supported). Shared sign-in mints all selected products (default: all seven) — each product needs its own fresh TOTP (codes are single-use; one code cannot cover multiple mints)
• VPN — WireGuard tools (install tries this via Homebrew / winget; or proton vpn setup)
  • macOS: Homebrew → wireguard-tools (sudo for connect/disconnect)
  • Windows: WireGuard app via winget (Administrator terminal for connect/disconnect)
• Authenticator — CAPTCHA (macOS): native WKWebView helper, built on postinstall when possible (bun run build:captcha to retry; needs Xcode CLT)
• Optional: Proton Pass CLI (pass-cli) for credential injection

Close the Proton VPN desktop app before connecting so tunnels do not conflict.

On macOS, VPN connect/disconnect may ask for your Mac login password (sudo), not your Proton password.

CAPTCHA (if Proton requires it on sign-in): solve it in the native WKWebView window, not Safari/verify.proton.me.

Agent plugins (Cursor / Codex / Claude / Pi)

This repo ships host plugin manifests and a thin MCP server (proton mcp) that shells out to the CLI in JSON/agent mode.

proton install-mcp --scope project --host all   # Cursor/Codex/Claude MCP + skill + Pi hint
proton install-mcp --scope user --host cursor
proton mcp                                      # stdio MCP (used by hosts)

| Host | Install | |------|---------| | Cursor | proton install-mcp --host cursor (user or project) — or load .cursor-plugin/ | | Codex | proton install-mcp --host codex — or load .codex-plugin/ | | Claude | proton install-mcp --host claude (project → .mcp.json; user → claude plugin marketplace add / install) — or load .claude-plugin/ | | Pi | pi install git:github.com/brandonkramer/proton-cli (skills via "pi" in package.json); wire proton mcp through your MCP adapter |

Sign-in / CAPTCHA stay interactive on a human TTY. Prefer curated MCP tools (mail/contacts/calendar/drive/vpn/settings reads + common writes) or proton_cli with confirm=true for non-reads. See skills/proton-cli/SKILL.md.

Commands

Run proton with no args (TTY) for the interactive menu (VPN / Authenticator / Contacts / Calendar / Drive / Settings / Mail / sign-in).

Global options: --json, -y / --yes, --sudo (WireGuard on macOS).

Shared

proton                            # interactive menu (TTY)
proton account pass://Vault/Item  # save default Pass login (password + TOTP)
proton account                    # show saved Pass ref / username
proton account --clear            # clear saved Pass ref
proton signin                     # uses saved Pass ref (or --pass / PROTON_PASS)
proton signin --pass "pass://Vault/Item"
proton signin --products vpn          # or auth / ctc / all
proton signin --partial-ok
proton status --json
proton signout
proton update --check
proton update
proton mcp                        # MCP stdio server for agents
proton install-mcp                # wire Cursor/Codex/Pi

With 2FA, proton signin / TUI Sign in need a fresh TOTP per product being minted. Prefer proton account pass://Vault/Item (or --pass / PROTON_PASS) so Pass supplies a new code for each mint. Requires pass-cli logged in. Sign-out keeps the saved Pass ref.

VPN (proton vpn …)

proton vpn setup
proton vpn countries
proton vpn servers --country US
proton vpn connect --country US
proton vpn connect --city "New York"
proton vpn connect US#23
proton vpn connect --p2p
proton vpn status --json
proton vpn disconnect

| Flag | Meaning | |------|---------| | --country <code> | Exit country (e.g. NL) | | --city <name> | City name | | --p2p | P2P servers | | --securecore | Secure Core | | --tor | Tor over VPN | | --free-only | Free-tier only |

Country / feature availability depends on your Proton plan.

Authenticator (proton auth …)

E2EE TOTP/Steam seed sync and codes (Authenticator Key; client-side encrypt/decrypt).

proton auth sync
proton auth list
proton auth code github
proton auth status --output json

Product-only proton vpn signin / proton auth signin exist; prefer shared proton signin.

Contacts (proton contacts …)

E2EE contact cards, groups, and pinned keys.

proton contacts list
proton contacts get alice
proton contacts create --name "Alice" --email [email protected]
proton contacts groups list
proton contacts pin-key contact-id ./key.asc

Bare proton (TTY) opens a nested Contacts menu (list / add contact / groups / status). Prefer proton contacts … --json for scripting.

Calendar (proton calendar …)

E2EE calendars and events.

proton calendar calendars list
proton calendar calendars create --name "Work" --color "#8080FF"
proton calendar events list --calendar primary
proton calendar events create --title "Standup" --start 2026-07-24T09:00 --duration 30m
proton calendar events respond EVENT_REF --status accept

Bare proton (TTY) opens a nested Calendar menu (list calendars / list events / add event / status). Prefer proton calendar … --json for scripting. Encrypted event operations need account password via --password, --pass, or PROTON_PASSWORD.

Drive (proton drive …)

E2EE files, folders, sharing, trash, and photos.

proton drive status
proton drive items list
proton drive items upload ./file.txt /
proton drive folders create /Projects
proton drive share link /file.txt
proton drive trash list
proton drive photos list

Bare proton (TTY) opens a nested Drive menu (list items / upload file / list trash / status). Prefer proton drive … --json for scripting. Encrypted operations need account password via --password, --pass, or PROTON_PASSWORD.

Settings (proton settings …)

Account and mail preference settings via Proton’s account/mail API (not Bridge IMAP/SMTP).

proton settings get
proton settings mail
proton settings set
proton settings set view-mode 1
proton settings set hide-remote-images 1 --dry-run
proton settings get --json

Sign in with proton signin --products settings|set|all. Writable keys include view-mode, draft-type, hide-remote-images, and others listed by bare proton settings set.

Bare proton (TTY) opens a nested Settings menu (account / mail / list keys / update). Prefer proton settings … --json for scripting.

Mail (proton mail …)

E2EE list/read/search/send/organize via Proton Mail REST API (not Bridge IMAP/SMTP).

proton mail status
proton mail list
proton mail list --label sent --unread
proton mail sent                         # shortcut for --label sent
proton mail read MESSAGE_ID              # HTML → plain text in the terminal
proton mail read MESSAGE_ID --raw        # keep original HTML
proton mail search "invoice"
proton mail send --to [email protected] --subject "Hi" --body "Hello"
proton mail send --to [email protected] --subject "Hi" --body "Hello" \
  --attach ./file.pdf --attach ./notes.txt
proton mail organize read MESSAGE_ID
proton mail organize trash MESSAGE_ID
proton mail labels list
proton mail addresses list

Bare proton (TTY) opens a nested Mail menu (list inbox / list sent / search / compose / status). From a message you can reply / reply-all / forward. Compose can pick To from Contacts or type an address, and accept optional local attachment paths. Prefer proton mail … --json for scripting.

Read/send/decrypt need the account password via saved proton account / PROTON_PASS / --pass, or --password / PROTON_PASSWORD.

Sign in with proton signin --products mail|all (or full proton signin; Mail shares its session with Contacts/Settings).

Proton Pass (optional)

If you use Proton Pass CLI (pass-cli):

pass-cli login   # once, if needed
proton account pass://Vault/Item   # recommended: persist default login + TOTP
proton signin                           # uses saved account ref
# or one-shot / env:
proton signin --pass "pass://Vault/Item"
export PROTON_PASS="pass://Vault/Item"

Also supported:

export PROTON_PASSWORD='pass://Vault/Item/password'
export PROTON_TOTP='pass://Vault/Item/totp'   # optional
pass-cli run -- proton signin

Vault/Item works too (pass:// prefix optional). If several items share a title, the CLI prefers the one that has TOTP and stores a stable share/item ID. Env aliases: PROTON_PASS, PROTONVPN_PASS, PROTONAUTH_PASS, PROTON_USERNAME, PROTON_PASSWORD, PROTON_TOTP. Interactive prompts remain the default when Pass is unset. Never log resolved secrets. With 2FA, Pass (via proton account / --pass) supplies a new TOTP for each product mint.

Agents / scripting

proton status --json
proton vpn status --json
proton vpn connect --json --country US
proton auth status --output json
proton auth code github --output json

| Flag / env | Meaning | |---|---| | --json / PROTONVPN_JSON=1 | JSON on stdout (VPN / shared) | | --output json\|plain\|ink / PROTONAUTH_OUTPUT | Authenticator output format | | -y / --yes | Non-interactive confirms | | --sudo | Allow interactive macOS sudo for WireGuard | | PROTON_AGENT=1 | Root proton agent-friendly (no accidental TUI) | | PROTONVPN_AGENT=1 | VPN agent mode (JSON-friendly; sudo -n only unless --sudo) | | PROTONAUTH_AGENT=1 / CI=1 | Auth agent mode (default JSON; no CAPTCHA window / TUI) | | PROTONCONTACTS_JSON=1 / PROTONCONTACTS_AGENT=1 | Contacts agent mode (JSON; no TUI) | | PROTONCALENDAR_JSON=1 / PROTONCALENDAR_AGENT=1 | Calendar agent mode (JSON; no TUI) | | PROTON_DRIVE_JSON=1 / PROTON_DRIVE_AGENT=1 | Drive agent mode (JSON; no TUI) | | PROTONSETTINGS_JSON=1 / PROTONSETTINGS_AGENT=1 | Settings agent mode (JSON; no TUI) | | PROTONMAIL_JSON=1 / PROTONMAIL_AGENT=1 | Mail agent mode (JSON; no TUI) |

VPN exit codes: 0 ok · 1 error · 2 usage · 3 not signed in · 4 privilege needed.

CAPTCHA never opens a window in agent mode (captcha_required — sign in interactively once, then reuse the session).

Monorepo

| Path | Package | Owns | |---|---|---| | packages/core | @bkramer/proton-core | Shared config, dual-mint sessions, Pass helpers | | packages/vpn | @bkramer/proton-vpn | WireGuard + vpn-api (proton vpn …) | | packages/authenticator | @bkramer/proton-authenticator | E2EE TOTP/Steam sync (proton auth …) | | packages/contacts | @bkramer/proton-contacts | E2EE contacts/groups (proton contacts …) | | packages/calendar | @bkramer/proton-calendar | E2EE calendars/events (proton calendar …) | | packages/drive | @bkramer/proton-drive | E2EE Drive files/folders/photos (proton drive …) | | packages/settings | @bkramer/proton-settings | Account/mail API preferences (proton settings …) | | packages/mail | @bkramer/proton-mail | E2EE Mail list/read/search/send (proton mail …) | | src/ | root bins | proton router + legacy wrappers |

Config root: ~/.config/proton-cli/ (account.json for the saved Pass ref; per-product sessions under sessions/).

Shared session model

Most products use different API hosts, so they mint separate sessions. Exception: Contacts, Settings, and Mail all use mail-api.proton.me and share one session after a successful mint for any of them. proton signin still feels like one login: credentials (and Pass TOTP) are collected once, CAPTCHA is solved in the native window when required, then each remaining host is minted (with a fresh TOTP per mint).

Agent skill

End-user usage skill for agents: skills/proton-cli/SKILL.md.

License

GPL-3.0-or-later