Logins, notes, cards, SSH keys, identities, aliases and two-factor codes in Proton Pass. Items are decrypted on your machine with the vault and item keys.
This page is what people actually do. For every command and flag, see the reference: items, vaults, aliases, links, sharing, shared, invitations, trash, breaches, settings, import and export.
An item takes two IDs to address, written as one token: SHARE_ID/ITEM_ID. A name or URL works instead.
proton pass items list --vault Work
proton pass items get github.com # by name or URL
proton pass items totp github.com # the current two-factor code
proton pass generate --length 32 # a new password, made locally
proton pass generate --words 4 # or a passphraseget prints the item's fields, including the password and the TOTP secret, to stdout. Pass stores the secret rather than the code, so totp is what works the current code out, and it reports how long that code has left.
A listing carries no secret. items list, aliases list, trash list and shared list show what an item is and where it lives, in every format including JSON. The password, the card, the keys and the hidden fields are what items get is for.
generate reaches no account and needs no session. The alphabet leaves out i, o, l and their capitals unless letters are all the password may contain. Every character kind you ask for is guaranteed to appear, and a length too short to hold one of each is refused.
--words N makes a passphrase instead: capitalised words, each followed by a digit, joined by --separator.
Every type takes --name, and optionally --vault, --note and --field NAME=VALUE.
proton pass items create --name GitHub --username roman --url github.com --generate-password
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 Visa --holder "Roman L" --expiry 2028-12 \
--secret-file number=/run/secrets/pan --secret-file cvv=/run/secrets/cvv
proton pass items create --type wifi --name Home --ssid MyNetwork --security WPA2 --secret-file password=/run/secrets/wifi
proton pass items create --type ssh-key --name laptop --public-key "$(cat ~/.ssh/id_ed25519.pub)" \
--secret-file private-key=~/.ssh/id_ed25519
proton pass items create --type identity --name Me --full-name "Jane Roe" --email jane@example.com --city Vienna
proton pass items update github.com --secret-file password=/run/secrets/github
pass-store show github | proton pass items update github.com --secret-file password=-Types are login (the default), note, credit-card, wifi, ssh-key, identity, alias and custom. Identity stores thirty-one fields, which the reference lists.
update takes the same flags as create and leaves anything you do not pass alone.
A secret is never a flag value. The secret parts of an item come from a file or from stdin, the way the account password does.
--secret-file NAME=FILEcan be given as often as you like.--secret-file NAME=-reads that one from standard input. Only one thing per run may read it.
NAME is one of the item's own secret fields - password, totp-uri, number, cvv, pin, private-key - or any other name, which makes a hidden custom field of it.
A value that is an otpauth:// URI is stored as a two-factor field rather than a hidden one.
--generate-password means the common case needs no file at all. The password is made on your machine, stored, and printed beside the new item's ID rather than into it. It takes the same shaping flags as proton pass generate, so --words 5 stores a passphrase.
A field can name the heading it sits under, in the same token:
proton pass items create --type custom --name Router \
--field "Network/SSID=home" --secret-file "Network/Key=/run/secrets/wifi" \
--field "Admin/URL=http://192.168.0.1" --secret-file "Admin/Password=/run/secrets/router"A field is identified by its section and name together, so Network/Password and Admin/Password are two fields.
Only the types whose Pass editor offers headings can carry them: custom, ssh-key, wifi and identity.
Files live on an item, so putting one there is an edit of the item.
proton pass items create --type note --name Passport --attach ~/scans/passport.pdf
proton pass items update Passport --attach ~/scans/visa.pdf --detach passport.pdf
proton pass items attachments list Passport
proton pass items attachments download Passport passport.pdf --dest ~/passport.pdf
proton pass items attachments download Passport --dest-dir ~/scans # all of them
proton pass items attachments update Passport passport.pdf --name passport-2031.pdfAttachments need a paid Pass plan. Without one, --attach is refused before anything is uploaded. So is a file larger than the plan allows, and a set of files with more in it than your Pass storage has left.
--attach and --detach repeat. An attachment is named by its own name or by its ID, and a name the item does not have is refused before the edit.
items get shows what an item carries. A listing does not.
A detached file is kept, and can be put back:
proton pass items attachments list Passport --removed
proton pass items attachments restore Passport passport.pdfAttachments are not part of an item's version history. items revisions restore puts the fields back and leaves the files as they are.
A login can carry passkeys: credentials a site registered so that it signs you in with no password at all.
proton pass items passkeys list github.com
proton pass items passkeys remove github.com romanThey are made between the site and the browser, so there is no way to add one from here. items get shows which a login carries; passkeys list shows the domain, the username, when it was made and on what, and --output json adds the site's own name, the name it shows you as, the note and the build of Pass that made it.
A passkey is named by its username or by its ID. Taking one off writes a new version of the item, so items revisions restore puts it back - but the site keeps its half of the credential either way, and will still offer to sign you in with a passkey this account no longer holds.
A login whose only way in is a passkey has no password to check, so items list --risk missing-2fa leaves it out.
proton pass items move github.com --into WorkThe item keeps its history and everything it holds, but gets a new ID, which is printed on stdout.
proton pass items trash github.com
proton pass trash restore github.com
proton pass items delete github.com # permanent
proton pass items trash --older-than 1y --type login --dry-rundelete and trash empty are permanent, so they show what would go and ask first. So does a filtered trash, since the filter chose the items rather than you. See Dry runs and confirmations.
proton pass vaults create --name Work
proton pass vaults update Work --description "Shared team logins" --icon star --color teal
proton pass vaults delete Work # by name, or by share IDIcons and colours are named, and Tab offers them: ten colours from violet to teal, and thirty icons from home to cheque.
Deleting a vault takes everything in it, so it names the vault and asks first.
To keep an item at the top of the list, run proton pass items pin github.com.
Hide-my-email addresses that forward to your own mailboxes.
proton pass settings domains list # the suffixes an alias can take
proton pass settings mailboxes list # where it can forward to
proton pass aliases create --prefix shop --mailbox me@proton.meProton makes the address from your prefix, a random word of its own, and the suffix. It picks a new word every time and only settles when the alias is made, so creating one tells you what it made:
✓ Created alias "shop" as shop.jasmine329@passinbox.com.
An alias is an item, so it is read and edited like one:
proton pass items get shop
proton pass items update shop --mailbox work@proton.me # where its mail arrives
proton pass items update shop --display-name "Jane R" # what recipients seeWhen an address starts attracting spam, switch it off rather than delete it. A disabled alias keeps its address and stops receiving; deleting it burns the address for good.
proton pass aliases disable shopAn alias forwards mail to you, but a reply would leave from your real address and give it away. A contact is the answer: Proton mints a second address standing for one correspondent, and mail you send there reaches them as though the alias had written it.
proton pass aliases contacts create shopping seller@example.com --name "The seller"
proton pass aliases contacts list shopping # WRITE TO shows the address
proton pass aliases contacts block shopping seller@example.comproton pass settings mailboxes create me@example.com
proton pass settings mailboxes verify me@example.com --code 123456
proton pass settings mailboxes delete me@example.com --transfer-to other@example.comA new mailbox receives nothing until it answers. Proton emails it a code, and verify is where that code goes back. resend sends another and retires the one before it.
Deleting a mailbox needs somewhere for its aliases to go, which is what --transfer-to names. It is required: without it, those aliases would stop receiving mail.
You can share a vault, or one item out of it. Both read the same way, and the same way Drive's sharing does.
proton pass vaults share add Work jane@proton.me --access editor
proton pass vaults share get Work
proton pass vaults share update Work jane@proton.me --access manager
proton pass vaults share remove Work jane@proton.me
proton pass items share add github.com jane@proton.me
proton pass items share get github.com # members, invitations and links
proton pass items share remove github.com jane@proton.meSharing a vault shares everything in it. Sharing one item lets the person open that item and nothing else in the vault.
--access is viewer, editor or manager. share get shows the people who accepted as members and the rest as invited. update and remove act on the address whichever it turns out to be.
Offer it to any address. Proton emails one without an account an invitation to create one.
proton pass vaults share add Work sam@example.com
proton pass vaults share get Work
proton pass vaults share confirm Work sam@example.comNothing reaches them until they have an account and you run share confirm. share get says which it is:
$ proton pass vaults share get Work
Name: Work
Member: you@proton.me (owner)
Invited: sam@example.com (viewer, waiting for a Proton account)
Invited: kim@example.com (editor, ready to confirm)confirm is refused while they read waiting for a Proton account. Nothing tells you when that changes, so check with share get.
items share takes the same three commands.
proton pass vaults transfer Work jane@proton.meThey have to be a member already, and only the owner can do it. Afterwards you are a manager like anybody else, so this is the one change to a vault you cannot undo on your own.
proton pass invitations list # what people have offered you
proton pass invitations accept Work
proton pass shared list # items other people share with you
proton pass sharing list # items you share with other people
proton pass vaults list # your vaults, with how many members each hasFor a vault, you can read its name and item count before accepting; what is in it stays sealed until you accept. An item offered on its own shows no preview at all.
An item somebody shared with you is in no vault of yours, so items list does not show it. shared list has it, addressed by the ID that listing shows, or by name.
A link that shows one item to somebody with no Proton account. The item stays encrypted, and a key made for the link is what opens it.
proton pass links create github.com --expires 7d
proton pass links create github.com --expires 24h --views 1
proton pass links list
proton pass links get 5bH2mQxK
proton pass links revoke 5bH2mQxKThe URL is the secret. The key travels in the part after the #, which a browser never sends to the server, so anyone holding the whole URL can read the item until the link expires or is revoked.
--expires is required. A link nobody remembered to revoke is how one of these goes wrong, and there is no sensible default for how long a secret should outlive its reason.
create writes the URL to stdout and the warning to stderr, so LINK=$(proton pass links create … --expires 7d) captures the link alone.
list shows what links exist and leaves the URLs out. To read one back, use links get, or items share get for the links on one item. So a link you mislaid is recovered rather than revoked and made again.
proton pass export --dest pass-backup.zip --passphrase-file ~/.backup-passphrase
proton pass import pass-backup.zip --passphrase-file ~/.backup-passphraseThe archive is the one Proton Pass itself writes, so the app opens what this writes and this opens what the app wrote.
It holds the vaults you own, and the attachments on their items. A vault somebody shared with you is theirs to back up and stays out. When something is left out, the command says how much on stderr.
--no-attachments writes the items alone, which is much faster.
Without a passphrase the archive holds every password in plain text, and the command says so as it writes. With one, the document is encrypted to it and stored as data.pgp, which Proton Pass can import. The attachments are never encrypted, with a passphrase or without.
The passphrase comes from a file, from stdin with --passphrase-file -, or from a prompt. Never from a flag value.
Reading a backup back keeps what it says about each item: the dates it was made and last changed on, and the trash, so an item that was in the trash goes back to the trash.
An alias address belongs to the account Proton gave it to. One from your own backup comes back if you have since deleted it; one from another account, or one you still hold, is named and skipped while everything else lands.
proton pass export --format csv --dest pass.csv
proton pass export --format json --dest - | jq '.vaults[].name'--format |
Holds | Encrypted with a passphrase |
|---|---|---|
zip |
Every item and its attachments | Yes |
json |
Every item, no attachments | Yes |
csv |
One row per item | No |
A CSV leaves out custom fields, attachments, passkeys and the keys of SSH items. It is in Proton Pass's own columns, so the app and pass import both read it back. --passphrase-file with --format csv is refused.
proton pass import bitwarden-export.json --manager bitwarden
proton pass import chrome-passwords.csv --manager chrome --vault Personal--manager names the program that wrote the file:
--manager |
Export it reads |
|---|---|
1password |
.1pux, .1pif, or a .zip of either |
apple-passwords, safari |
CSV |
bitwarden |
JSON, or a .zip with the attachments |
brave, chrome, edge |
CSV |
dashlane |
CSV, or a .zip of one CSV per kind of item |
enpass |
JSON, attachments included |
firefox |
CSV |
kaspersky |
TXT |
keepass |
XML |
keeper, nordpass, roboform |
JSON or CSV |
lastpass |
CSV |
proton-pass |
The archive, the document inside it, or the CSV (the default) |
Logins, notes, cards, identities, SSH keys, networks and custom items come across with their custom fields and one-time codes. Attachments come from 1Password, Bitwarden and Enpass, and need a paid Pass plan.
A vault, folder or group in the file becomes a vault of that name, made if it is not there. Items in none land in your first vault. --vault puts everything into the one you name.
Importing adds items. Nothing in a file says which existing item it was, so importing the same file twice puts the items in twice. Use --dry-run to list what would land, and where.
On a plan with a vault limit, the items of a vault that will not fit are named before anything is sent, and --vault is the way to bring them in anyway.
Pass can be protected with an extra password of its own, on top of your Proton account password. The first pass command in a session asks for it:
$ proton pass items list
Extra password:
ID TYPE NAME USERNAME MODIFIED
…One answer covers the session, not the command. Proton grants it for as long as the session lives, so nothing asks again on this machine until you sign out or the session expires.
Nothing else in proton is affected. Mail, Drive, Calendar and Contacts never ask for it.
For a run with nobody to ask, hand it to the sign-in instead:
proton account login --user me@proton.me \
--password-file /run/secrets/proton \
--extra-password-file /run/secrets/proton-passA pass command that needs it and finds nobody to ask says so and names that flag. Like every other secret it is read from a file, from stdin with --extra-password-file -, or from a prompt.
A few wrong answers end the session, so read a refusal rather than retrying blindly.
proton pass settings extra-password get
proton pass settings extra-password enable
proton pass settings extra-password disableenable asks for the password twice, or reads it once from --extra-password-file or --extra-password-file -. It needs at least eight characters. Keep it safe: without it nothing opens Pass, on any device. Your other devices ask for it the next time they open Pass, and this session goes on working.
disable asks for the password first. Pass then opens with your account password alone, on every device, and this session goes on working.
To change it, turn it off and on again.
proton pass items revisions list github.com # every edit, newest first
proton pass items revisions get github.com 3 # one version, decrypted
proton pass items revisions restore github.com 3Pass keeps every edit, so a password changed by mistake can be read back. A revision written under a key this account no longer holds is still listed by its number.
revisions restore writes that version as the newest one, so nothing in the history is lost. It changes the item's fields; attachments are left as they are.
proton pass items list --risk reused # which logins share a password
proton pass items list --risk weak
proton pass items list --risk missing-2fa # a site offers a code and you store none
proton pass items list --risk compromised # the password has leaked somewhereThis is Pass Monitor's password health. Each check keeps only the logins that fail it and adds a RISK column saying what was found. Logins sharing one password carry the same number, so two pairs do not read as one group of four. Anything you excluded from Proton's security checks is left out of all of them.
--risk weak is proton'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 compromised is the only check that reaches the network. It sends the first six hexadecimal characters of each password's SHA-1 to credential-check.protonweb.com, never the password and never the whole hash, and asks one question per password you have stored.
No check prints a password. proton pass items get is still the only command that does.
proton pass breaches list # worst first
proton pass breaches get jane@proton.me
proton pass breaches create me@example.com # watch an address you own elsewhere
proton pass breaches verify me@example.com --code 123456
proton pass breaches disable jane.work@proton.mebreaches is Pass Monitor's other half: which of your addresses have turned up in somebody else's data breach, when, and what was exposed. If a password leaked in the clear it shows the last few characters, which is what tells you which one to change.
Three kinds of address are watched, shown in the TYPE column: proton for the ones on your account, alias for the hide-my-email aliases in your vaults, and custom for the ones you added. Listing the aliases reads your vaults, so breaches list costs what items list costs.
STATE says what has to happen next. An address you added is unverified until you hand back the code Proton emailed it with verify; resend sends the code again. Until then Proton is not watching it, so get, enable and disable refuse. paused means you told Proton to stop watching, which enable undoes.
delete removes an address you added, and its breach history with it. To stop Proton watching one of your own addresses or an alias, use disable. Pausing an alias also leaves it out of the password checks above, which is the same switch.