pass, the standard unix password manager, is a simple shell script that provides an interface to easily store and access files encrypted with GPG, in a secure password vault.

pass uses gpg (an implementation of the pgp encryption protocol) to encrypt and decrypt your files, so you can access them with any tool which decrypts with your GPG keys, not just the pass tool. You can sync the password vault using any tool, or you can use git, which is integrated with pass, to provide automatic syncing between devices.

There are several other tools you can use to manage your pass database:

  • qtpass - a desktop gui pass tool providing full GUI management of the vault
  • gopass - a replacement for pass with some additional features like search and coloring
  • gpg - you can directly decrypt your password files using gpg, without any wrapper. This can be useful for building your own scripts or tooling.

Setting up your GPG key

First, you need to create your GPG key. You can skip this step if you already have a GPG key you would like to use.

$ gpg --gen-key

You will see a number of options. Generally, they are self explanatory, but ensure you use these options when asked.

  • Select key type of “DSA and RSA”
  • Create a size 4096 bit key
  • Expiration - if you’re not sure, generally set to 0 (none). However, you should read more about this below.

You’ll then enter your name, email, password, and allow the key to generate. After you enter the password, it may take a while as it collects randomness (entropy) from the system to generate a secure key. Once the entropy is generated, the key generation is complete.

The password must be secure, it is embedded in your key, used to encrypt it. Anyone who obtains your private key file and your password can use this to impersonate you.

Finally, export from gpg and import to gpg2, so that tools which use gpg2 can also use the key.

$ gpg2 --import <(gpg --export-secret-keys)

Finally, your key is stored in ~/.gnupg.

GPG expiration

GPG key expiration is a complex topic. I can’t begin to cover all the angles on this topic, so I’d reccomend researching this on your own. Generally, it’s good to set some expiration so that a compromized key can’t be used forever. However, similarly, this requires action at expiration time. For starting out, a non expiring key is a safe default, but before you rely on this key for critical security, you should plan to grow a deeper understanding of this complex topic.

Setting up pass

Now that you have a key, either an older key, or one generated above, you can set up your pass vault.

First, list your keys using the gpg command:

$ gpg --list-secret-keys
sec   4096R/12345678 2018-11-02
uid                  John Doe (Comment) <>
ssb   4096R/12345678 2018-11-02

Your key is identified by the email (in this case, Use this identifer to create your pass database, adding the key identifier to the end of the command.

$ pass init
mkdir: created directory '/home/johndoe/.password-store/'
Password store initialized for

Your password store has now been created at the path shown in the command output. You can now back up this directory, or sync it around, if you don’t use the git option.

Using pass

Passwords in pass are stored in a directory-like tree.

We will view an example tree.

To view all your passwords, run:

$ pass

Password Store
├── email
│   ├── personal
│   │   ├── jdoe-gmail
│   │   └── jdoe-hotmail
│   └── work
│       ├── doecorp-amazon-work-account
│       ├── doecorp-domain-registrar
│       └── doecorp-jdoe-domain-account
└── financial
    └── banks
        ├── bank-of-america
        ├── chase
        └── usbank

Adding an Entry

To add a password, run the insert command, followed by the path.

$ pass insert medical/hospital/billing
mkdir: created directory '/home/jdoe/.password-store/medical'
mkdir: created directory '/home/jdoe/.password-store/medical/hospital'
Enter password for medical/hospital/billing: 
Retype password for medical/hospital/billing: 

Type your password twice when prompted, and enter.

If you’d like to add more than a password, use the edit command documented below.

Edit an Entry

To edit an entry, run the edit command, followed by the path.

$ pass edit medical/hospital/billing

On running this command, it will ask for your password, and then open a text editor in the terminal where you can add as many details as you would like.

View a Password

To view a password, just specify your path without any command.

$ pass medical/hospital/billing

username: jdoe

Note: this account used for billing at downtown clinic,
not the suburb clinic.

You can also specify -c to copy the first line (usually the password itself) to the clipboard.

$ pass -c medical/hospital/billing
Copied medical/hospital/billing to clipboard. Will clear in 45 seconds.

You can now use it from your clipboard.

Pass entries are simply multi-line files, so you can store as much information as you’d like within the file. The only important part is to keep the password on the first line, as this is where pass looks for it when using the clipboard functionality.

Generate a Password

Instead of using insert, you can use generate to create a new password for you, and store it. Also specify the character count. The command below will create and store a 10 character password.

$ pass generate medical/hospital/chart 10

The generated password for medical/hospital/chart is:

You can then see your new password in the password store, and view it:

$ pass

Password Store
├── email
│   ├── personal
│   │   ├── jdoe-gmail
│   │   └── jdoe-hotmail
│   └── work
│       └── ceo-doecorp
├── financial
│   └── banks
│       ├── bank-of-america
│       ├── chase
│       └── usbank
└── medical
    └── hospital
        ├── billing
        └── chart
$ pass medical/hospital/chart


Here, pass, and it’s underlying technology of gpg can provide you with a simple and secure way of storing your passwords with minimal overhead and maximum security.