Proton Pass - chezmoi

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

Or download from the official repository.

Log In

Authenticate with Proton Pass:

proton-pass-cli login

Follow the authentication prompts.

Template Functions

`protonPass`

Retrieve an item using a secret reference URI:

{{ protonPass "pass://$SHARE_ID/$ITEM_ID/$FIELD" }}

The URI format is 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

~/.gitconfig.tmpl

[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

~/.aws/credentials.tmpl

[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

~/.npmrc.tmpl

//registry.npmjs.org/:_authToken={{ protonPass "pass://personal/npm/token" }}
email={{ protonPass "pass://personal/npm/email" }}

SSH Configuration

~/.ssh/config.tmpl

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 }}"
    }
  }
}

Secret Reference URI Format

Proton Pass uses URIs in the format:

pass://SHARE_ID/ITEM_ID/FIELD

Where:

SHARE_ID: The vault/share identifier
ITEM_ID: The item identifier
FIELD: 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

~/k8s/secrets.yaml.tmpl

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

proton-pass-cli login

Item Not Found

List all items:

proton-pass-cli list

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

Get Started

Core Concepts

User Guide

Encryption & Secrets

Password Managers

Advanced Usage

FAQ

​Setup

​Install Proton Pass CLI

​Log In

​Template Functions

​protonPass

​protonPassJSON

​Usage Examples

​Simple Secret Retrieval

​Git Configuration

​Using JSON Structure

​Database Credentials

​AWS Credentials

​Multiple API Keys

​NPM Configuration

​SSH Configuration

​Docker Registry

​Secret Reference URI Format

​Finding Item References

​Configuration

​Custom Command

​Complete Examples

​Multi-Service Configuration

​Application Configuration

​Kubernetes Secrets

​Troubleshooting

​Not Logged In

​Item Not Found

​Command Not Found

​Testing Templates

​Invalid Reference

​Best Practices

​See Also

Build docs developers (and LLMs) love