Skip to main content
chezmoi includes support for 1Password using the 1Password CLI to expose data as template functions.

​
Setup

​
Install 1Password CLI

Install the 1Password CLI from 1Password’s website.

​
Sign In

Log in and get a session: 
op account add --address $SUBDOMAIN.1password.com --email $EMAIL
eval $(op signin --account $SUBDOMAIN)
This is not necessary if you are using biometric authentication.

​
Template Functions

​
onepasswordRead

Read a secret using the secret reference URI: 
{{ onepasswordRead "op://app-prod/db/password" }}
This runs: 
op read op://app-prod/db/password

​
onepassword

Get structured data for an item: 
{{ (onepassword "$UUID").fields }}
This runs op item get $UUID --format json and returns the parsed JSON.

​
onepasswordDetailsFields

Get a simplified field structure: 
{{ (onepasswordDetailsFields "$UUID").password.value }}
This returns fields indexed by their ID or label for easier access.

​
onepasswordItemFields

Get item-specific fields (fields with sections): 
{{ (onepasswordItemFields "$UUID").apikey.value }}

​
onepasswordDocument

Retrieve a document: 
{{ onepasswordDocument "$UUID" }}
onepasswordDocument is not available in Connect mode.

​
Usage Examples

​
Reading Secrets by Reference

The simplest approach using secret references: 
# ~/.ssh/config.tmpl
Host github.com
    IdentityFile ~/.ssh/id_ed25519
    User git

Host work-github
    HostName github.com
    IdentityFile ~/.ssh/work_id_rsa
    User {{ onepasswordRead "op://Work/GitHub/username" }}

​
Using Structured Data

Access specific fields from the JSON response: 
# Access fields by array index
username = {{ (index (onepassword "$UUID").fields 0).value }}
password = {{ (index (onepassword "$UUID").fields 1).value }}

​
Retrieving Documents

# ~/.ssh/work_id_rsa
{{ onepasswordDocument "jn5odbpyctjbhk5gqa7xs5cjom" }}

​
Working with Item Fields

Access additional fields (those in sections):
~/.config/service/config.tmpl
[api]
key = {{ (onepasswordItemFields "$UUID").api_key.value }}
endpoint = {{ (onepasswordItemFields "$UUID").endpoint.value }}

[database]
host = {{ (onepasswordItemFields "$UUID").db_host.value }}
port = {{ (onepasswordItemFields "$UUID").db_port.value }}

​
Configuration

​
Sign-In Prompt

By default, chezmoi will verify the session token and prompt for sign-in if needed.
~/.config/chezmoi/chezmoi.toml
[onepassword]
    prompt = true  # Default behavior
To disable automatic prompting:
~/.config/chezmoi/chezmoi.toml
[onepassword]
    prompt = false
Do not use prompt = true on shared machines. Session tokens are passed via command-line parameters, which are visible to other users.

​
Custom Command

If op is not in your PATH:
~/.config/chezmoi/chezmoi.toml
[onepassword]
    command = "/custom/path/to/op"

​
Secrets Automation

chezmoi supports 1Password Connect and Service Accounts for restricted environments where the full desktop app isn’t available.

​
Account Mode (Default)

For regular 1Password accounts:
~/.config/chezmoi/chezmoi.toml
[onepassword]
    mode = "account"  # Default
In account mode, chezmoi will error if:
  • OP_SERVICE_ACCOUNT_TOKEN is set, or
  • Both OP_CONNECT_HOST and OP_CONNECT_TOKEN are set

​
1Password Connect

Once 1Password Connect is configured:
~/.config/chezmoi/chezmoi.toml
[onepassword]
    mode = "connect"
Set the required environment variables: 
export OP_CONNECT_HOST="http://localhost:8080"
export OP_CONNECT_TOKEN="your-connect-token"
Limitations in Connect mode:
  • onepasswordDocument is not available
  • Account parameters are not allowed
  • Both OP_CONNECT_HOST and OP_CONNECT_TOKEN must be set

​
1Password Service Accounts

Once a service account is created:
~/.config/chezmoi/chezmoi.toml
[onepassword]
    mode = "service"
Set the required environment variable: 
export OP_SERVICE_ACCOUNT_TOKEN="your-service-account-token"
Limitations in Service mode:
  • Account parameters are not allowed
  • OP_SERVICE_ACCOUNT_TOKEN must be set
Both 1Password Connect and Service Accounts prevent the CLI from working with multiple accounts. If you need access to secrets from more than one 1Password account, do not use these features.

​
Multiple Accounts

In account mode, you can specify which account to use: 
{{ onepasswordRead "op://app-prod/db/password" "work-account" }}
The account parameter can be:
  • Account URL: example.1password.com
  • Email: [email protected]
  • Account UUID
  • User UUID
  • Shorthand

​
Complete Examples

​
NPM Configuration

~/.npmrc.tmpl
//registry.npmjs.org/:_authToken={{ onepasswordRead "op://Personal/NPM/token" }}
email={{ onepasswordRead "op://Personal/NPM/email" }}

​
Database Configuration

~/.config/db/config.yml.tmpl
production:
  host: {{ onepasswordRead "op://Production/Database/host" }}
  port: {{ onepasswordRead "op://Production/Database/port" }}
  username: {{ onepasswordRead "op://Production/Database/username" }}
  password: {{ onepasswordRead "op://Production/Database/password" }}
  database: {{ onepasswordRead "op://Production/Database/database" }}

development:
  host: localhost
  port: 5432
  username: dev
  password: {{ onepasswordRead "op://Development/Database/password" }}
  database: app_dev

​
Multi-Service API Keys

~/.config/api-keys.env.tmpl
# GitHub
GITHUB_TOKEN={{ onepasswordRead "op://Personal/GitHub/token" }}
GH_TOKEN={{ onepasswordRead "op://Personal/GitHub/token" }}

# OpenAI
OPENAI_API_KEY={{ onepasswordRead "op://Personal/OpenAI/api-key" }}

# Stripe
STRIPE_SECRET_KEY={{ onepasswordRead "op://Work/Stripe/secret-key" }}
STRIPE_PUBLISHABLE_KEY={{ onepasswordRead "op://Work/Stripe/publishable-key" }}

# Slack
SLACK_WEBHOOK_URL={{ onepasswordRead "op://Work/Slack/webhook-url" }}

​
Troubleshooting

​
Session Token Expired

eval $(op signin --account $SUBDOMAIN)

​
Command Not Found

Ensure the 1Password CLI is installed and in your PATH: 
which op
op --version

​
Invalid Item Reference

Verify the item exists: 
op item get "$UUID" --format json

​
Testing Template Functions

Test your template functions: 
chezmoi execute-template '{{ onepasswordRead "op://Personal/test/value" }}'

​
Best Practices

  1. Use secret references: Prefer onepasswordRead with op:// URIs for simplicity
  2. Organize vaults: Use separate vaults for Personal, Work, etc.
  3. Use descriptive names: Name items clearly for easy reference
  4. Test before committing: Verify templates work before adding to source control
  5. Document UUIDs: Keep a reference of UUIDs used in templates

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us