bkramer-proton-cli

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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](https://bun.sh) ≥ 1.1 at runtime (even when installing via npm).

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

From GitHub:

```bash
bun install -g github:brandonkramer/proton-cli
```

### From a clone

```bash
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](https://proton.me/support/single-password)
- 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](https://protonpass.github.io/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.

```bash
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

```bash
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 …`)

```bash
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).

```bash
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.

```bash
proton contacts list
proton contacts get alice
proton contacts create --name "Alice" --email alice@example.com
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.

```bash
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.

```bash
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).

```bash
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).

```bash
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 alice@example.com --subject "Hi" --body "Hello"
proton mail send --to alice@example.com --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](https://protonpass.github.io/pass-cli/) (`pass-cli`):

```bash
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:

```bash
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

```bash
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`](https://github.com/brandonkramer/proton-cli/blob/HEAD/skills/proton-cli/SKILL.md).

## License

GPL-3.0-or-later

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 alice@example.com
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 alice@example.com --subject "Hi" --body "Hello"
proton mail send --to alice@example.com --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