Documentation Index
Fetch the complete documentation index at: https://mintlify.com/twpayne/chezmoi/llms.txt
Use this file to discover all available pages before exploring further.
chezmoi includes support for Proton Pass, a password manager from Proton, using the Proton Pass CLI to expose data as template functions.
Setup
Install Proton Pass CLI
Install the Proton Pass CLI:
npm install -g @protontech/pass-cli
Log In
Authenticate with Proton Pass:
Follow the authentication prompts.
Template Functions
protonPass
Retrieve an item using a secret reference URI:
{{ protonPass "pass://$SHARE_ID/$ITEM_ID/$FIELD" }}
pass://share-id/item-id/field-name.
protonPassJSON
Get structured JSON data for an item:
{{ (protonPassJSON "item-identifier").password }}
{{ (protonPassJSON "item-identifier").username }}
Usage Examples
Simple Secret Retrieval
# Using secret reference
{{ protonPass "pass://share-123/item-456/password" }}
Git Configuration
[user]
name = {{ protonPass "pass://personal/git-config/name" }}
email = {{ protonPass "pass://personal/git-config/email" }}
signingkey = {{ protonPass "pass://personal/git-config/gpg-key" }}
Using JSON Structure
~/.config/app/config.yml.tmpl
{{ $github := protonPassJSON "github" -}}
github:
username: {{ $github.username }}
token: {{ $github.password }}
email: {{ $github.email }}
Database Credentials
~/.config/db/config.yml.tmpl
{{ $db := protonPassJSON "production-database" -}}
production:
host: {{ $db.url }}
port: 5432
username: {{ $db.username }}
password: {{ $db.password }}
database: production_db
AWS Credentials
[default]
aws_access_key_id = {{ protonPass "pass://personal/aws/access-key-id" }}
aws_secret_access_key = {{ protonPass "pass://personal/aws/secret-access-key" }}
region = {{ protonPass "pass://personal/aws/region" }}
Multiple API Keys
~/.config/api-keys.env.tmpl
# GitHub
GITHUB_TOKEN={{ protonPass "pass://work/github/token" }}
# GitLab
GITLAB_TOKEN={{ protonPass "pass://work/gitlab/token" }}
# OpenAI
OPENAI_API_KEY={{ protonPass "pass://personal/openai/api-key" }}
# Stripe
STRIPE_SECRET_KEY={{ protonPass "pass://work/stripe/secret-key" }}
NPM Configuration
//registry.npmjs.org/:_authToken={{ protonPass "pass://personal/npm/token" }}
email={{ protonPass "pass://personal/npm/email" }}
SSH Configuration
Host github.com
User {{ protonPass "pass://personal/github-ssh/username" }}
IdentityFile ~/.ssh/id_ed25519
Host gitlab.com
User {{ protonPass "pass://work/gitlab-ssh/username" }}
IdentityFile ~/.ssh/id_rsa
Docker Registry
~/.docker/config.json.tmpl
{{ $docker := protonPassJSON "docker-hub" -}}
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "{{ printf "%s:%s" $docker.username $docker.password | b64enc }}"
}
}
}
pass://SHARE_ID/ITEM_ID/FIELD
SHARE_ID: The vault/share identifierITEM_ID: The item identifierFIELD: The field name (e.g., password, username, email)
Finding Item References
To find item identifiers:
# List all items
proton-pass-cli list
# View item details
proton-pass-cli show "item-name"
Configuration
Custom Command
If the Proton Pass CLI is not in your PATH:
~/.config/chezmoi/chezmoi.toml
[protonPass]
command = "/custom/path/to/proton-pass-cli"
Complete Examples
Multi-Service Configuration
~/.config/services.yml.tmpl
{{ $github := protonPassJSON "github" -}}
{{ $aws := protonPassJSON "aws" -}}
{{ $db := protonPassJSON "database" -}}
github:
username: {{ $github.username }}
token: {{ $github.password }}
aws:
access_key_id: {{ $aws.username }}
secret_access_key: {{ $aws.password }}
region: us-east-1
database:
host: {{ $db.url }}
username: {{ $db.username }}
password: {{ $db.password }}
database: production
Application Configuration
~/.config/app/config.yml.tmpl
application:
name: myapp
environment: production
api_keys:
github: {{ protonPass "pass://work/github/token" }}
openai: {{ protonPass "pass://work/openai/api-key" }}
stripe: {{ protonPass "pass://work/stripe/secret-key" }}
database:
url: postgresql://{{ protonPass "pass://work/db/username" }}:{{ protonPass "pass://work/db/password" }}@{{ protonPass "pass://work/db/host" }}/production
redis:
url: redis://:{{ protonPass "pass://work/redis/password" }}@localhost:6379
Kubernetes Secrets
apiVersion: v1
kind: Secret
metadata:
name: app-secrets
type: Opaque
data:
database-password: {{ protonPass "pass://work/db/password" | b64enc }}
api-key: {{ protonPass "pass://work/api/key" | b64enc }}
jwt-secret: {{ protonPass "pass://work/jwt/secret" | b64enc }}
Troubleshooting
Not Logged In
Log in to Proton Pass:
Item Not Found
List all items:
Verify the item exists and get its reference:
proton-pass-cli show "item-name"
Command Not Found
Ensure Proton Pass CLI is installed:
which proton-pass-cli
npm list -g @protontech/pass-cli
Testing Templates
Test template functions:
chezmoi execute-template '{{ protonPass "pass://share/item/field" }}'
chezmoi execute-template '{{ protonPassJSON "item" | toJson }}'
Invalid Reference
Ensure your reference URI is in the correct format:
pass://SHARE_ID/ITEM_ID/FIELD
Best Practices
- Use secret references: Prefer the
pass:// URI format for clarity
- Organize vaults: Use separate vaults for work, personal, shared
- Document references: Keep a list of reference URIs used
- Test access: Verify items are accessible before templating
- Use descriptive names: Name items clearly for easy reference
- Leverage JSON: Use
protonPassJSON for multiple fields
- Stay synced: Ensure Proton Pass is synced across devices
See Also