# Pass 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](items.md), [vaults](vaults.md), [aliases](aliases.md), [links](links.md), [sharing](sharing.md), [shared](shared.md), [invitations](invitations.md), [trash](trash.md), [breaches](breaches.md), [settings](settings.md), [import and export](pass.md). An item takes two IDs to address, written as one token: `SHARE_ID/ITEM_ID`. A name or URL works instead. ## Find and read ```bash 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. `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`. ```bash 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-stdin password ``` Types are `login` (the default), `note`, `credit-card`, `wifi`, `ssh-key`, `identity`, `alias` and `custom`. Identity stores thirty-one fields, which the [reference](items.md) 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-stdin NAME` reads one of them from the stream. Only one thing per run may read stdin. `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: ```bash 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. ```bash 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: ```bash 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. ```bash 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 ```bash 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 ```bash 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](../using/confirmations.md). ## Vaults ```bash proton pass vaults create --name Work proton pass vaults update Work --description "Shared team logins" --icon 7 --color 3 proton pass vaults delete Work # by name, or by share ID ``` Icons and colours are numbers. 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`. ## Aliases Hide-my-email addresses that forward to your own mailboxes. ```bash proton pass aliases options # available suffixes and mailboxes 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: ```bash 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 ``` 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. ```bash 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. ```bash 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 ```bash 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. ## 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. ```bash 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. ```bash 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: ```console $ 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 ```bash 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 ```bash 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. ```bash 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 ```bash 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**, 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-stdin`, 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 ```bash 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 ```bash 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](https://proton.me/support/pass-extra-password) of its own, on top of your Proton account password. The first `pass` command in a session asks for it: ```console $ 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: ```bash 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-stdin`, 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 ```bash 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-stdin`. 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. ## History ```bash 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 ```bash 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. 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. ## Breaches ```bash 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.