proton pass items

Every command under proton pass items, with the arguments and flags it takes. For these commands in use, see the pass guide.

Holds attachments, create, delete, exclude, get, include, list, move, passkeys, pin, revisions, share, totp, trash, unpin and update.

attachments

Files attached to an item.

Holds download, list, restore and update.

attachments download

Download and decrypt attachments.

Naming an attachment downloads that one; naming none downloads them all. An attachment is named by its own name or by its ID.

Existing files are never overwritten silently: a collision becomes “file (2).pdf” unless –force says otherwise.

proton pass items attachments download REF [ATTACHMENT_REF]

proton pass items attachments download github.com --dest-dir .
proton pass items attachments download github.com passport.pdf --dest ~/passport.pdf

Flag	Description
--dest string	Write to this path, or - for stdout
--dest-dir string	Write into this directory, keeping each item’s own name
--force	Overwrite a file that already exists

attachments list

List an item’s attachments.

–removed lists the files taken off the item instead, which are the ones attachments restore can bring back.

proton pass items attachments list REF

proton pass items attachments list github.com
proton pass items attachments list github.com --removed

Flag	Description
--removed	List what was taken off the item rather than what is on it

attachments restore

Put a removed attachment back on an item.

ATTACHMENT_REF is the name or ID attachments list --removed shows. A name that was removed more than once is refused, with the IDs to choose from.

proton pass items attachments restore REF ATTACHMENT_REF...

proton pass items attachments restore github.com passport.pdf

attachments update

Rename an attachment.

Renaming is update --name; there is no rename verb.

The item is not touched, so this adds nothing to its history.

proton pass items attachments update REF ATTACHMENT_REF

proton pass items attachments update github.com passport.pdf --name passport-2031.pdf

Flag	Description
--name string	New name for the file

create

Create an item.

A secret is read from a file, never from a flag value: –secret-file NAME=FILE, and - as the file reads standard input. NAME is cvv, number, password, pin, private-key, totp-uri, or any name at all, which makes a hidden custom field of it.

–generate-password makes one instead, so a new login needs no file: it is shaped by the same flags pass generate takes.

–attach puts a local file on the item, and needs a paid Pass plan.

proton pass items create

proton pass items create --name GitHub --username roman --url github.com --generate-password
proton pass items create --type note --name Passport --attach ~/scans/passport.pdf
proton pass items create --name Router --generate-password --words 5
proton pass items create --type note --name 'Door codes' --note 'Front: 1234'
proton pass items create --type credit-card --name 'Travel card' --holder 'Roman' --expiry 2030-04 --secret-file number=/run/secrets/card
proton pass items create --type custom --name Router --field 'Network/SSID=home' --secret-file 'Network/Key=/run/secrets/wifi'

Flag	Description
--address string	Set the address (identity)
--attach stringArray	Attach a local file (repeatable)
--birthdate string	Set the birthdate (identity)
--city string	Set the city (identity)
--company string	Set the company (identity)
--country string	Set the country (identity)
--county string	Set the county (identity)
--email string	Set the email address (login)
--expiry string	Set the card expiry, YYYY-MM (credit-card)
--facebook string	Set the facebook (identity)
--field stringArray	Set a custom field, as NAME=VALUE or SECTION/NAME=VALUE (repeatable)
--first-name string	Set the first name (identity)
--floor string	Set the floor (identity)
--full-name string	Set the full name (identity)
--gender string	Set the gender (identity)
--generate-password	Make the password rather than being given one
--holder string	Set the cardholder’s name (credit-card)
--instagram string	Set the instagram (identity)
--job-title string	Set the job title (identity)
--last-name string	Set the last name (identity)
--length int	How many characters (default 20)
--license-number string	Set the license number (identity)
--linkedin string	Set the linkedin (identity)
--middle-name string	Set the middle name (identity)
--name string	Set the item’s name
--no-digits	Leave the digits out
--no-symbols	Leave the symbols out
--no-uppercase	Leave the capitals out
--note string	Set the note
--organization string	Set the organization (identity)
--passport-number string	Set the passport number (identity)
--personal-website string	Set the personal website (identity)
--phone string	Set the phone (identity)
--postal-code string	Set the postal code (identity)
--public-key string	Set the public key (ssh-key)
--reddit string	Set the reddit (identity)
--second-phone string	Set the second phone (identity)
--secret-file stringArray	Read a secret field from a file, as NAME=FILE; - is stdin (repeatable)
--security string	Wi-Fi security (wifi): WPA, WPA2, WPA3, WEP
--separator string	What stands between the words of a passphrase: comma, digit, hyphen, period, space, symbol, underscore (default hyphen)
--social-security-number string	Set the social security number (identity)
--ssid string	Set the network name (wifi)
--state string	Set the state (identity)
--type string	What kind of item: login, note, credit-card, wifi, ssh-key, identity, alias, custom (default login)
--url string	Set the URL (login)
--username string	Set the username (login)
--vault string	Which vault, by name or ID (default: your first)
--website string	Set the website (identity)
--words int	Make a passphrase of this many words instead
--work-email string	Set the work email (identity)
--work-phone string	Set the work phone (identity)
--x-handle string	Set the x handle (identity)
--yahoo string	Set the yahoo (identity)

