pass - the standard Unix password manager

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

intent

pass is a minimal CLI password manager that stores each credential as a GPG-encrypted text file. use this skill when you need to set up or manage a Unix password store, generate or retrieve encrypted passwords, sync credentials across machines with git, handle TOTP codes, or migrate passwords from another manager. pass is for users who want passwords in version control without a centralized cloud service.

inputs

required before starting:

• a Unix-like system (Linux, macOS, BSD, WSL2)
• GPG installed and a GPG key pair (RSA 4096 or ed25519 recommended)
• the pass package installed via distro package manager or Homebrew
• (optional) git installed if you plan to sync the store
• (optional) wl-clipboard on Wayland systems if you need clipboard support

environment variables (optional, set in shell profile if needed):

• PASSWORD_STORE_DIR: override default store location (default: ~/.password-store)
• PASSWORD_STORE_KEY: default GPG key ID or email to encrypt with
• PASSWORD_STORE_CLIP_TIME: clipboard clear timeout in seconds (default: 45)
• PASSWORD_STORE_ENABLE_EXTENSIONS: set to true to load user extensions
• EDITOR: which text editor pass edit uses (default: $EDITOR or vi)
• PASSWORD_STORE_GIT: override git directory path (default: $PASSWORD_STORE_DIR)
• PASSWORD_STORE_CLIP_TOOL: clipboard command (default: xclip or pbcopy depending on OS)

external connections (optional):

• GitHub / GitLab SSH key pair if syncing the store to a remote git repo (requires SSH key auth setup)
• TOTP provider (Google, GitHub, AWS, etc.) if using pass-otp for 2FA

procedure

1. install pass

Linux:

• Arch / Manjaro: pacman -S pass
• Debian / Ubuntu: apt install pass
• Fedora / RHEL: dnf install pass
• openSUSE: zypper in password-store

macOS:

• brew install pass

output: pass --version prints the installed version (e.g., pass 1.7.4)

2. generate or import a GPG key

if you do not have a GPG key:

1. run gpg --full-generate-key
2. select RSA (3) and 4096 bits when prompted (or ed25519 for modern systems)
3. enter your name and email (this becomes the key identifier)
4. set a strong passphrase (you will type this when pass encrypts/decrypts)
5. wait for entropy collection

if you already have a key, list it:

gpg --list-secret-keys --keyid-format LONG

output: a key ID like 3AA5C34371567BD2 or the email you registered

3. initialise the password store

1. run pass init "your@email.com" (or use the key ID instead)
2. this creates ~/.password-store/ directory and a .gpg-id file

optional: multi-key setup for team sharing:

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

this encrypts all entries so both alice and bob can decrypt.

optional: scope a different key to a subfolder:

pass init -p work/ work@company.com

output: ~/.password-store/ directory exists with .gpg-id file containing the key fingerprint(s)

4. organise the password store with folders

create a folder hierarchy that mirrors your context, not website URLs. examples:

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

convention: each entry is a multiline text file with this structure:

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

the first line is always the password. pass -c only copies line 1 to clipboard. use lowercase keys (url:, username:, notes:) for compatibility with browser extensions and pass-import.

output: folder structure created manually with mkdir -p ~/.password-store/<category>/

5. list the store

view the full tree:

pass

view a subtree:

pass email/
pass ls email/

find entries by name (fuzzy search):

pass find github

output: stdout lists entry paths, one per line

6. read and copy passwords

print all lines of an entry:

pass email/gmail

copy line 1 (password) to clipboard:

pass -c email/gmail

clipboard auto-clears after 45 seconds (configurable with PASSWORD_STORE_CLIP_TIME)

copy a specific line (e.g. line 2, the username):

pass -c2 email/gmail

search decrypted content across all entries:

pass grep username
pass grep -i "amazon"

output: password printed to stdout or copied to clipboard; clipboard clears after timeout

7. insert a password manually

insert with confirmation prompt:

pass insert email/gmail

you are prompted to enter the password twice.

insert while echoing your input (single prompt):

pass insert -e email/gmail

insert in multiline mode (recommended for the metadata structure):

pass insert -m email/gmail

press Ctrl-D to finish.

overwrite an existing entry without prompt:

pass insert -f email/gmail

output: entry created at ~/.password-store/email/gmail.gpg

8. generate a new password

generate a 25-character random password (default):

pass generate email/gmail

generate with custom length:

pass generate email/gmail 20

generate without symbols (alphanumeric only):

pass generate -n email/gmail 20

generate and copy directly to clipboard:

pass generate -c email/gmail 20

generate and replace only the password (keep metadata):

pass generate -i email/gmail 20

generate and overwrite without prompt:

pass generate -f email/gmail 20

output: generated password printed to stdout or copied to clipboard; entry file updated

9. edit an entry

open in $EDITOR:

pass edit email/gmail

if the entry does not exist, it is created.

output: entry file updated with changes you made in the editor

10. remove entries

remove a single entry (with confirmation):

pass rm email/gmail

remove a folder recursively:

pass rm -r email/

remove without confirmation prompt:

