Each password is a GPG-encrypted file under ~/.password-store/. The store is plain files in a folder hierarchy; no proprietary formats, no daemon.

1. Installation

Linux

macOS

brew install pass

2. GPG Key Setup

pass requires a GPG key. Skip this block if you already have one.

# Generate a new key (use RSA 4096 or ed25519)
gpg --full-generate-key
# List your keys — note the key ID or email
gpg --list-secret-keys --keyid-format LONG

The key ID looks like 3AA5C34371567BD2 or you can use the email you registered.

3. Initialise the Store

pass init "your@email.com"
# or using the key ID:
pass init 3AA5C34371567BD2

This creates ~/.password-store/ and a .gpg-id file.

Multiple GPG IDs are supported (for team use):

pass init alice@example.com bob@example.com

Use -p to scope a different GPG key to a subfolder (useful for shared stores):

pass init -p work/ work@company.com

Running pass init on an existing store re-encrypts all entries with the new key(s).

4. Data Organisation Convention

Store each entry as a multiline file with this structure:

url: https://example.com
username: you@example.com
notes: anything extra

• First line is always the password. pass -c and clipboard tools only

• Use lowercase keys (url:, username:, notes:) for compatibility with

• Organise with folders that mirror context, not the URL structure:

~/.password-store/
├── email/
│   ├── gmail
│   └── fastmail
├── dev/
│   ├── github
│   └── npm
└── finance/
    ├── bank-hsbc
    └── revolut

5. Daily Usage

List the store

pass                       # full tree
pass email/                # subtree
pass ls email/             # explicit alias

Find entries by name

pass find github           # lists all entries whose path matches "github"

Read a password

pass email/gmail           # print all lines to stdout
pass -c email/gmail        # copy line 1 to clipboard (clears after 45s)
pass -c2 email/gmail       # copy line 2 (e.g. the username) to clipboard

Search inside decrypted content

pass grep username         # grep across all decrypted entries
pass grep -i "amazon"      # case-insensitive; accepts any grep option

Insert an existing password

pass insert email/gmail              # prompted twice for confirmation
pass insert -e email/gmail           # echo password as you type (single prompt)
pass insert -m email/gmail           # multiline (recommended, ends with Ctrl-D)
pass insert -f email/gmail           # overwrite without prompt

Generate a new password

pass generate email/gmail            # 25-char password (default length)
pass generate email/gmail 20        # custom length
pass generate -n email/gmail 20     # no symbols
pass generate -c email/gmail 20     # copy to clipboard instead of printing
pass generate -i email/gmail 20     # replace only line 1, keep rest of file
pass generate -f email/gmail 20     # overwrite without prompt

Edit an entry

pass edit email/gmail      # opens $EDITOR; creates entry if it doesn't exist

Remove an entry

pass rm email/gmail
pass rm -r email/          # remove a folder recursively
pass rm -f email/gmail     # no confirmation prompt

Move / copy

pass mv email/gmail email/gmail-old
pass mv -f email/gmail email/gmail-old   # overwrite without prompt
pass cp email/gmail backup/gmail
pass cp -f email/gmail backup/gmail      # overwrite without prompt

6. Git Sync

Initialise git inside the store:

pass git init
pass git remote add origin git@github.com:you/pass-store.git

Every pass insert, generate, edit, rm automatically creates a git commit. Push and pull manually:

pass git push
pass git pull

To clone the store on another machine:

# Import your GPG key first:
gpg --import private-key.asc
gpg --edit-key your@email.com  # then: trust → 5 → quit
# Clone the store:
git clone git@github.com:you/pass-store.git ~/.password-store

7. Extensions

pass-otp (TOTP / 2FA codes)

# Install
pacman -S pass-otp          # Arch
brew install pass-otp       # macOS
# Add a TOTP secret (use the otpauth:// URI from your provider)
pass otp insert totp/github
# paste: otpauth://totp/GitHub:you@example.com?secret=BASE32SECRET&issuer=GitHub
# Generate a code
pass otp totp/github
# Copy to clipboard
pass otp -c totp/github

pass-import (migrate from another manager)

pip install pass-import    # or: pacman -S pass-import
# Import from Bitwarden (JSON export)
pass import bitwarden bitwarden-export.json
# Import from 1Password (1PUX export)
pass import 1password export.1pux
# List all supported formats
pass import --list

pass-update

# Install
git clone https://github.com/roddhjav/pass-update ~/.password-store/.extensions/update.bash
# Update a password interactively
pass update email/gmail

8. Shell Completion

# bash — add to ~/.bashrc
source /usr/share/bash-completion/completions/pass
# zsh — add to ~/.zshrc
autoload -U compinit && compinit
# fish — works out of the box after install

9. Useful Environment Variables

10. Troubleshooting

gpg: decryption failed: No secret key Your GPG key is not available. Import it with gpg --import and set trust.

gpg-agent keeps asking for passphrase Add to ~/.gnupg/gpg-agent.conf:

default-cache-ttl 3600
max-cache-ttl 14400

Clipboard does not clear on Wayland Install wl-clipboard and set PASSWORD_STORE_CLIP_TOOL=wl-copy or pass -c with wl-clipboard in PATH.

pass git shows dirty tree after clone Run pass git status; if only .gpg-id is untracked, run pass git add . and pass git commit -m "add gpg-id".