Skip to main content
chezmoi includes support for pass, the standard Unix password manager, using the pass CLI.

​
Setup

​
Install pass

brew install pass

​
Initialize pass

If you haven’t set up pass yet: 
# Initialize with your GPG key
pass init [email protected]

# 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

# ~/.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

# 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 [email protected]:username/passwords.git

# Push passwords
pass git push -u origin master

​
Team Password Sharing

Initialize pass for multiple GPG keys: 
pass init [email protected] [email protected]
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

Build docs developers (and LLMs) love

Get started for freeTalk to us