Naming what to act on

Wherever a command's usage shows REF, you can name the thing in four ways. Use whichever you already have.

proton mail messages get 5bH2mQxKT9wLpN4v…    # the full ID
proton mail messages get 5bH2mQxK             # the short ID a list printed
proton mail messages get "Invoice #2291"      # the subject
proton contacts get jane                      # a name or an address

If nothing matches, the command exits 3. If more than one thing matches, it prints the candidates and exits 4:

$ proton contacts get jane
Error: "jane" matches 2 contacts.
Try:   narrow the term, or use one of:
         7Kd91mQx  jane@example.com
         3Ns8pT2v  jane.roe@work.example

Short IDs

On a terminal, lists shorten Proton’s IDs to eight characters and remember what they showed you. Paste one straight back into the next command.

Short IDs carry no ellipsis and never start with a dash, so they copy cleanly out of a table and your shell reads them as-is.

In scripts, IDs are always full. Pipes, redirects, --output json and --output yaml all emit complete IDs, so no script ever sees a truncated value. To turn shortening off interactively too, pass --full-ids.

A short ID only works on the machine that printed it. The lookup table lives in ~/.config/proton-cli/idcache/<profile>.json. If you copied one from elsewhere, run the matching list here first, or use the full ID.

Tab completion

With completion installed, Tab completes every command, every flag, and the values a flag accepts: item types, output formats, setting keys, colours, icons.

A REF completes from what your listings showed you - the short ID, and the subject, name or address beside it. So does a flag whose value names one of your things:

$ proton pass items list --vault ⇥
Work      -- 5bH2mQxK
Personal  -- 9xL4pQrT

--folder, --label, --parent, --vault, --calendar, --album, --computer, --shared, --mailbox, --suffix and --into all complete this way, and --folder and the mail --into offer the built-in folders too. In Drive, --into takes a path.

$ proton mail conversations list
ID        FROM                       SUBJECT                                MESSAGES  DATE
ketTSogw  Gastronaut Reservierungen  Reservation Confirmation - Vero Sushi          1  2026-08-31 19:31

$ proton mail conversations get ket⇥
ketTSogw  -- Reservation Confirmation - Vero Sushi

The subject completes too. Your shell decides between them by what you have already typed:

$ proton mail messages get Invo⇥
Invoice #2291 is ready  -- 5bH2mQxK

$ proton contacts get jane⇥
Jane Doe          -- QmxLp2Rt
jane@example.com  -- QmxLp2Rt

It offers only what this machine has seen. A collection you have not listed yet has nothing to offer, and says which listing would fill it:

$ proton pass items get ⇥
Nothing seen yet - run `proton pass items list` first

Two IDs in one

A Pass item and a calendar event each need two IDs, written as one slash-separated token. Lists print them this way, and you paste them back the same way. Short IDs work on both halves at once.

proton pass items get SHARE_ID/ITEM_ID
proton calendar events get CALENDAR_ID/EVENT_ID

One occurrence of a recurring event

A recurring event is stored once and happens many times. To name a single occurrence, add its own start time after an @.

proton calendar events get 4f2a1b9c@2026-04-16T09:00   # one occurrence
proton calendar events get 4f2a1b9c                    # the whole series

Keep the @ part to act on that occurrence. Drop it to act on the series. Add --onwards to act on one occurrence and every later one.

Drive uses paths

Files and folders are named by their path:

proton drive items get /Documents/report.pdf
proton drive items move /Documents/report.pdf --into /Archive

Some things in Drive have no place in the tree, so they have no path: a trashed item, a photo, an album. Name those by the REF their list showed.

proton drive trash restore 7Kd91mQx
proton drive photos download 3Ns8pT2v --dest-dir ./photos

A computer, an item somebody shared with you and a public link somebody sent you each hold a tree of their own. Name the tree with --computer REF, --shared REF or --link URL, and everything in it by path from its root:

proton drive items list /Documents --computer "Work laptop"
proton drive items download /report.pdf --shared Project --dest-dir .
proton drive items list / --link 'https://drive.proton.me/urls/7X2K9M3N1P#kQ81mDx4T9wL'

A message behind a password

A password-protected message is in no mailbox, so it has no REF. Its usage shows LINK, and either the link you were sent or the id in it names it:

proton mail protected get 9fK2pQ7xNv4mB8 --eo-password-file /run/secrets/jane
proton mail protected get 'https://mail.proton.me/eo/9fK2pQ7xNv4mB8' --eo-password-file -

Full IDs that start with a dash

Proton’s IDs are base64, and - is one of its characters, so about one ID in sixty-four starts with a dash. Paste them like any other reference:

proton pass items get -x76EpiVSJf2oHzHgyC2D_jF8O…==/_fb26gvMWjnM7US4_wpTNm_LqI…==
proton contacts delete -bJxDLEMvt-Z6t4Yna7V8SYQ_F…==

Put your flags before such an ID. Everything after it is read as another argument.

proton mail messages attachments download --dest-dir ./files -bJxDLEMvt-…==   # works
proton mail messages attachments download -bJxDLEMvt-…== --dest-dir ./files   # does not

Short IDs need none of this. Their eight characters begin after any leading dashes, so flags can go on either side.

Filters and bulk changes - naming many things at once
Dry runs and confirmations - checking a selection before it happens