Domain Driven Architecture

Gopass Quick-Reference

Autor: Ansgar Zwick
29. Januar 2020

Tags: howto, reference, gopass

Gopass is a password-manager suitable for teams. It provides features as:

  • Secrets/credentials such as passwords are stored in files
  • Encryption is done by GnuPG
  • Versioning is provided by GIT

File structure of gopass

Gopass stores all secrets in separate files in a directory structure. The files are encrypted for certain gpg-ids. The gpg-ids used for the encryption are stored in a .gpg-id file. More precisely, a .gpg-id file contains all public gpg-ids (actually their fingerprints) which encrypt all the files in the respective folder and the subfolders. If there is another .gpg-id file in a subfolder, it "overwrites" the .gpg-id of the superfolder.

A simple gopass folder tree might look like:

gopass  (gopass root)
 ├─ team
 |   ├─ .public-keys  (contains the team members' public keys)
 |   |    └─ 8C6B83F071FBF4D45232FE9D4700C1   (contains public key; filename is fingerprint of key)
 |   ├─ .gpg-id   (contains the team's gpg ids)
 |   └─ server-pw
 └─ personal
     ├─ .gpg-id   (contains only the personal id or ids)
     └─ email-pw

The default root folder is: /.password-store/

Gopass stores its configuration in a config.yml file, in Linux it is usually found in folder ~/.config/gopass/ This config-file can be handy for checking some config details, or - at own risk (!) - to make manual config changes.

The public keys of the recipients are stored in folder .public-keys/ in each store/mount.


  • GnuPG (aka gpg) needs to be installed. If not, install (depending on your environment) e.g. with: sudo apt install gpg
  • gpg keys must be available
    • check with: gpg -k for existing keys
    • if none are available (or you want to create new ones), use: gpg --full-gen-key, for details see the corresponding paragraph below.


  • Install as described on: - (WARNING: The official Debian repositories contain a package named gopass that is not related to this gopass. So, you should not use e.g. sudo apt-get install gopass without having ensured that gopass refers to the intended one.)
  • Initialize
    • in the default location ~/.password-store/ with: gopass init <gpg-id>, where <gpg-id> is the fingerprint of your public gpg-key.
    • or in another location with: gopass init <-p folder> <gpg-id>

Update Gopass

If you have installed gopass with a package manager, you can use the same package manager to update gopass. If gopass has been installed manually, you'd need to re-install with a newer version in order to update.

Gopass Commands

For an overview of all commands, use gopass help:

gopass -h

Show list of secrets


List secrets of a particular store or subfolder (lists secret names, not the encrypted values)

Example: gopass personal

Insert secret

gopass insert <secret>

Example: gopass insert personal/email-pw

Edit a secret

gopass edit <secret>
Example: gopass edit personal/email-pw

Show secret

gopass <secret>
Example: gopass personal/email-pw

Copy secret to clipboard

gopass -c <secret>
Example: gopass -c personal/email-pw

Delete secret

gopass rm <secret>
Example: gopass rm personal/email-pw

Move secret

gopass mv <secret>
Example: gopass mv personal/mailpassword otherfolder/email-pw

Search for secrets (i.e. for secret names, not for the private secret values). Search is case-insensitive.

gopass search <part of secret name>
Example: gopass search mail

Search within encrypted secrets. It can only find secrets which you are able to decrypt (you will be prompted for the passphrase of your private key):

gopass grep <word to find>
Example: gopass search mail

Using stores (aka mounts)

Gopass supports multiple folder trees resp. repositories. They are called stores. Stores are very handy, e.g. if you have different git repositories containing different secret-stores.

List mounted stores

gopass mounts

Add a store

A store (repository) can be mounted (means added to gopass) by:

gopass init --store <store-name> --path <path>
Example: gopass init --store personal --path ~/personal-path

Or mount a store directly from a remote git repo:

gopass clone [git-url] [store-name] --sync gitcli

Example: gopass clone personal --sync gitcli

Remove a store

gopass mounts unmount <store-name>
Example: gopass mounts unmount personal

Manage team members and keys

List members resp. keys

Check the members for whom the secrets are encrypted:

gopass recipients
gopass recipients --store <store name>

Shows the recipients for each store resp. for a specific store.

Only shows "top-level" recipients, does not show recipients of a subfolder, if other recipients were defined in a subfolder's .gpg-id file.

Add a new key

For example for a new team member. A team member, who has already access to the gopass store, can add the new key by:

gopass recipients add [FINGERPRINT]

If several stores exist, gopass will prompt to select a store.

Determine the fingerprint for the key by:

gpg --fingerprint [keyname]

or list all keys incl. fingerprint:

gpg --list-public-keys --with-fingerprint --with-colons

When adding a recipient with gopass recipients add their public key will automatically be exported to the store in .gpg-keys/<ID>.

The other team members can retrieve all changes by gopass sync.

Remove a key

E.g. if a team member left the team. Remove the key fingerprint from the .gpg-id file.

gopass recipients rm [FINGERPRINT]

Replace an expired key

Generate a new key as described above. A team member with a valid key can add the new key and remove the old one by:

gopass recipients add [NEW FINGERPRINT]
gopass recipients rm [OLD FINGERPRINT]

After that, the other team members need to import the new key:

gopass sync


meissa GmbH


Recent Posts



We support