pass rm -f email/gmail

output: entry or folder deleted from ~/.password-store/

11. move and copy entries

move an entry:

pass mv email/gmail email/gmail-old

move and overwrite without prompt:

pass mv -f email/gmail email/gmail-old

copy an entry:

pass cp email/gmail backup/gmail

copy and overwrite without prompt:

pass cp -f email/gmail backup/gmail

output: entry file moved or copied to the new path

12. initialise git sync

set up 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, mv, cp automatically creates a git commit.

push changes to remote:

pass git push

pull remote changes:

pass git pull

output: git repository initialized at ~/.password-store/.git; commits appear in git log

13. clone the store on another machine

prerequisites: the remote repo is already set up and your GPG key is available

1. import your GPG private key: gpg --import private-key.asc
2. set trust on the key: gpg --edit-key your@email.com, then type trust, select 5, then quit
3. clone the repo: git clone git@github.com:you/pass-store.git ~/.password-store

output: ~/.password-store/ directory populated with encrypted entries; decryption works with your imported GPG key

14. add TOTP / 2FA codes with pass-otp

install the extension:

• Arch: pacman -S pass-otp
• macOS: brew install pass-otp
• other: pip install pass-otp

add a TOTP secret (use the otpauth:// URI from your provider):

pass otp insert totp/github

paste the otpauth URI: otpauth://totp/GitHub:you@example.com?secret=BASE32SECRET&issuer=GitHub

generate a code:

pass otp totp/github

copy the code to clipboard:

pass otp -c totp/github

output: TOTP entry created at ~/.password-store/totp/github.gpg; running the command outputs a 6-digit code valid for 30 seconds

15. migrate passwords from another manager with pass-import

install the tool:

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 import formats:

pass import --list

output: entries created in ~/.password-store/ with folder structure inferred from the source manager

16. enable shell completion

bash , add to ~/.bashrc:

source /usr/share/bash-completion/completions/pass

zsh , add to ~/.zshrc:

autoload -U compinit && compinit

fish , works automatically after install

output: pass <TAB> completes entry names and subcommands

decision points

• if you do not have a GPG key: generate one with gpg --full-generate-key before running pass init. if you already have a key, skip generation and go straight to pass init.

• if you want to share the store with team members: use pass init alice@example.com bob@example.com so entries encrypt to multiple keys. if solo, use a single key.

• if you plan to sync the store across machines: set up git with pass git init and push to a remote repo. if you only use pass on one machine, skip git.

• if the clipboard does not work on Wayland: install wl-clipboard and ensure PASSWORD_STORE_CLIP_TOOL=wl-copy is set, or pass will try xclip and fail. on X11 or macOS, the default clipboard tools work out of the box.

• if gpg-agent keeps asking for a passphrase: increase the cache TTL in ~/.gnupg/gpg-agent.conf with default-cache-ttl 3600 and max-cache-ttl 14400, then restart the agent with gpgconf --kill gpg-agent.

• if you need TOTP codes for 2FA: install pass-otp and use pass otp insert to add secrets. if you only use passwords, skip this extension.

• if you are migrating from Bitwarden, 1Password, LastPass, or KeePass: use pass-import to automate the migration. if starting fresh, skip this step.

• if you want to update passwords interactively: install pass-update with git clone https://github.com/roddhjav/pass-update ~/.password-store/.extensions/update.bash. if you prefer editing manually, use pass edit instead.

output contract

a successful pass setup and workflow produces:

• store directory: ~/.password-store/ exists with a .gpg-id file at the root containing the GPG key fingerprint(s)
• entry files: each password is stored at ~/.password-store/<category>/<name>.gpg as a binary-encrypted file
• git repo (if syncing): .git/ directory exists inside ~/.password-store/ with commit history showing insert, generate, edit, and rm operations
• clipboard output: pass -c <entry> places the first line on the clipboard; the clipboard clears automatically after the timeout
• decryption: pass <entry> outputs plaintext to stdout only if the GPG key is available and unlocked
• imports: pass import <format> <file> creates entries with folder structure matching the source manager, or fails with an error if the format is unsupported
• TOTP codes (if using pass-otp): pass otp <entry> outputs a 6-digit code valid for 30 seconds, refreshing every 30 seconds

outcome signal

you know the skill worked when:

• pass lists your entire password store tree with no errors
• pass -c <entry> copies a password to your clipboard without prompting for your GPG passphrase (if the agent cached it) or prompts once and then succeeds
• pass generate <entry> 20 creates a new encrypted entry and prints the generated password
• pass edit <entry> opens your default text editor, you modify the entry, and save; the entry is re-encrypted and a git commit is created (if git is enabled)
• pass find <keyword> returns a list of matching entries instantly
• pass git push and pass git pull sync your store to a remote repo without auth errors
• pass otp <entry> outputs a valid TOTP code you can use to log in (if you set up pass-otp)
• pass import <format> <file> imports entries from another password manager with the correct folder structure and no decryption errors
• importing a cloned store on a new machine and running pass <entry> decrypts successfully after importing the GPG key