pass stores each password as a separate GPG-encrypted file in a directory tree. That is the entire design.

~/.password-store/
├── email/
│   ├── fastmail.gpg
│   └── work.gpg
├── servers/
│   └── vps01.gpg
└── banking/
    └── example-bank.gpg

No database, no proprietary format, no service. gpg -d on any of those files returns the contents, which means the data outlives the tool.

Setting up

You need a GPG key first:

gpg --full-generate-key       # choose ECC or RSA 4096
gpg --list-secret-keys --keyid-format LONG

sudo apt install pass
pass init "YOUR_KEY_ID"
pass git init

pass git init makes the store a Git repository. Every change is committed automatically, which gives you a full history of your password changes and the ability to recover an old one.

Daily use

pass insert email/fastmail          # prompts, hidden input
pass insert -m servers/vps01        # multiline

pass email/fastmail                 # print to terminal
pass -c email/fastmail              # clipboard, cleared after 45s
pass                                # show the whole tree
pass find bank                      # search names
pass grep "username: colton"        # search decrypted contents

pass edit email/fastmail
pass rm email/fastmail
pass mv email/old email/new

pass -c is what you want by default. It clears the clipboard after 45 seconds, limiting the window during which something else can read it. Our clipboard guide covers why that matters, and specifically why a clipboard manager with history can undermine it.

Multi-line entries

Convention is password on the first line, everything else after:

pass insert -m servers/vps01

correct-horse-battery-staple
user: deploy
host: vps01.example.com
port: 2222
url: https://panel.example.com
otpauth://totp/vps01?secret=BASE32SECRET

The first line is what pass -c copies, so the rest can be arbitrary notes without interfering.

pass servers/vps01 | sed -n '2,$p'    # everything but the password

Generating

pass generate email/newsite 32
pass generate -n email/newsite 20     # no symbols, for sites that reject them
pass generate -c email/newsite 32     # generate and copy
pass generate -i email/existing 32    # replace only the first line

-i matters for an existing multi-line entry: without it, generate replaces the whole file and loses your notes.

Sync

The store is a Git repository containing only encrypted files, so the remote sees nothing readable.

pass git remote add origin git@github.com:you/password-store.git
pass git push -u origin main

pass git pull
pass git log --oneline

pass git runs Git commands in the store directory, so everything from our Git basics guide applies.

Recovering an old password:

pass git log -p email/fastmail        # encrypted, but shows when it changed
pass git checkout HEAD~3 -- email/fastmail.gpg
pass email/fastmail

Being able to recover a password you changed last week and then discovered something still needed is genuinely useful.

TOTP

sudo apt install pass-extension-otp
pass otp insert servers/vps01
pass otp -c servers/vps01

Whether to keep TOTP codes alongside passwords is a real question. It collapses two factors into one: anything that compromises your password store has both.

The argument for is that the store is encrypted with a key held only by you, so the second factor still protects against a compromised website, which is the threat it primarily addresses. The argument against is that it is no longer meaningfully two-factor for an attacker on your machine.

Keeping TOTP on a separate device is stronger. Keeping it in pass is considerably better than not using TOTP at all.

Sharing with a team

pass init -p servers/shared KEY_ID_1 KEY_ID_2 KEY_ID_3

That subtree is encrypted to three keys, so any of those three people can decrypt it. Adding someone means re-encrypting:

pass init -p servers/shared KEY1 KEY2 KEY3 KEY4

Removing someone re-encrypts without their key, and it does not retroactively protect anything they already read. Rotate the secrets when someone leaves.

This is a legitimately good model for a small team, because access control is cryptographic rather than enforced by a server you have to trust.

Browser and mobile

Browser: browserpass for Firefox and Chromium, which needs a native host component installed alongside the extension.

Android: Password Store works well, clones the Git repository, and supports autofill.

iOS: support exists and is noticeably weaker.

If mobile access is central to how you use passwords, this is where pass gets harder to recommend. Bitwarden or KeePassXC with a sync service will be less friction.

The honest limitations

Filenames are not encrypted. Anyone with access to the store sees banking/example-bank.gpg and knows you bank there. The password is safe and the metadata is not. For some threat models that is disqualifying.

tree ~/.password-store    # this is all visible

Losing the GPG key loses everything. No recovery, no vendor, no reset. Back the key up separately and offline, before you start relying on this:

gpg --export-secret-keys --armor YOUR_KEY_ID > key-backup.asc
# then put this somewhere offline and safe, not in the password store

GPG is awkward. Key management, agent configuration, expiry. Our GPG basics guide covers it, and it is more friction than a password manager that handles this for you.

No form filling beyond the browser extension, no breach monitoring, no password health reports.

Who it suits

Someone who already uses GPG and Git, works primarily on Linux, wants their secrets in a format that will still be readable in twenty years, and is comfortable with the metadata tradeoff.

For that person it is excellent: fast, scriptable, syncable anywhere, and dependent on no company continuing to exist.

For someone who wants a password manager to be invisible and work identically on a phone, KeePassXC offers a single encrypted database with no metadata leakage and good mobile clients, and Bitwarden is open source with a self-hostable server if you want the convenience without the vendor. Both are entirely reasonable choices, and using any password manager is what matters most.

Frequently Asked Questions

How does pass store passwords?

Each entry is a separate file encrypted with GPG, arranged in an ordinary directory tree under ~/.password-store. There is no database and no custom format, so any GPG implementation can decrypt an entry and the directory structure is visible with ls.

Is it a problem that the directory structure is not encrypted?

It is a real tradeoff. Anyone with access to the store sees which sites you have accounts on, even though they cannot read the passwords. If that metadata matters for your threat model, pass is the wrong tool and an encrypted database such as KeePassXC is a better fit.

How do I sync pass between machines?

The password store is a Git repository, so you push and pull it like any other. Since every file is already encrypted, the remote can be any Git host without exposing anything, and pass git is a wrapper that runs Git commands in the store directory.

What happens if I lose my GPG key?

Every entry becomes permanently unreadable. There is no recovery mechanism and no vendor to appeal to. Back up your GPG private key separately from the password store, ideally on offline media, before you start relying on pass for anything important.

Can I use pass on Android or iOS?

Android has Password Store, which works well and includes autofill. iOS support exists but is considerably weaker. If mobile access matters a great deal, this is the point where a conventional password manager is the more practical choice.

How does pass handle the clipboard safely?

The -c flag copies a password to the clipboard and clears it automatically after 45 seconds by default. This limits the window in which a clipboard manager or another application can capture it, though a manager running with history enabled may still have stored it.