Everyone needs a password manager, even we who live in the world of CLI and TUI, maybe even more so. We require a safe place for all passwords, of course, but also keys and registration info of various sizes and types.

Pass is an easy-to-use and lightweight password store that keeps passwords inside gpg2-encrypted files in a directory, ~/.password-store. Using pass the user can add, remove, edit, synchronize, generate, and manipulate passwords and other secrets like tokens and multi-line log in data. It's basically a shell script.

Pass is capable of copying passwords to your clipboard and tracking password changes using git.

The community has produced GUIs and importers and extensions for pass.

What is pass

pass is built around a few core concepts:

GPG Encryption

pass uses GPG to encrypt passwords. GPG is a well-established encryption tool that provides strong security for your sensitive data. Each password file is encrypted using your GPG key, ensuring that only you (or someone with access to your GPG key) can decrypt and view the passwords.

Directory

Passwords and other stuff are stored in a hierarchical directory structure. This makes it easy to organize and find your credentials. You can have directories for different environments and, within each directory, many user credential files.

Plain Text

Although the files are encrypted, the underlying storage is in plain text. This simplicity allows for easy integration with other tools and scripts.

Examples

Show a list of password-store by issuing the command pass

Password Store
├── Business
│   ├── my-business-site.com
│   └── other-site.net
├── Email
│   ├── casaursus.net
│   └── gmail.com
├── PVE
│   ├── Pve1
│   │   └── token  
│   ├── Pve2
│   │   └── token
│   └── Pve3
│       └── token
└── boss
    ├── bank
    ├── email
    └── login

How to show a password

$ pass Email/casaursus.net
$ sup3r$tr0ng4ndC0mplicat3dPa$$w0rd=a_JOKE

How to copy a password to the clipboard

$ pass -c Email/casaursus.net
$ Copied Email/[email protected] to clipboard. Will clear in 45 seconds.

Install pass

We can use pass as a stand-alone. Or adding a Git repository (GitLab, GitHub, Bitbucket, or self-hosted Git storage) makes this fascinating and more useful.

Debian-based

sudo apt update && sudo apt install pass

Homebrew

brew install pass

Arch Linux

sudo pacman -S pass

Generate a GPG key

You need to create a GPG key if you do not have one. Make sure you have a strong GPG key. You can generate a new GPG key with the following command:

gpg --expert --pinentry-mode=loopback --full-gen-key

• Choose option 9 ECC and ECC,
• Choose option 1, Curve 25519,
• Enter e.g., 3y (valid for 3 years → o never expires); shorter is better
• Enter your name and email (or any email), but no comment
• Add a passphrase to secure the key pair

Or use a more basic gpg --full-generate-key. See the documentation.

Initialize

pass init "[email protected]"

mkdir: created directory ‘/home/user/.password-store’
Password store initialized for [email protected].

You will need that password to open your store.

Initialize using GIT

git pass git See this link for details.
Gives several benefits as GIT does. It can be local, or it can be linked to a repository and stored off-site on GitHub/GitLab … if you don't self-host a Git service.

You may want to add completion (bash/fish/zsh) from this location.

How to use pass

The main use cases are listed, but for more information, see the documentation. "Password" is used here as a general term for all that we have in the password-store.

List

passwords and other stored info pass ls

Add

Adding a password pass insert Sites/example.com
Add to a subdirectory pass insert -m API/pypi
Add a multiline thing pass insert -m snippet

Edit

Insert a new or edit a password using your editor pass edit special

Show or Copy a password

Show password pass Sites/example.com
Copy to clipboard pass -c Sites/example.com

Remove

Delete entry pass rm Sites/example.com

Generate

Generate a password pass generate Sites/anothersite.org
Generate and add to clipboard pass generate -c Sites/anothersite123.org

Git

Running Git commands uses pass git <command>

Find

pass search Site1
pass find token

Move

pass mv API/token Site1/API/token

Copy

pass cp Site1/password Site2/password

Grep

pass grep "email:"

Use pass with Git

Create a Git-powered password store

Type pass init <your key> and pass git init, and you have all the benefits of a local Git repository, e.g., if you delete the wrong password, you can restore it

Use a remote Git repository

This is an easy way of getting our passwords and tokens backed up, but also a tool to copy our password store to a new device.

Type pass git remote add origin [email protected]:example.com/pw-store.git
Use the correct address for your Git remote site.

Then you can push it by pass git push origin main

Clone the password-store to a new machine

On the new machine, clone the Git repository into a hidden directory, and we have the GPG-coded passwords on the new machine too.

• use git clone [email protected]:example.com/pw-store.git .password-store

We need the GPG key pair on the new machine.

• On the original machine, export the files
  • mkdir -p export/keys && cd export/keys and export both parts to it