delete

Delete items permanently.

proton pass items delete [REF...]

proton pass items delete GitHub
proton pass items delete --vault Work --all --yes

Flag	Description
--all	Act on everything in scope, rather than a subset
--limit int	Most items to affect; 0 for no cap (default 150)
--newer-than string	Match items newer than DURATION
--older-than string	Match items older than DURATION (e.g. 30d, 2w, 1h)
--type string	Match only this kind of item: login, note, credit-card, wifi, ssh-key, identity, alias, custom
--vault string	Match only this vault, by name or ID

exclude

Leave logins out of Pass Monitor’s checks.

An excluded login is left out of every items list --risk check, and items list --excluded lists them. Only logins can be excluded: an alias’s address is watched or not with breaches enable and breaches disable.

proton pass items exclude REF...

proton pass items exclude 'Router admin'
proton pass items exclude 'Router admin' 'Printer admin'

get

Show one item, decrypted.

Passwords, TOTP secrets and private keys are printed in full. This is the only command that prints them; the listings do not.

Last Used is when a Pass app last filled the item in, and shows for logins, cards and identities. Reading an item with this program does not count.

proton pass items get REF

proton pass items get github.com
proton pass items get GitHub --output json

include

Bring logins back into Pass Monitor’s checks.

proton pass items include REF...

proton pass items include 'Router admin'

list

List items across your vaults.

Takes the same filters as trash and delete, so you can preview a selection here before acting on it. A hidden vault is left out unless –vault names it.

–sort used orders by when a Pass app last filled an item in. Reading one with this program does not count as using it.

–risk is Pass Monitor’s password health, and keeps only the logins that fail one check. A RISK column says what was found, numbering the logins that share one password so two pairs do not read as one group of four. A login excluded with items exclude is left out of all of them.

–risk weak is this program’s own reading: a password shorter than twelve characters, or shorter than sixteen and drawn from fewer than three of lowercase, uppercase, digits and symbols. Pass judges strength its own way, so the two can disagree.

–risk missing-2fa names the logins for sites that offer a time-based code and have neither a code nor a passkey stored against them.

–risk compromised asks a public corpus of leaked passwords whether yours are in it, one request per password you have stored. It is the only check that reaches the network, and it sends the first six hexadecimal characters of each password’s SHA-1 - one bucket in sixteen million - to credential-check.protonweb.com, never the password and never the whole hash.

–excluded keeps only the logins excluded from Pass Monitor, which no check looks at. items include brings one back.

No check prints a password; items get is still the only command that does.

proton pass items list

proton pass items list
proton pass items list --vault Work
proton pass items list --type login
proton pass items list --risk reused
proton pass items list --risk weak --vault Work
proton pass items list --risk missing-2fa
proton pass items list --risk compromised
proton pass items list --excluded
proton pass items list --sort used --desc

Flag	Description
--desc	Reverse the order
--excluded	Keep only the logins excluded from Pass Monitor
--limit int	How many items per page; 0 for all of them (default 50)
--newer-than string	Match items newer than DURATION
--older-than string	Match items older than DURATION (e.g. 30d, 2w, 1h)
--page int	Which page of results, counting from zero
--risk string	Keep only the logins failing this password check: compromised, missing-2fa, reused, weak
--sort string	Order by: name, type, modified, created, used (default name)
--type string	Match only this kind of item: login, note, credit-card, wifi, ssh-key, identity, alias, custom
--vault string	Match only this vault, by name or ID

move

Put an item in another vault.

