pass (Password Store)

Integrate pass with chezmoi to manage secrets in your dotfiles

chezmoi includes support for pass, the standard Unix password manager, using the pass CLI.

Setup

Install pass

macOS

brew install pass

Initialize pass

If you haven’t set up pass yet:

# Initialize with your GPG key
pass init [e-mail]

# Or initialize with a specific GPG key ID
pass init 0x1234567890ABCDEF

Add Passwords

# Add a password
pass insert github/token

# Generate a random password
pass generate aws/secret-key 32

# Add multiline data
pass insert -m ssh/private-key

Template Functions

pass

Get the first line from a password entry:

{{ pass "github/token" }}

This runs pass show github/token and returns the first line.

passFields

Get structured data from a password entry with key-value pairs:

{{ (passFields "aws/credentials").access_key_id }}

This parses the entry as colon-separated key-value pairs.

passRaw

Get the complete raw output from a password entry:

{{ passRaw "ssh/private-key" }}

Useful for multiline data like SSH keys or certificates.

Usage Examples

Simple Passwords

GitHub Token

# ~/.config/gh/config.yml.tmpl
github_token: {{ pass "github/token" }}

Git Configuration

~/.gitconfig.tmpl

[user]
    name = John Doe
    email = {{ pass "git/email" }}
    signingkey = {{ pass "git/signing-key" }}

[github]
    user = {{ pass "github/username" }}

[credential]
    helper = store

SSH Private Keys

Store SSH keys in pass:

# Add SSH key to pass
pass insert -m ssh/id_rsa < ~/.ssh/id_rsa

Use in templates:

~/.ssh/id_rsa.tmpl

{{ passRaw "ssh/id_rsa" }}

Structured Data with passFields

Store data as key-value pairs in pass:

pass insert -m aws/credentials
# Then enter:
access_key_id: AKIAIOSFODNN7EXAMPLE
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region: us-east-1

Access in templates:

~/.aws/credentials.tmpl

[default]
aws_access_key_id = {{ (passFields "aws/credentials").access_key_id }}
aws_secret_access_key = {{ (passFields "aws/credentials").secret_access_key }}
region = {{ (passFields "aws/credentials").region }}

Database Credentials

Store in pass

# Production database
pass insert -m db/production
# Enter:
host: db.example.com
port: 5432
username: app_user
password: super_secret_password
database: production_db

Multiple API Keys

~/.config/api-keys.env.tmpl

# Cloud Services
AWS_ACCESS_KEY_ID={{ pass "aws/access-key-id" }}
AWS_SECRET_ACCESS_KEY={{ pass "aws/secret-access-key" }}
DIGITALOCEAN_TOKEN={{ pass "digitalocean/token" }}

# Development Tools
GITHUB_TOKEN={{ pass "github/token" }}
GITLAB_TOKEN={{ pass "gitlab/token" }}
OPENAI_API_KEY={{ pass "openai/api-key" }}

# Payment Services
STRIPE_SECRET_KEY={{ pass "stripe/secret-key" }}
STRIPE_PUBLISHABLE_KEY={{ pass "stripe/publishable-key" }}

Docker Registry Credentials

# Store Docker Hub credentials
pass insert docker/username
pass insert docker/password

~/.docker/config.json.tmpl

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "{{ printf "%s:%s" (pass "docker/username") (pass "docker/password") | b64enc }}"
    }
  }
}

Kubernetes Config

~/.kube/config.tmpl

apiVersion: v1
kind: Config
clusters:
- cluster:
    server: {{ pass "kubernetes/server" }}
    certificate-authority-data: {{ passRaw "kubernetes/ca-cert" | b64enc }}
  name: production
contexts:
- context:
    cluster: production
    user: admin
  name: production
current-context: production
users:
- name: admin
  user:
    client-certificate-data: {{ passRaw "kubernetes/client-cert" | b64enc }}
    client-key-data: {{ passRaw "kubernetes/client-key" | b64enc }}

Configuration

Custom Command

If pass is not in your PATH:

~/.config/chezmoi/chezmoi.toml

[pass]
    command = "/custom/path/to/pass"

Custom Password Store Location

By default, pass uses ~/.password-store. To use a different location:

export PASSWORD_STORE_DIR="$HOME/.my-passwords"

Or add to your shell profile:

~/.bashrc

export PASSWORD_STORE_DIR="$HOME/.my-passwords"

Organizing Your Password Store

Use a hierarchical structure:

~/.password-store/
├── personal/
│   ├── email/
│   │   └── gmail
│   ├── github/
│   │   ├── token
│   │   └── username
│   └── ssh/
│       └── id_rsa
├── work/
│   ├── aws/
│   │   └── credentials
│   ├── github/
│   │   └── token
│   └── vpn/
│       └── password
└── shared/
    └── wifi/
        └── home

Access with:

{{ pass "personal/github/token" }}
{{ pass "work/aws/credentials" }}

Advanced Usage

Using pass with Git

pass can sync with git:

# Initialize git in password store
pass git init

# Add a remote
pass git remote add origin [e-mail]:username/passwords.git

# Push passwords
pass git push -u origin master

Team Password Sharing

Initialize pass for multiple GPG keys:

pass init [e-mail] [e-mail]

Everyone with these keys can decrypt the passwords.

Generating Passwords

# Generate a 32-character password
pass generate github/token 32

# Generate without symbols
pass generate -n aws/secret-key 40

Editing Passwords

# Edit a password entry
pass edit github/token

# View a password
pass show github/token

Complete Examples

Multi-Service Configuration

~/.config/services.yml.tmpl

github:
  username: {{ pass "github/username" }}
  token: {{ pass "github/token" }}
  email: {{ pass "github/email" }}

aws:
  access_key_id: {{ (passFields "aws/credentials").access_key_id }}
  secret_access_key: {{ (passFields "aws/credentials").secret_access_key }}
  region: {{ (passFields "aws/credentials").region }}

database:
  host: {{ (passFields "database/production").host }}
  port: {{ (passFields "database/production").port }}
  username: {{ (passFields "database/production").username }}
  password: {{ (passFields "database/production").password }}

smtp:
  host: {{ (passFields "email/smtp").host }}
  port: {{ (passFields "email/smtp").port }}
  username: {{ (passFields "email/smtp").username }}
  password: {{ (passFields "email/smtp").password }}

Troubleshooting

GPG Key Not Found

Ensure your GPG key is available:

gpg --list-secret-keys

If not, import it:

gpg --import private-key.asc

Password Not Found

List all passwords:

pass ls

Or search:

pass find github

Command Not Found

Ensure pass is installed:

which pass
pass --version

Testing Templates

Test template functions:

chezmoi execute-template '{{ pass "test/password" }}'

GPG Agent Issues

If GPG prompts repeatedly for your password:

# Check GPG agent
gpg-connect-agent /bye

# Restart GPG agent
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

Best Practices

1. Use hierarchy: Organize passwords in logical folders
2. Use descriptive names: Make entry names clear and searchable
3. Backup regularly: Keep encrypted backups of your password store
4. Use git: Sync your password store across machines with git
5. Set GPG key expiry: Use expiring GPG keys for better security
6. Use passFields: Structure complex data as key-value pairs
7. Test access: Verify passwords are accessible before using in templates

See Also

• pass Website
• pass Git Repository
• Template Functions Reference
• gopass - Extended version of pass