@roman-16/proton-cli-win32-x64 1.9.7 → 1.9.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +624 -0
  3. package/bin/proton-cli.exe +0 -0
  4. package/package.json +1 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,624 @@
1
+ # proton-cli
2
+
3
+ [![Release](https://img.shields.io/github/v/release/roman-16/proton-cli?sort=semver)](https://github.com/roman-16/proton-cli/releases/latest)
4
+ [![License: MIT](https://img.shields.io/github/license/roman-16/proton-cli)](LICENSE)
5
+ [![Go](https://img.shields.io/github/go-mod/go-version/roman-16/proton-cli)](go.mod)
6
+
7
+ > **Disclaimer:** This is an unofficial, community-built tool and is not endorsed by or affiliated with Proton AG. Use at your own risk.
8
+
9
+ An unofficial command-line tool for [Proton](https://proton.me) - Mail, Drive, Calendar, Pass, and Contacts from your terminal, with real end-to-end encryption.
10
+
11
+ proton-cli implements the same authentication and encryption as the [Proton web client](https://github.com/ProtonMail/WebClients): SRP login, the PGP key hierarchy, and full end-to-end encryption, using [go-srp](https://github.com/ProtonMail/go-srp) and [gopenpgp](https://github.com/ProtonMail/gopenpgp).
12
+
13
+ ## Contents
14
+
15
+ - [Features](#features)
16
+ - [Install](#install)
17
+ - [Quick start](#quick-start)
18
+ - [Core concepts](#core-concepts)
19
+ - [Configuration](#configuration)
20
+ - [Usage](#usage)
21
+ - [Scripting](#scripting)
22
+ - [How it works](#how-it-works)
23
+ - [Human verification (CAPTCHA)](#human-verification-captcha)
24
+ - [Security](#security)
25
+ - [Limitations](#limitations)
26
+ - [Development](#development)
27
+ - [API reference](#api-reference)
28
+ - [License](#license)
29
+
30
+ ## Features
31
+
32
+ - **Mail** - list, search, read, send (attachments, HTML, scheduled, self-destruct), organize, and manage labels, folders, and Sieve filters.
33
+ - **Drive** - upload/download (streaming and recursive), move, copy, revisions, public links, member sharing, trash, and photos.
34
+ - **Calendar** - calendars and events, recurrence, reminders, and attendees.
35
+ - **Pass** - vaults, items (login, note, card, wifi, ssh key, identity, custom), aliases, and TOTP.
36
+ - **Contacts** - full CRUD, pinned encryption keys, and contact groups.
37
+ - **Real E2EE** - SRP login and the full PGP key hierarchy, decrypting and signing exactly like the web client.
38
+ - **Built for scripts** - `--output json`, meaningful exit codes, streaming I/O, and `stdout = new ID` on create.
39
+
40
+ ## Install
41
+
42
+ ### Download a binary (recommended)
43
+
44
+ Grab the latest binary for your platform from [**GitHub Releases**](https://github.com/roman-16/proton-cli/releases/latest).
45
+
46
+ | Platform | Binary |
47
+ |---|---|
48
+ | Linux (x86_64) | `proton-cli_linux_amd64` |
49
+ | Linux (ARM64) | `proton-cli_linux_arm64` |
50
+ | macOS (Apple Silicon) | `proton-cli_darwin_arm64` |
51
+ | macOS (Intel) | `proton-cli_darwin_amd64` |
52
+ | Windows (x86_64) | `proton-cli_windows_amd64.exe` |
53
+
54
+ **Linux / macOS:**
55
+
56
+ ```bash
57
+ curl -LO https://github.com/roman-16/proton-cli/releases/latest/download/proton-cli_linux_amd64
58
+ chmod +x proton-cli_linux_amd64
59
+ sudo mv proton-cli_linux_amd64 /usr/local/bin/proton-cli
60
+ ```
61
+
62
+ **Windows:** download the `.exe` from the [releases page](https://github.com/roman-16/proton-cli/releases/latest) and add it to your PATH.
63
+
64
+ ### Install on Arch Linux (AUR)
65
+
66
+ ```bash
67
+ yay -S proton-cli-bin # or: paru -S proton-cli-bin
68
+ ```
69
+
70
+ ### Install on Debian, Ubuntu, Linux Mint (APT)
71
+
72
+ ```bash
73
+ sudo install -d -m 0755 /etc/apt/keyrings
74
+ curl -fsSL https://roman-16.github.io/proton-cli/gpg.key | sudo tee /etc/apt/keyrings/proton-cli.asc >/dev/null
75
+ echo "deb [signed-by=/etc/apt/keyrings/proton-cli.asc] https://roman-16.github.io/proton-cli stable main" | sudo tee /etc/apt/sources.list.d/proton-cli.list
76
+ sudo apt update && sudo apt install proton-cli
77
+ ```
78
+
79
+ ### Install on Fedora, RHEL, Alpine
80
+
81
+ `.rpm` and `.apk` packages are attached to each [release](https://github.com/roman-16/proton-cli/releases/latest). Download the one for your platform and install it directly:
82
+
83
+ ```bash
84
+ sudo dnf install ./proton-cli_*.rpm # Fedora / RHEL
85
+ sudo apk add --allow-untrusted ./proton-cli_*.apk # Alpine
86
+ ```
87
+
88
+ ### Install with Nix
89
+
90
+ Available in [nixpkgs](https://search.nixos.org/packages?query=proton-cli) as the `proton-cli` package.
91
+
92
+ ### Install with Nix flake
93
+
94
+ ```nix
95
+ inputs = {
96
+ proton-cli = {
97
+ url = "github:roman-16/proton-cli";
98
+ inputs.nixpkgs.follows = "nixpkgs";
99
+ };
100
+ };
101
+
102
+ # in a NixOS module
103
+ environment.systemPackages = [
104
+ proton-cli.packages.${pkgs.stdenv.hostPlatform.system}.default
105
+ ];
106
+ ```
107
+
108
+ ### Install on Windows (winget)
109
+
110
+ ```powershell
111
+ winget install Roman.ProtonCLI
112
+ ```
113
+
114
+ ### Install with Homebrew (macOS)
115
+
116
+ ```bash
117
+ brew install --cask roman-16/tap/proton-cli
118
+ ```
119
+
120
+ ### Install with npm
121
+
122
+ ```bash
123
+ npm install -g @roman-16/proton-cli
124
+ ```
125
+
126
+ ### Install with Go
127
+
128
+ ```bash
129
+ go install github.com/roman-16/proton-cli@latest
130
+ ```
131
+
132
+ > **Note:** `go install` builds do **not** embed the CAPTCHA helper that release binaries include. If Proton demands human verification at login, install a release binary instead. See [Human verification](#human-verification-captcha).
133
+
134
+ ### Build from source
135
+
136
+ ```bash
137
+ git clone https://github.com/roman-16/proton-cli.git
138
+ cd proton-cli
139
+ go build .
140
+ ```
141
+
142
+ ## Quick start
143
+
144
+ ### 1. Set your credentials
145
+
146
+ ```bash
147
+ export PROTON_USER=alice@proton.me
148
+ export PROTON_PASSWORD=your-password
149
+ # export PROTON_TOTP=123456 # if 2FA is enabled
150
+ ```
151
+
152
+ The session is saved to `~/.config/proton-cli/sessions/<profile>.json` after the first login and reused automatically.
153
+
154
+ ### 2. Try it
155
+
156
+ ```bash
157
+ proton-cli mail messages list
158
+ proton-cli drive items list
159
+ proton-cli --help # every command and subcommand accepts --help
160
+ proton-cli --version
161
+ ```
162
+
163
+ ## Core concepts
164
+
165
+ These apply across every command.
166
+
167
+ - **REF** - anywhere you see `REF`, pass either a full Proton ID or a search term (subject / name / URL / title, depending on the command). Ambiguous matches print candidates to stderr and exit `4`.
168
+ - **Short IDs** - in an interactive terminal, list commands shorten Proton IDs to 8 characters. proton-cli caches the IDs you have seen at `~/.config/proton-cli/idcache/<profile>.json`, so you can paste an 8-char prefix into any command that takes an ID. Pipes, redirection, and `--output json|yaml` always emit full IDs. Pass `--full-ids` to disable shortening. See [Short IDs](#short-ids) below.
169
+ - **Output** - `--output text|json|yaml` (default `text`). JSON/YAML use `snake_case` keys.
170
+ - **Exit codes** - `0` success · `1` user error · `2` auth · `3` not-found · `4` conflict / ambiguous · `5` network / server · `130` cancelled.
171
+ - **Create = ID on stdout** - creating commands print the new ID to stdout and `✓ …` to stderr, so `ID=$(proton-cli ... create ...)` works. `mail messages send` follows suit: it prints the message ID, and scheduled sends confirm the resolved local time.
172
+ - **Streaming I/O** - `-` means stdin (inputs) or stdout (outputs), e.g. `mail messages send --body -`, `drive items upload - /path`, `drive items download /path --output -`.
173
+ - **Dry run** - `--dry-run` on any mutating command previews without applying.
174
+ - **Cancellation** - `Ctrl+C` aborts in-flight operations.
175
+
176
+ ### Short IDs
177
+
178
+ ```
179
+ $ proton-cli mail messages list
180
+ ID FROM SUBJECT DATE ⚑
181
+ ──────── ────────────── ─────────────── ──────────────── ─
182
+ NWM5AYGx alice@a.com Hello 2026-04-15 14:32
183
+ ```
184
+
185
+ The short prefix pastes straight back into any command:
186
+
187
+ ```
188
+ $ proton-cli mail messages read NWM5AYGx
189
+ Subject: Hello
190
+ ...
191
+ ```
192
+
193
+ Pipes and `--output json|yaml` always emit full IDs:
194
+
195
+ ```
196
+ $ proton-cli mail messages list --output json | jq -r '.messages[].id'
197
+ NWM5AYGx_FIHWT2_QbBr-whe-bIE8rbZunzr5RhXGaihvQ43z2qcxcqFgVRwi7A5C-ADmohv7TjXfYbDEIHZPQ==
198
+ ```
199
+
200
+ If a prefix isn't in your local cache (e.g. copied from another machine), run the matching list command first or use the full ID. Ambiguous prefixes (two cached IDs share the first 8 chars) exit `4` with both candidates listed.
201
+
202
+ ## Configuration
203
+
204
+ Credentials and connection settings resolve in this order: **a flag overrides the profile-scoped env var (`PROTON_<PROFILE>_X`), which overrides the plain env var (`PROTON_X`).** See [Profiles](#profiles-multi-account).
205
+
206
+ ### Environment variables
207
+
208
+ | Variable | Description |
209
+ |---|---|
210
+ | `PROTON_USER` | Proton account email |
211
+ | `PROTON_PASSWORD` | Account password (required for encrypted operations) |
212
+ | `PROTON_TOTP` | TOTP code (if 2FA is enabled) |
213
+ | `PROTON_API_URL` | API base URL (default: `https://mail.proton.me/api`) |
214
+ | `PROTON_APP_VERSION` | App version header (default: `Other`) |
215
+
216
+ ### Profiles (multi-account)
217
+
218
+ A profile is just a name. Each profile has its own session file (`~/.config/proton-cli/sessions/<profile>.json`) and its own set of profile-scoped environment variables. Select the active profile with the `--profile` flag or the `PROTON_PROFILE` environment variable (the flag wins; both fall back to `default`):
219
+
220
+ ```bash
221
+ proton-cli --profile work mail messages list
222
+ # or make it the default for your shell session:
223
+ export PROTON_PROFILE=work
224
+ proton-cli mail messages list
225
+ ```
226
+
227
+ For every setting, the active profile is consulted **scoped-first, then unscoped**: `PROTON_<PROFILE>_X` takes precedence over the plain `PROTON_X`. `<PROFILE>` is the profile name upper-cased, with any non-alphanumeric character replaced by `_` (so `work` becomes `WORK`, `my-work` becomes `MY_WORK`). This applies to every env-backed setting (`USER`, `PASSWORD`, `TOTP`, `API_URL`, `APP_VERSION`):
228
+
229
+ ```bash
230
+ export PROTON_PROFILE=work
231
+ export PROTON_WORK_USER=alice@company.com
232
+ export PROTON_WORK_PASSWORD=work-password
233
+ proton-cli mail messages list # uses PROTON_WORK_*, falling back to PROTON_*
234
+ ```
235
+
236
+ Only the per-profile session file is written to disk; all other wiring lives in flags and the environment.
237
+
238
+ ## Usage
239
+
240
+ The examples below are representative, not exhaustive. Every command lists its full flags with `--help`, e.g. `proton-cli mail messages send --help`.
241
+
242
+ | Area | Subcommands |
243
+ |---|---|
244
+ | `mail messages` | list, search, read, send, unschedule, trash, delete, move, mark, star, unstar |
245
+ | `mail conversations` | list, search, read, trash, delete, move, mark, star, unstar, attachments |
246
+ | `mail attachments` | list, download |
247
+ | `mail labels` | list, create, update, delete |
248
+ | `mail filters` | list, create, update, enable, disable, delete |
249
+ | `mail addresses` | list |
250
+ | `drive items` | list, info, upload, download, rename, move, copy, trash, delete, revisions |
251
+ | `drive folders` | create |
252
+ | `drive share` | status, link, unlink, add, remove |
253
+ | `drive invitations` | list, accept, reject |
254
+ | `drive trash` | list, restore, empty |
255
+ | `drive photos` | list, upload, download, trash, delete, favorite, unfavorite, albums |
256
+ | `calendar calendars` | list, create, rename, delete |
257
+ | `calendar events` | list, get, create, update, respond, delete |
258
+ | `contacts` | list, get, create, update, delete, pin-key, unpin-key, groups |
259
+ | `pass items` | list, get, create, edit, trash, restore, delete |
260
+ | `pass vaults` | list, create, rename, delete |
261
+ | `pass alias` | options, create |
262
+ | `settings` | get, mail, set |
263
+ | `api` | any endpoint (GET / POST / PUT / DELETE) |
264
+
265
+ <details>
266
+ <summary><b>Mail</b></summary>
267
+
268
+ ```bash
269
+ # Messages
270
+ proton-cli mail messages list --folder inbox --unread
271
+ proton-cli mail messages search --keyword "invoice"
272
+ proton-cli mail messages search --from "amazon" --after 2026-01-01
273
+ proton-cli mail messages read REF # body + attachments footer
274
+ proton-cli mail messages read --format text|html|raw REF
275
+ proton-cli mail messages read --body-only REF > body.txt
276
+ proton-cli mail messages send --to a@ex.com --cc c@ex.com --subject Hi --body Hello
277
+ proton-cli mail messages send --to to@ex.com --subject Hi --body "<b>Hi</b>" --html
278
+ proton-cli mail messages send --to to@ex.com --subject Hi --body Hi --attach ./report.pdf
279
+ proton-cli mail messages send --to to@ex.com --subject Hi --body "<b>Hi</b>" --html --attach-inline ./logo.png # embed an image inline in the HTML body
280
+ proton-cli mail messages send --to to@ex.com --subject Hi --body Hi --send-at 2026-05-01T09:00 # local time; prints the message ID + confirms the schedule
281
+ proton-cli mail messages list --folder scheduled # queued scheduled sends
282
+ proton-cli mail messages unschedule REF # cancel a scheduled send (moves it back to Drafts)
283
+ proton-cli mail messages send --to to@ex.com --subject Hi --body Hi --expires 7d
284
+ proton-cli mail messages send --to bob@gmail.com --subject Hi --body secret --eo-password hunter2 # password-protect for non-Proton recipients
285
+ echo "body" | proton-cli mail messages send --to foo --subject bar --body -
286
+ proton-cli mail messages trash REF...
287
+ proton-cli mail messages delete REF... # permanent
288
+ proton-cli mail messages move --dest archive REF...
289
+ proton-cli mail messages mark read|unread REF
290
+ proton-cli mail messages star REF
291
+ proton-cli mail messages unstar REF
292
+
293
+ # Batch filters (union with any explicit REFs)
294
+ proton-cli mail messages trash --unread --older-than 30d
295
+ proton-cli mail messages move --dest archive --from "newsletter@" --older-than 7d
296
+ proton-cli mail messages delete --folder spam --all
297
+ # Combine filters, --limit, --all: proton-cli mail messages trash --help
298
+
299
+ # Conversations (full threads; same verbs as messages)
300
+ proton-cli mail conversations list --folder sent --unread
301
+ proton-cli mail conversations read CONV_ID # full thread, chronological
302
+ proton-cli mail conversations read --summary CONV_ID # one line per message
303
+ proton-cli mail conversations read --strip-quotes CONV_ID
304
+ proton-cli mail conversations attachments list CONV_ID
305
+ proton-cli mail conversations attachments download CONV_ID --all --output-dir ./atts/
306
+
307
+ # Attachments
308
+ proton-cli mail attachments list MESSAGE_ID
309
+ proton-cli mail attachments download MESSAGE_ID ATT_ID --output ./file.pdf
310
+ proton-cli mail attachments download MESSAGE_ID --all --output-dir ./atts/
311
+ proton-cli mail attachments download MESSAGE_ID ATT_ID --output - # stdout
312
+ # --force, --include-inline, auto-suffix on collision: proton-cli mail attachments download --help
313
+
314
+ # Labels and folders
315
+ proton-cli mail labels list
316
+ proton-cli mail labels create --name "Important" --color "#8080FF"
317
+ proton-cli mail labels create --name "Projects" --folder --parent PARENT_LABEL_ID
318
+ proton-cli mail labels update LABEL_ID --name "Renamed" --color "#DB60D6"
319
+ proton-cli mail labels delete LABEL_ID
320
+
321
+ # Filters (Sieve)
322
+ proton-cli mail filters list
323
+ proton-cli mail filters create --name "Archive invoices" \
324
+ --sieve 'require ["fileinto"]; if header :contains "Subject" "invoice" { fileinto "Archive"; }'
325
+ proton-cli mail filters enable|disable FILTER_ID
326
+ proton-cli mail filters delete FILTER_ID
327
+
328
+ # Addresses
329
+ proton-cli mail addresses list
330
+ ```
331
+
332
+ </details>
333
+
334
+ <details>
335
+ <summary><b>Drive</b></summary>
336
+
337
+ ```bash
338
+ # Items
339
+ proton-cli drive items list /Documents
340
+ proton-cli drive items info /Documents/report.pdf # type, size, checksum, sharing
341
+ proton-cli drive items upload ./report.pdf /Documents
342
+ proton-cli drive items upload --recursive ./folder /Backup
343
+ proton-cli drive items upload - /Notes/note.txt # from stdin
344
+ proton-cli drive items download /Documents/report.pdf --output ./report.pdf
345
+ proton-cli drive items download /Documents/report.pdf --output-dir ./out/ # keep original name
346
+ proton-cli drive items download /Photos/pic.jpg --output - # to stdout
347
+ proton-cli drive items rename /Documents/old.txt new.txt
348
+ proton-cli drive items move /Documents/report.pdf /Archive
349
+ proton-cli drive items copy /Documents/report.pdf /Archive
350
+ proton-cli drive items trash /Documents/old.pdf # to trash (reversible)
351
+ proton-cli drive items delete /Documents/secret.txt # permanent
352
+ proton-cli drive items revisions list /Documents/report.pdf
353
+ proton-cli drive items revisions restore /Documents/report.pdf REVISION_ID
354
+
355
+ # Batch filters
356
+ proton-cli drive items trash --pattern "*.tmp" --scope / --recursive
357
+ proton-cli drive items delete --larger-than 100MB --scope /Backups --recursive # permanent
358
+ proton-cli drive items trash --older-than 90d --scope /Logs --recursive
359
+
360
+ # Folders
361
+ proton-cli drive folders create /Documents/NewFolder
362
+
363
+ # Sharing - public links
364
+ proton-cli drive share status /Documents/report.pdf # who has access + public link
365
+ proton-cli drive share link /Documents/report.pdf # create/show the public link
366
+ proton-cli drive share link /Documents/report.pdf --edit --expires 7d --password hunter2
367
+ proton-cli drive share unlink /Documents/report.pdf
368
+
369
+ # Sharing - members (invite Proton users)
370
+ proton-cli drive share add /Documents/report.pdf bob@proton.me --edit
371
+ proton-cli drive share remove /Documents/report.pdf bob@proton.me
372
+
373
+ # Incoming share invitations
374
+ proton-cli drive invitations list
375
+ proton-cli drive invitations accept|reject INVITATION_ID
376
+
377
+ # Trash
378
+ proton-cli drive trash list
379
+ proton-cli drive trash restore LINK_ID...
380
+ proton-cli drive trash empty # across all volumes
381
+
382
+ # Photos
383
+ proton-cli drive photos list
384
+ proton-cli drive photos list --tags favorites # filter by tag (favorites, screenshots, videos, …)
385
+ proton-cli drive photos upload ./IMG_0001.jpg
386
+ proton-cli drive photos download PHOTO_LINK_ID --output-dir ./pics/
387
+ proton-cli drive photos trash PHOTO_LINK_ID... # to trash (reversible)
388
+ proton-cli drive photos delete PHOTO_LINK_ID... # permanent
389
+ proton-cli drive photos favorite PHOTO_LINK_ID... # mark as favorite (album-only photos are copied to your timeline)
390
+ proton-cli drive photos unfavorite PHOTO_LINK_ID... # remove from favorites
391
+ proton-cli drive photos albums list
392
+ proton-cli drive photos albums create --name "Holiday"
393
+ proton-cli drive photos albums add ALBUM_LINK_ID PHOTO_LINK_ID...
394
+ proton-cli drive photos albums items ALBUM_LINK_ID
395
+ ```
396
+
397
+ </details>
398
+
399
+ <details>
400
+ <summary><b>Calendar</b></summary>
401
+
402
+ ```bash
403
+ # Calendars
404
+ proton-cli calendar calendars list
405
+ proton-cli calendar calendars create --name "Work" --color "#8080FF"
406
+ proton-cli calendar calendars rename CALENDAR_ID --name "Personal" --color "#DB60D6"
407
+ proton-cli calendar calendars delete CALENDAR_ID # requires PROTON_PASSWORD
408
+
409
+ # Events
410
+ proton-cli calendar events list --calendar "Work" --start 2026-04-15 --end 2026-04-20
411
+ proton-cli calendar events get CALENDAR_ID EVENT_ID
412
+ proton-cli calendar events get "Meeting" # search by title
413
+ proton-cli calendar events create \
414
+ --title "Meeting" --location "Vienna" --description "Quarterly sync" \
415
+ --start "2026-04-16T14:00" --duration 1h
416
+ proton-cli calendar events create --title "Standup" --start 2026-04-16T09:00 \
417
+ --rrule "FREQ=WEEKLY;COUNT=10" --remind 15m --remind 1h # recurrence + reminders
418
+ proton-cli calendar events create --title "Review" --start 2026-04-16T14:00 \
419
+ --attendee alice@proton.me --attendee bob@example.com # externals get an emailed invite
420
+ proton-cli calendar events update CALENDAR_ID EVENT_ID --title "Updated"
421
+ proton-cli calendar events respond CALENDAR_ID EVENT_ID --status accept # reply to an invitation (accept|tentative|decline)
422
+ proton-cli calendar events respond "Meeting" --status decline # by title; emails the organizer a REPLY
423
+ proton-cli calendar events delete CALENDAR_ID EVENT_ID
424
+ ```
425
+
426
+ </details>
427
+
428
+ <details>
429
+ <summary><b>Contacts</b></summary>
430
+
431
+ ```bash
432
+ proton-cli contacts list
433
+ proton-cli contacts get REF # ID or search
434
+ proton-cli contacts create --name "John Doe" --email john@example.com --phone "+1234567890"
435
+ proton-cli contacts create --name "Jane" --email a@ex.com --email b@ex.com \
436
+ --title "CTO" --birthday 1990-01-01 --address "Vienna" --url https://jane.example
437
+ proton-cli contacts update --email "new@example.com" REF
438
+ proton-cli contacts delete REF
439
+
440
+ # Pinned keys - encrypt mail to a specific PGP key you trust for a contact
441
+ proton-cli contacts pin-key REF --key bob-pubkey.asc # pin & auto-encrypt to it
442
+ proton-cli contacts pin-key REF --email bob@ex.com --key - # armored key from stdin; pick which email
443
+ proton-cli contacts unpin-key REF
444
+
445
+ # Contact groups
446
+ proton-cli contacts groups list
447
+ proton-cli contacts groups create --name "Team" --color "#8080FF"
448
+ proton-cli contacts groups add GROUP_ID REF...
449
+ proton-cli contacts groups remove GROUP_ID REF...
450
+ proton-cli contacts groups delete GROUP_ID
451
+ ```
452
+
453
+ </details>
454
+
455
+ <details>
456
+ <summary><b>Pass</b></summary>
457
+
458
+ ```bash
459
+ # Items
460
+ proton-cli pass items list --vault "Work"
461
+ proton-cli pass items get SHARE_ID ITEM_ID
462
+ proton-cli pass items get "github.com" # search
463
+ proton-cli pass items create --type login --name "GitHub" --username me --password secret \
464
+ --url github.com --totp "otpauth://..."
465
+ proton-cli pass items create --type note --name "My Note" --note "Some text"
466
+ proton-cli pass items create --type credit-card --name "Visa" --holder "Roman" --number "4111..." --expiry "2028-12"
467
+ proton-cli pass items create --type wifi --name "Home" --ssid MyNet --password pw --security WPA2
468
+ proton-cli pass items create --type ssh-key --name "laptop" --public-key "ssh-ed25519 ..." \
469
+ --private-key "$(cat id_ed25519)"
470
+ proton-cli pass items create --type identity --name "Me" --full-name "Jane Roe" --email jane@ex.com
471
+ proton-cli pass items create --type custom --name "Server" --field "Host=1.2.3.4" --hidden "Root PW=secret"
472
+ proton-cli pass items create --type login --name X --field "Recovery=abc" # custom fields on any type
473
+ proton-cli pass items edit REF --password "new-secret"
474
+ proton-cli pass items trash REF
475
+ proton-cli pass items restore REF
476
+ proton-cli pass items delete REF
477
+
478
+ # Batch filters
479
+ proton-cli pass items trash --vault "Old" --type login
480
+ proton-cli pass items trash --older-than 1y --type login
481
+ proton-cli pass items delete --vault "Temporary" --all
482
+
483
+ # Vaults
484
+ proton-cli pass vaults list
485
+ proton-cli pass vaults create --name "Work"
486
+ proton-cli pass vaults rename SHARE_ID --name "Personal"
487
+ proton-cli pass vaults delete SHARE_ID
488
+
489
+ # Aliases
490
+ proton-cli pass alias options
491
+ proton-cli pass alias create --prefix my-alias --mailbox my-mailbox@proton.me
492
+ ```
493
+
494
+ </details>
495
+
496
+ <details>
497
+ <summary><b>Settings</b></summary>
498
+
499
+ ```bash
500
+ proton-cli settings get # account settings
501
+ proton-cli settings mail # mail settings
502
+ proton-cli settings set # list the writable mail-setting keys
503
+ proton-cli settings set view-mode 1 # 0=conversations, 1=messages
504
+ proton-cli settings set draft-type text/html
505
+ proton-cli settings set hide-remote-images 1
506
+ ```
507
+
508
+ </details>
509
+
510
+ <details>
511
+ <summary><b>Raw API</b></summary>
512
+
513
+ For any endpoint not covered by a high-level command:
514
+
515
+ ```bash
516
+ proton-cli api GET /drive/volumes
517
+ proton-cli api POST /calendar/v1 --body '{"Name":"Work",...}'
518
+ proton-cli api GET /mail/v4/messages --query Page=0 --query PageSize=10
519
+ proton-cli api GET /calendar/v1 --output json | jq '.Calendars[].ID'
520
+ ```
521
+
522
+ See [API reference](#api-reference) for the full endpoint spec.
523
+
524
+ </details>
525
+
526
+ ## Scripting
527
+
528
+ proton-cli is built to compose in shell pipelines.
529
+
530
+ ```bash
531
+ # stdout is the new ID on create - capture it directly
532
+ LABEL=$(proton-cli mail labels create --name Work --color "#8080FF")
533
+
534
+ # JSON + jq for full IDs and fields
535
+ proton-cli mail messages list --output json | jq -r '.messages[].id'
536
+
537
+ # exit codes drive control flow (0 ok · 3 not-found · 4 ambiguous)
538
+ if ! proton-cli contacts get "jane"; then
539
+ echo "no unique match (exit $?)"
540
+ fi
541
+
542
+ # streaming: pipe a Drive file straight into another tool
543
+ proton-cli drive items download /report.pdf --output - | gpg --encrypt --recipient me ...
544
+
545
+ # preview any mutation first
546
+ proton-cli mail messages trash --unread --older-than 30d --dry-run
547
+ ```
548
+
549
+ ## How it works
550
+
551
+ 1. **Session creation** - creates an unauthenticated session via `POST /auth/v4/sessions`.
552
+ 2. **SRP authentication** - Secure Remote Password login with [go-srp](https://github.com/ProtonMail/go-srp), with 2FA/TOTP support.
553
+ 3. **Session persistence** - per profile, saves the auth tokens plus the salted key password **encrypted** with a random client key held server-side. The key password is never written to disk in cleartext, and revoking the session makes the saved blob undecryptable. See [Security](#security).
554
+ 4. **Key hierarchy** - unlocks User key → Address keys → per-service keys (Calendar, Drive, Contacts).
555
+ 5. **End-to-end encryption** - encrypts/decrypts using [gopenpgp](https://github.com/ProtonMail/gopenpgp).
556
+ 6. **Auto-refresh** - refreshes expired tokens automatically.
557
+
558
+ ### Encryption details
559
+
560
+ | Service | Encrypt with | Sign with |
561
+ |---|---|---|
562
+ | Calendar events | Calendar key (session key) | Address key |
563
+ | Drive files | Node key (session key per block) | Address key |
564
+ | Drive names | Parent node key | Address key |
565
+ | Contacts | User key | User key |
566
+ | Mail | Session key | Address key |
567
+ | Pass items | AES-256-GCM (item key) | N/A (symmetric) |
568
+ | Pass vaults | AES-256-GCM (vault key) | N/A (symmetric) |
569
+
570
+ ## Human verification (CAPTCHA)
571
+
572
+ Proton's anti-bot may demand a CAPTCHA at login. proton-cli opens a small webview window via an embedded helper, you solve it, and the original command retries automatically. No extra install is needed - the helper is `//go:embed`-ded into release binaries.
573
+
574
+ - **Linux desktop** needs `libwebkit2gtk-4.1` and `libgtk-3` installed.
575
+ - **macOS / Windows** need nothing (system WebKit / WebView2).
576
+ - **Headless** environments (server, container, no GUI) can't display the webview, so proton-cli exits with an error - run the command on a desktop machine instead.
577
+ - **`go install` builds** don't embed the helper. Install a [release binary](#install) if you hit a CAPTCHA.
578
+
579
+ ## Security
580
+
581
+ proton-cli saves a per-profile session file at `~/.config/proton-cli/sessions/<profile>.json` (mode `0600`). The salted key password that unlocks your PGP keys is stored **encrypted** with a random 256-bit client key that lives server-side, so:
582
+
583
+ - the key password is never written to disk in cleartext, and
584
+ - revoking the session (from the Proton apps) makes a leaked copy of the file undecryptable.
585
+
586
+ The file still contains the session refresh token, so treat it as a secret. proton-cli is unaudited; see [`SECURITY.md`](SECURITY.md) for the full storage model, the vulnerability-reporting process, and hardening recommendations.
587
+
588
+ ## Limitations
589
+
590
+ A few constraints are inherent to Proton's design or platform:
591
+
592
+ - **Colors** - labels, folders, calendars, and contact groups accept only Proton's 20 fixed accent colors; the CLI validates `--color` and lists the allowed values on error.
593
+ - **Calendar deletion** - `calendar calendars delete` is password-scoped and needs `PROTON_PASSWORD`.
594
+ - **Search lag** - `search` and `list` read Proton's eventually-consistent server-side index; a just-sent or just-deleted message can take a few seconds to appear or disappear. Confirm a mutation by ID with `read` rather than re-searching a subject.
595
+ - **CAPTCHA** - can't be solved headlessly, and `go install` builds don't embed the helper (see [Human verification](#human-verification-captcha)).
596
+
597
+ See [`docs/limitations.md`](docs/limitations.md) for the full list, including features not yet implemented.
598
+
599
+ ## Development
600
+
601
+ Requires [devbox](https://www.jetify.com/devbox) and [direnv](https://direnv.net/):
602
+
603
+ ```bash
604
+ direnv allow
605
+ go build . # quick build
606
+ just lint # gofmt + golangci-lint
607
+ just build # release-shaped binary (embeds the CAPTCHA helper)
608
+ ```
609
+
610
+ Tests are integration tests that run against the live Proton API and require `PROTON_USER` / `PROTON_PASSWORD`.
611
+
612
+ ## API reference
613
+
614
+ See [`openapi.yaml`](openapi.yaml) for the complete API spec covering ~740 endpoints. To regenerate from the latest Proton source:
615
+
616
+ ```bash
617
+ cd scripts && npm install && npm run generate-openapi
618
+ ```
619
+
620
+ See [`scripts/README.md`](scripts/README.md) for details on the generator.
621
+
622
+ ## License
623
+
624
+ MIT
package/bin/proton-cli.exe CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@roman-16/proton-cli-win32-x64",
3
- "version": "1.9.7",
3
+ "version": "1.9.8",
4
4
  "description": "proton-cli native binary for win32-x64",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/roman-16/proton-cli",