The item keeps its history and everything it holds, but gets a new ID: an item in Pass is identified by its vault as well as itself. The new ID is printed on stdout.

proton pass items move REF

proton pass items move github.com --into Work

Flag	Description
--into string	Which vault to put it in, by name or ID

passkeys

Passkeys stored against a login.

Holds list and remove.

passkeys list

List the passkeys stored against a login.

A passkey signs in without a password, so a login that carries one may hold no password at all.

–output json carries what a row leaves out: the site’s own name, the name it shows you as, the passkey’s note, and the build of Pass that made it.

proton pass items passkeys list REF

proton pass items passkeys list github.com

passkeys remove

Take a passkey off a login.

PASSKEY_REF is the username or the ID passkeys list shows.

The site keeps its half of the credential, so it will still offer to sign you in with a passkey this account no longer holds.

Taking one off is a new version of the item, so items revisions restore puts it back.

proton pass items passkeys remove REF PASSKEY_REF...

proton pass items passkeys remove github.com roman

pin

Keep items at the top of the list.

proton pass items pin REF...

proton pass items pin github.com

revisions

Earlier versions of an item.

Holds get, list and restore.

revisions get

Show one earlier version, decrypted.

The password, TOTP secret and private key that revision held are printed in full, as items get prints the current ones.

Attachments are not part of a version: attachments list shows the ones on the item, and attachments list --removed the ones taken off it.

REVISION_REF is the number revisions list shows.

proton pass items revisions get REF REVISION_REF

proton pass items revisions get github.com 3

revisions list

Show what an item used to be.

Pass keeps every edit, so a password changed by mistake can be recovered. Newest first.

This says what changed and when. To read one revision back in full, use revisions get.

proton pass items revisions list REF

proton pass items revisions list github.com
proton pass items revisions list github.com --output json

revisions restore

Put an item back to an earlier version.

The version is added to the history as the newest one, so nothing is lost.

The item’s attachments are left as they are. To bring one back, use attachments restore.

REVISION_REF is the number revisions list shows.

proton pass items revisions restore REF REVISION_REF

proton pass items revisions restore github.com 3

share

Who else can open an item.

Holds add, confirm, get, remove and update.

share add

Offer one item to somebody, leaving the vault around it alone.

What travels is the item’s own key rather than the vault’s, so they can open that item and nothing else sealed under the same share.

EMAIL may be an address outside Proton. Proton emails them an invitation to create an account, and nothing reaches them until they have one and you run share confirm.

proton pass items share add REF EMAIL

proton pass items share add github.com jane@proton.me
proton pass items share add github.com jane@proton.me --access editor

Flag	Description
--access string	What they may do with it: viewer, editor, manager (default viewer)

share confirm

Let somebody into an item once they join Proton.

Use it for an address that had no Proton account when you offered it. It is refused until the account exists, and share get says who is ready. Afterwards they hold an ordinary invitation, which they still have to accept.

proton pass items share confirm REF EMAIL

proton pass items share confirm github.com jane@example.com

share get

Show how an item is shared: who holds it, who has been offered it, and the links made for it.

A link’s URL carries the key that opens the item, so this prints it in full - as links get does, and as a listing never does.

proton pass items share get REF

proton pass items share get github.com

share remove

Take somebody’s access to an item away.

It withdraws an invitation nobody answered, or removes a member who did.

proton pass items share remove REF EMAIL

proton pass items share remove github.com jane@proton.me

share update

Change what somebody may do with an item.

A member’s access changes in place. Somebody who has not answered yet has their offer withdrawn and made again at the new access, which sends them a fresh invitation.

proton pass items share update REF EMAIL

proton pass items share update github.com jane@proton.me --access viewer

Flag	Description
--access string	What they may do with it: viewer, editor, manager (default viewer)

totp

Print the current two-factor code for an item.

How long the code has left is reported beside it, so you can tell whether to wait for the next one.

For a script: –output json, then read .code.

proton pass items totp REF

proton pass items totp github.com
proton pass items totp github.com --output json

trash

Move items to the trash.

proton pass items trash [REF...]

proton pass items trash GitHub
proton pass items trash --vault Work --older-than 1y

Flag	Description
--all	Act on everything in scope, rather than a subset
--limit int	Most items to affect; 0 for no cap (default 150)
--newer-than string	Match items newer than DURATION
--older-than string	Match items older than DURATION (e.g. 30d, 2w, 1h)
--type string	Match only this kind of item: login, note, credit-card, wifi, ssh-key, identity, alias, custom
--vault string	Match only this vault, by name or ID

