gopass Password Manager Reference

1. Overview

gopass is a GPG-encrypted password manager compatible with pass. Stores credentials in a git-backed directory structure with automatic encryption/decryption.

Credential Organization Pattern

Use separate entries for each credential type, not combined entries:

ADMINISTRATIO/servers/home-dc01/
├── Administrator     # Just the password
├── dsrm              # Just the DSRM password
└── meta              # Metadata (hostname, IP, etc.)

2. Core Concepts

2.1. Store Structure

~/.local/share/gopass/stores/root/
├── .gpg-id                    # GPG key ID for encryption
├── ADMINISTRATIO/
│   ├── servers/
│   │   ├── home-dc01/
│   │   │   ├── Administrator.gpg
│   │   │   ├── dsrm.gpg
│   │   │   └── meta.gpg
│   │   └── ise-01/
│   │       └── admin.gpg
│   └── services/
│       └── vault/
│           └── root-token.gpg
└── .git/                      # Git repository for sync

2.2. Encryption

Each entry is GPG-encrypted with keys in .gpg-id
Decryption requires GPG key (YubiKey or local key)
Git tracks encrypted files, not plaintext

3. Basic Operations

3.1. List Entries

# List all entries
gopass ls

# List specific path
gopass ls ADMINISTRATIO/servers

3.2. Show/Retrieve Password

# Show password (prompts for GPG)
gopass show ADMINISTRATIO/servers/home-dc01/Administrator

# Copy to clipboard (auto-clears after 45s)
gopass show -c ADMINISTRATIO/servers/home-dc01/Administrator

# Output only (no newline) - useful for scripts
gopass show -o ADMINISTRATIO/servers/home-dc01/Administrator

3.3. Generate Passwords

# Generate 32-character password
gopass generate ADMINISTRATIO/servers/home-dc01/Administrator 32

# Generate without symbols
gopass generate -s ADMINISTRATIO/servers/home-dc01/Administrator 32

# Generate and copy to clipboard
gopass generate -c ADMINISTRATIO/servers/home-dc01/Administrator 32

3.4. Insert Entries

3.4.1. Single-Line (Password Only)

# Interactive (prompts for password)
gopass insert ADMINISTRATIO/servers/home-dc01/Administrator

# From stdin
echo "MySecurePassword123!" | gopass insert ADMINISTRATIO/servers/home-dc01/Administrator

3.4.2. Multi-Line with Heredoc

Use heredoc for multi-line entries. This is the preferred method for metadata.

gopass insert ADMINISTRATIO/servers/home-dc01/meta << 'EOF'
hostname: home-dc01
ip: 10.50.1.50
os: Windows Server 2025 Core
domain: inside.domusdigitalis.dev
roles: AD DS, DNS
deployed: 2026-02-09
notes: New forest, replaced old dc-01
EOF

3.4.3. Multi-Line Interactive

# -m flag for multi-line input (Ctrl+D to finish)
gopass insert -m ADMINISTRATIO/servers/home-dc01/meta

3.5. Edit Entries

# Opens in $EDITOR
gopass edit ADMINISTRATIO/servers/home-dc01/meta

3.6. Delete Entries

# Delete single entry
gopass rm ADMINISTRATIO/servers/home-dc01/old-entry

# Delete recursively (directory)
gopass rm -r ADMINISTRATIO/servers/decommissioned/

# Force delete (no confirmation)
gopass rm -f ADMINISTRATIO/servers/home-dc01/old-entry

3.7. Move/Rename Entries

# Rename entry
gopass mv ADMINISTRATIO/servers/old-name ADMINISTRATIO/servers/new-name

# Move to different path
gopass mv ADMINISTRATIO/temp/password ADMINISTRATIO/servers/home-dc01/admin

4. Credential Organization

4.1. Recommended Structure

