Domain Driven Architecture

Gopass Quick-Reference

Autor: A Zwick
January 29, 2020

Tags: password-manager, 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 files named .gpg-id.
More precisely, a file .gpg-id contains all public gpg-ids (in fact their fingerprints) which are used to encrypt all the files in the same folder and all subfolders. If there is another .gpg-id file in a subfolder, it "overwrites" on its turn the keys of this subfolder and sub-subfolders.

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 package "gopass" of the official Debian repositories is not related to this gopass. So, don't use e.g. sudo apt-get install gopass, unless you want to install the "other" gopass.)
  • Initialization:
    • Use gopass init <gpg-id> for initialization in the default location (i.e. ~/.password-store/), where <gpg-id> is the fingerprint of your public gpg-key.
    • or initialize 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

Rotate a secret's content / Password

Rotating a secret can be done by editing it manually or by generating a new one:

gopass generate <path to secret> <optional length>
Example: gopass generate personal/my-store-secret 25

The generate command replaces the first line of a secret with a newly generated one. The content of other lines is not changed, but the lines below the first one might be reordered.

Passwords are generated by default with alphanumeric characters. To **include symbols* you can use option "-s", e.g.:

gopass generate -s personal/my-store-secret 25

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 created and mounted (i.e. 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

Or you can mount an already existing local store:

gopass mounts add <store name> <path to local store>
Example: gopass mounts add mystore ~/repo/personal/store

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 name>

Shows the recipients for all stores resp. for a specific store.

This command 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 member resp. key

To add a new member you need to ensure that the new member's public key is already imported in gpg. If this is not the case, import the key e.g. by

gpg --import

Add the new key to gopass by (executed by a team member, who has already access to the gopass store):

gopass recipients add <EMAIL or FINGERPRINT>

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

You can get the fingerprint of a key by:

gpg --fingerprint <keyname>

or list all keys including the fingerprints:

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 a 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

Enable auto-completion in bash

echo "source <(gopass completion bash)" >> ~/.bashrc

Update May 2021

Gopass Bridge

If you are already using gopass for storing your passwords, Gopass Bridge is a handy tool for easy entering passwords into webpages.


In order to use the Gopass Bridge you need

  • gopass-jsonapi
  • the Gopass Bridge browser plugin

Use the steps below to install and configure gopass-jsonapi and Gopass Bridge for Ubuntu per cli.
(alternatively follow the description on:

  1. Download the appropriate version of the gopass-jsonapi e.g. for gopass 1.12 (find out by gopass -version) by:
    curl -L --output jsonapi.deb
    Note: for other gopass versions, see:
  2. Install gopass-jsonapi sudo dpkg -i jsonapi.deb
  3. Configure gopass-jsonapi by gopass-jsonapi configure and answer the subsequent questions.
  4. Install the browser plugin
  5. Ensure your gopass entries follow this format (password separated with — from username in separate lines):
    username: <username>

url is optional.


Click on Gopass Bridge Icon in your browser and enter the credential name, e.g. if the password has been stored in path /web/personal/github just enter git or another substring in order to search.


meissa GmbH


Recent Posts



We support