unpin

Stop keeping items at the top.

proton pass items unpin REF...

proton pass items unpin github.com

update

Change an item’s fields.

A secret is read from a file, never from a flag value: –secret-file NAME=FILE, and - as the file reads standard input. NAME is cvv, number, password, pin, private-key, totp-uri, or any name at all, which makes a hidden custom field of it.

–generate-password replaces the password with one it makes.

–attach puts a local file on the item, and needs a paid Pass plan. –detach takes one off by name or ID; it stays in the item’s history.

–simplelogin-note replaces the note an alias brought from SimpleLogin, and –clear-simplelogin-note removes it. That note is not end-to-end encrypted, and an alias without one is refused: –note is the encrypted one.

proton pass items update REF

proton pass items update GitHub --secret-file password=/run/secrets/github
proton pass items update GitHub --secret-file password=-
proton pass items update GitHub --username roman-16 --url github.com
proton pass items update GitHub --generate-password
proton pass items update Passport --attach ~/scans/visa.pdf --detach passport.pdf
proton pass items update shop --display-name 'Jane R'
proton pass items update shop --clear-display-name
proton pass items update shop --simplelogin-note 'Bike shop, 2024'
proton pass items update shop --clear-simplelogin-note

Flag	Description
--address string	Replace the address (identity)
--attach stringArray	Attach a local file (repeatable)
--birthdate string	Replace the birthdate (identity)
--city string	Replace the city (identity)
--clear-display-name	Remove the display name (alias)
--clear-simplelogin-note	Remove the SimpleLogin note (alias)
--company string	Replace the company (identity)
--country string	Replace the country (identity)
--county string	Replace the county (identity)
--detach stringArray	Remove an attachment, by name or ID (repeatable)
--display-name string	Replace the name recipients see on mail from it (alias)
--email string	Replace the email address (login)
--expiry string	Replace the card expiry, YYYY-MM (credit-card)
--facebook string	Replace the facebook (identity)
--field stringArray	Replace a custom field, as NAME=VALUE or SECTION/NAME=VALUE (repeatable)
--first-name string	Replace the first name (identity)
--floor string	Replace the floor (identity)
--full-name string	Replace the full name (identity)
--gender string	Replace the gender (identity)
--generate-password	Make the password rather than being given one
--holder string	Replace the cardholder’s name (credit-card)
--instagram string	Replace the instagram (identity)
--job-title string	Replace the job title (identity)
--last-name string	Replace the last name (identity)
--length int	How many characters (default 20)
--license-number string	Replace the license number (identity)
--linkedin string	Replace the linkedin (identity)
--mailbox stringArray	Replace where mail to it arrives (alias, repeatable)
--middle-name string	Replace the middle name (identity)
--name string	Replace the item’s name
--no-digits	Leave the digits out
--no-symbols	Leave the symbols out
--no-uppercase	Leave the capitals out
--note string	Replace the note
--organization string	Replace the organization (identity)
--passport-number string	Replace the passport number (identity)
--personal-website string	Replace the personal website (identity)
--phone string	Replace the phone (identity)
--postal-code string	Replace the postal code (identity)
--public-key string	Replace the public key (ssh-key)
--reddit string	Replace the reddit (identity)
--second-phone string	Replace the second phone (identity)
--secret-file stringArray	Read a secret field from a file, as NAME=FILE; - is stdin (repeatable)
--security string	Wi-Fi security (wifi): WPA, WPA2, WPA3, WEP
--separator string	What stands between the words of a passphrase: comma, digit, hyphen, period, space, symbol, underscore (default hyphen)
--simplelogin-note string	Replace the note SimpleLogin keeps beside the address (alias)
--social-security-number string	Replace the social security number (identity)
--ssid string	Replace the network name (wifi)
--state string	Replace the state (identity)
--url string	Replace the URL (login)
--username string	Replace the username (login)
--website string	Replace the website (identity)
--words int	Make a passphrase of this many words instead
--work-email string	Replace the work email (identity)
--work-phone string	Replace the work phone (identity)
--x-handle string	Replace the x handle (identity)
--yahoo string	Replace the yahoo (identity)

---

Every command also takes the flags that work everywhere.