• gpg --output public.pgp --armor --export <[email protected]>
• gpg --output private.pgp --armor --export-secret-key <[email protected]> it will ask for the passphrase.
• check for success type ls, output should be private.pgp public.pgp
• On the new machine
  • scp -r me@mypc:export/keys .
  • cd export/keys
  • gpg --import private.pgp It will ask for the passphrase
  • gpg --import public.pgp
  • To be able to encrypt new passwords, you need to edit the trust level
  • gpg --edit-key [email protected]
  • type trust and choose the max value 5

Change Expire Date for a GPG key

List the key gpg -K (--list-secret-keys) and copy the key you want to change

Edit that by key gpg --edit-key <key>, and:

• type expire
• set type your time, 0 = newer <n> y for number of years
• then save by typing save.

See the man page for full details.

Pass in your workflow

Pass is superb when integrating into our workflow.

Logging into a remote server/service

Using an alias: alias cus="ACCESS_KEY_ID=$(pass show cu/cus/access-id) SECRET_KEY=$(pass show cu/cus/token) cus"

Now I can run a custom service, “cus”, by cus run [email protected]

Using export

Using tokens, you do not want them in your shell history for security reasons.
export SERVER_TOKEN=$(pass show servers/api/token).

Usefull add-ones

You might like to add these

My usage includes OTP for 2FA using TOTP codes. From the CLI or piped into other commands or applications. You can include these features into a script; it just commands.

Pass-OTP

A pass extension for managing one-time-password (OTP) tokens.

Install

• On Debian: sudo apt && sudo apt -y install pass-extension-otp
• On macOS, Homebrew: brew install pass-otp
• Browser Support, passff >= 1.6.0 now supports using pass-otp to fill login forms. zx2c4 pass management extension for Mozilla Firefox. Pending Chrome port. An official signed version can be found on the Mozilla add-on page. This extension allows you to access your zx2c4 pass repository directly from your web browser. You can choose to automatically fill and submit login forms if a matching password entry is found. Add-on that allows users of the Unix password manager 'pass' to access their password store from Firefox. PassFF allows users of the Unix password manager pass password repository directly from Firefox. PassFF can be configured to autofill and autosubmit login forms when a matching password entry is found.

👍 Pass-OTP is one of the tools I use daily. I use ZBar to read various QR codes.

OATHtool

Generate and validate OATH one-time passwords.  KEY and OTP are the string '-' to read from standard input, '@FILE' to read from the indicated filename, or a hex-encoded value (not recommended on multi-user systems).

Install

• Debian-based sudo apt install oathtool gnupg2
• macOS, Homebrew brew install oath-toolkit

PassFF

The zx2c4 pass management extension for Firefox. (Pending Chrome port.) This extension allows you to access your zx2c4 pass repository directly from your web browser. You can select to automatically fill and submit login forms if a matching password entry is found.

Install

An official signed version can be found on the Mozilla add-on page.

👍 PassFF is one of the tools I use daily.

ZBar

ZBar Bar Code Reader is an open-source software suite for reading bar codes from various sources, such as video streams, image files, and raw intensity sensors. It supports EAN-13/UPC-A, UPC-E, EAN-8, Code 128, Code 93, Code 39, Codabar, Interleaved 2 of 5, QR Code, and SQ Code.

Install

• On Debian: sudo apt update && sudo apt -y install zbar-tools
• On macOS, Homebrew: brew install zbar

Using it

Download your QR code and type

• zbarimg -q my_qr.png to read it in clear text.

Using it with pass, and OTP by

• Typing pass otp add my_service,
• copy the output of the previous otpauth://...
• add it when asked to Enter otpauth:// URI for my_service:
• add it when asked to Retype otpauth:// URI for my_service:

and, you are clear to go.

Generate a TOTP code

• Type pass otp my_service and you will get a 6-digit code as output.

👍 ZBar is one of the tools I use.

PAM-GnuPG

Unlock GnuPG keys on login by a PAM module that hands over your login password to gpg-agent. This can be useful if you are using a GnuPG-based password manager like pass.

⚠️ Your store will automatically be opened at login ⚠️.
You need to turn on auto-close the desktop to add security.

Requires GnuPG 2.1 and probably only works on Linux.

QtPass — GUI

Many times I use a GUI, QtPass, a cross-platform app for Linux, macOS-Windows.

Install

• On Debian: sudo apt update && sudo apt -y install qtpass
• Install from the homepage
• Edit settings, password length, and how to use pass, the OTP extension. Git …

Backups

Since pass stores passwords in a directory, it's important to regularly back up this directory. You can use tools like rsync to back up the password directory to an external drive or a cloud storage service.

rsync -avz ~/.password-store/ /path/to/backup

References

pass ^[1]pass-otp ^[2] QtPass GUI ^[3] passff ^[4] OATHtool ^[5] PAM-GnuPG ^[6] ZBar ^[7]