Pass

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.

Find and read

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 passphrase

get 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.

When an item was last used

items get shows when an item was created, last changed and last used. Last Used is when a Pass app last filled the item in, and shows for logins, cards and identities. Reading an item with proton does not count as using it.

proton pass items list --sort used --desc     # the most recently used first

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.

Create and edit

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.

Secrets

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=FILE can 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.

Sections

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.

Attachments

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.pdf

Attachments 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.pdf

Attachments are not part of an item’s version history. items revisions restore puts the fields back and leaves the files as they are.

Passkeys

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 roman

They 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.

Move it

proton pass items move github.com --into Work

The item keeps its history and everything it holds, but gets a new ID, which is printed on stdout.

Trash and delete

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-run

delete 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.

Vaults

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 ID

Icons 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 a vault

proton pass vaults hide Archive
proton pass vaults unhide Archive

A hidden vault is left out of items list, the trash, aliases list, sharing list, the password checks and breaches list, and looking an item up by name does not search it. items list --vault Archive still lists it, and an item’s ID still reaches it. vaults list shows every vault, and says which are hidden.

• trash empty leaves the trash of a hidden vault alone.
• A new item without --vault goes to your first vault that is not hidden.
• Only you stop seeing it: hiding a shared vault changes nothing for its other members.

Aliases

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.me

Proton 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 see
proton pass items update shop --clear-display-name

An alias brought in from SimpleLogin can carry a note of SimpleLogin’s own, which items get shows as SimpleLogin Note.

proton pass items update shop --simplelogin-note "Bike shop, 2024"
proton pass items update shop --clear-simplelogin-note

That note is not end-to-end encrypted, and an alias without one cannot be given one. --note is the encrypted note every item has, and aliases create --note sets it on a new alias.

When 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 shop

Reply as an alias

An 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.com

Where aliases arrive

proton 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.com

A 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.

Your own domain for aliases

On a paid Pass plan, aliases can be made on a domain you own.

proton pass settings domains create example.com
proton pass settings domains get example.com           # the DNS entries, and which ones Proton sees
proton pass settings domains update example.com --default

A new domain carries no alias until its DNS entries are in place. get shows every entry the domain needs, checks them again each time it runs, and says what it found where an entry is wrong. Ownership and MX are what a domain needs to carry aliases; SPF, DKIM and DMARC keep its mail out of spam. list shows each custom domain with its STATUS: unverified, unconfigured, or active.

Once the domain is verified, three things can be set on it:

proton pass settings domains update example.com --catch-all me@proton.me --catch-all work@proton.me
proton pass settings domains update example.com --catch-all none
proton pass settings domains update example.com --display-name "Jane Roe"
proton pass settings domains update example.com --random-prefix

With a catch-all, mail sent to any name at the domain makes an alias for that name as it arrives, forwarding to the mailboxes named. --display-name is what recipients see on mail from the domain’s aliases, and --clear-display-name takes it off.

--default makes new aliases take a domain when nothing names another, and works for Proton’s domains too. --default=false leaves none chosen.

Deleting a domain deletes every alias made on it. The command names the count and asks first.

Sharing

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.me

Sharing 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.

Share with somebody who is not on Proton

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.com

Nothing 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.

Hand a vault over

proton pass vaults transfer Work jane@proton.me

They 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.

What is shared, and by whom

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 has

For 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.

Secure links

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 5bH2mQxK

The 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.

Backups

proton pass export --dest pass-backup.zip --passphrase-file ~/.backup-passphrase
proton pass import pass-backup.zip --passphrase-file ~/.backup-passphrase

The 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, hidden or not, 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.

Other layouts to export to

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.

Moving from another password manager

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.

An extra password

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-pass

A 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.

Turn the extra password on or off

proton pass settings extra-password get
proton pass settings extra-password enable
proton pass settings extra-password disable

enable 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.

Access tokens

On a paid Pass plan, a token lets a program into Pass without your password: Proton’s pass-cli, or an AI agent working through it.

proton pass settings access-tokens create --name ci --expires 30d --vault Work
proton pass settings access-tokens list
proton pass settings access-tokens get ci
proton pass settings access-tokens update ci --vault Work --vault Personal
proton pass settings access-tokens delete ci

A token reads the vaults it is handed and nothing else. --name, --expires and at least one --vault are required; --expires is between 1h and 1y. update names the whole set of vaults, so one left out is taken back.

The token is shown once, when it is made. Copy it then: get shows the token’s name and vaults and never the token itself, and one you have lost is deleted and made again. Under --output json it is the secret field:

TOKEN=$(proton pass settings access-tokens create --name ci --expires 30d --vault Work --output json | jq -r .secret)

A token for an AI agent

proton pass settings access-tokens create --name agent --expires 1d --vault Work --agent
proton pass settings access-tokens activity list agent

--agent marks a token for an AI agent, which then has to give a reason for every action it takes. activity list shows them, newest first: what was done, to which item, and why.

History

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 3

Pass 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.

Check your passwords

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 somewhere

This 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. A login you excluded 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.

Exclude a login from the checks

proton pass items exclude "Router admin"
proton pass items list --excluded              # every login you excluded
proton pass items include "Router admin"

Only logins can be excluded, and only in a vault you may edit. items get shows Monitor: excluded on one. An alias’s address is watched or not with breaches enable and breaches disable, which is the same switch.

Breaches

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.me

breaches 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.

Pause every alias at once

proton pass breaches disable --type alias
proton pass breaches enable --type alias

This needs a paid Pass plan. --type proton does the same for the addresses on your account. While a kind is paused, every address of it lists as paused, and none can be switched on its own. Resuming leaves the ones you paused one at a time paused. Addresses you added are paused one at a time.

Mark breaches resolved

proton pass breaches resolve jane@proton.me

Every current breach of the address is marked resolved, and get shows each one’s state. They cannot be reopened in Pass. A breach found later is reported as new. Resolving needs a plan that includes the detail of each breach.

The breaches of the addresses on your account are also listed one by one in Dark Web Monitoring.