ADMINISTRATIO/
├── servers/
│   ├── <hostname>/
│   │   ├── Administrator    # Primary admin password
│   │   ├── dsrm             # DSRM password (DCs only)
│   │   ├── root             # Root password (Linux)
│   │   └── meta             # Server metadata
│   └── ...
├── services/
│   ├── vault/
│   │   ├── root-token
│   │   └── unseal-keys
│   ├── ise/
│   │   ├── admin
│   │   └── ers-api
│   └── ...
├── network/
│   ├── pfsense/
│   │   └── admin
│   ├── wlc/
│   │   └── admin
│   └── ...
└── personal/
    └── ...

4.2. Separate Entries Pattern

DO NOT combine passwords in one entry. Use separate entries:

WRONG (combined entry)

ADMINISTRATIO/servers/home-dc01
  Administrator: Password123
  DSRM: DsrmPassword456

CORRECT (separate entries)

ADMINISTRATIO/servers/home-dc01/Administrator → Password123
ADMINISTRATIO/servers/home-dc01/dsrm → DsrmPassword456
ADMINISTRATIO/servers/home-dc01/meta → hostname, IP, notes

Why separate entries:

Each credential can be retrieved independently
Clipboard operations work correctly (gopass show -c gets one password)
Easier scripting and automation
Better audit trail (git history per credential)

5. Clipboard Operations

5.1. Copy to Clipboard

# Copy password (Wayland - uses wl-copy)
gopass show -c ADMINISTRATIO/servers/home-dc01/Administrator

5.2. Clipboard with wl-copy (Wayland)

For Wayland environments, combine with wl-copy:

# Copy password to clipboard using wl-copy
gopass show -o ADMINISTRATIO/servers/home-dc01/Administrator | wl-copy

# Copy and paste in one motion (for SSH, etc.)
gopass show -o ADMINISTRATIO/servers/home-dc01/Administrator | wl-copy && wl-paste

5.3. Brace Expansion for Multiple Keys

Brace expansion allows globbing multiple similar paths in one command.

# Copy multiple SSH public keys at once
cat ~/.ssh/id_ed25519_{d000,sk_rk_d000,sk_rk_d000_secondary}.pub | wl-copy

# Expands to:
# cat ~/.ssh/id_ed25519_d000.pub ~/.ssh/id_ed25519_sk_rk_d000.pub ~/.ssh/id_ed25519_sk_rk_d000_secondary.pub | wl-copy

6. Git Integration

gopass stores are git repositories by default.

6.1. Sync Operations

# Pull latest from remote
gopass sync

# Show git status
gopass git status

# Manual git operations
gopass git pull
gopass git push

6.2. Clone Existing Store

# Clone from remote
gopass clone git@github.com:user/password-store.git

# Clone to specific location
gopass clone git@github.com:user/password-store.git --path ~/.password-store-work

7. Search and Find

# Search entry names
gopass find home-dc01

# Search entry contents (decrypts all!)
gopass grep "10.50.1.50"

# List entries matching pattern
gopass ls | grep -i server

8. Scripting with gopass

8.1. Get Password for Script

# Store in variable (careful with shell history!)
PASSWORD=$(gopass show -o ADMINISTRATIO/servers/home-dc01/Administrator)

# Use directly in command
sshpass -p "$(gopass show -o path/to/password)" ssh user@host

8.2. Batch Operations

# Generate multiple passwords
for server in dc01 dc02 ise01; do
    gopass generate ADMINISTRATIO/servers/home-${server}/admin 32
done

9. Real-World Examples

9.1. New Server Deployment

# 1. Generate Administrator password
gopass generate ADMINISTRATIO/servers/home-dc01/Administrator 32

# 2. Generate DSRM password (for DCs)
gopass generate ADMINISTRATIO/servers/home-dc01/dsrm 32

# 3. Store metadata using heredoc
gopass insert ADMINISTRATIO/servers/home-dc01/meta << 'EOF'
hostname: home-dc01
ip: 10.50.1.50
os: Windows Server 2025 Core
domain: inside.domusdigitalis.dev
roles: AD DS, DNS
deployed: 2026-02-09
EOF

