Filters and bulk changes

proton mail messages trash 5bH2mQxK 9xL4pQrT              # named
proton mail messages trash --from newsletter@example.com --older-than 90d   # described
proton mail messages trash 5bH2mQxK --unread --folder spam                  # both

The filters

Filter	What it matches
--folder · --scope · --vault	Where to look
--older-than · --newer-than	By age
--larger-than · --smaller-than	By size
--pattern	The name, against a glob
--keyword	Text in what a thing says, as well as what it is called
--read · --unread · --starred · --type	By state or kind
--all	Everything in scope, rather than a subset
--limit	How many a bulk verb may affect, or a listing holds

Each command’s own page lists the filters it takes. Mail adds --from, --to, --via, --subject, --has-attachments, --after and --before.

What --keyword reads inside things - a message body, a file’s text - is what an index on this machine holds: Local index.

Check a selection before acting on it

list takes the same filters as the verbs beside it, so you can see what matches first:

proton drive items list /Build --pattern "*.tmp" --recursive     # see what matches
proton drive items trash --scope /Build --pattern "*.tmp" --recursive   # act on it

list takes a path as its argument. Bulk verbs take --scope instead; their arguments name individual items.

You can also preview the change itself with --dry-run.

Something has to be selected

A command needs at least one reference or one filter:

$ proton mail messages trash
Error: Nothing selected.
Try:   pass a REF, or a filter such as --unread, --starred, --from, --subject or --older-than.
       Use --all to target a whole folder.

Limits

--limit defaults to 150 on a bulk verb: a guard against a mistyped filter, not a technical bound. A selection that fills it says so, --limit N reads as far as it takes to find N, and --limit 0 lifts the cap altogether.

Bulk verbs report Proton’s answer per item. Whatever was refused is named, and the count and the IDs in --output json report what actually landed.

A filter that matches a folder and the files inside it selects the folder alone.

Drive filters walk the tree. --pattern, --keyword and the size and age filters visit every folder under the scope, so over a large tree narrow it with --scope. With a drive index they are answered from this machine instead.

A filtered Drive listing shows each item’s full path.