9.2. Retrieve for DC Promotion

# Get Administrator password for PowerShell
gopass show -o ADMINISTRATIO/servers/home-dc01/Administrator | wl-copy

# Get DSRM password
gopass show -o ADMINISTRATIO/servers/home-dc01/dsrm | wl-copy

9.3. SSH Key Deployment

# Copy multiple YubiKey public keys for pasting
cat ~/.ssh/id_ed25519_{d000,sk_rk_d000,sk_rk_d000_secondary}.pub | wl-copy

# Paste into remote authorized_keys
ssh admin@10.50.1.50 "cat >> ~/.ssh/authorized_keys"

10. Troubleshooting

10.1. GPG Key Not Found

# Check GPG keys
gpg --list-keys

# Check store's GPG ID
cat ~/.local/share/gopass/stores/root/.gpg-id

# Re-initialize with correct key
gopass init <gpg-key-id>

10.2. YubiKey Not Detected

# Check YubiKey status
ykman info

# Check GPG card status
gpg --card-status

# Restart GPG agent
gpgconf --kill gpg-agent
gpg --card-status

10.3. Entry Won’t Decrypt

# Check which key encrypted the entry
gpg --list-packets ~/.local/share/gopass/stores/root/path/to/entry.gpg

# Verify you have the key
gpg --list-secret-keys

11. Quick Reference

Operation Command

Operation	Command
List all	`gopass ls`
Show password	`gopass show path/to/entry`
Copy to clipboard	`gopass show -c path/to/entry`
Output only	`gopass show -o path/to/entry`
Generate password	`gopass generate path/to/entry 32`
Insert (interactive)	`gopass insert path/to/entry`
Insert (heredoc)	`gopass insert path << 'EOF' … EOF`
Edit	`gopass edit path/to/entry`
Delete	`gopass rm path/to/entry`
Search names	`gopass find pattern`
Search contents	`gopass grep pattern`
Sync	`gopass sync`

List all

gopass ls

Show password

gopass show path/to/entry

Copy to clipboard

gopass show -c path/to/entry

Output only

gopass show -o path/to/entry

Generate password

gopass generate path/to/entry 32

Insert (interactive)

gopass insert path/to/entry

Insert (heredoc)

gopass insert path << 'EOF' … EOF

Edit

gopass edit path/to/entry

Delete

gopass rm path/to/entry

Search names

gopass find pattern

Search contents

gopass grep pattern

Sync

gopass sync

12. Store Architecture (v2)

As of 2026-02-09, credentials use the v2 taxonomy:

v2/
├── OPUS/           # Work (per-employer, portable)
│   └── chla/
├── DOMUS/          # Personal infrastructure
│   ├── ad/         # Active Directory
│   ├── network/    # Network devices
│   ├── servers/    # Server credentials
│   ├── storage/    # NAS, backup
│   ├── wifi/       # Wireless networks
│   └── devices/    # Standalone devices
├── ARCANA/         # Secrets & keys (non-logins)
│   ├── api/        # API keys
│   ├── crypto/     # Encryption keys
│   ├── ssh/        # SSH passphrases
│   ├── radius/     # RADIUS secrets
│   └── certificates/
├── COMMERCIA/      # Financial
├── PERSONAE/       # Personal accounts
└── COMMUNIS/       # Shared/family

Access v2 entries:

gopass show v2/DOMUS/ad/evanusmodestus
gopass show v2/OPUS/chla/ad/erosado
gopass show v2/ARCANA/crypto/borg-passphrase

See gopass Taxonomy for full structure and naming conventions.

13. Related Documentation

gopass Taxonomy - v2 structure design and naming conventions
gopass Migration Plan - Migration from legacy to v2
Credential Chain
Secrets Recovery
Windows DC Deployment (uses gopass)