Skip to main content

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 Bitwarden using the Bitwarden CLI (bw), Bitwarden Secrets CLI (bws), and rbw to expose data as template functions.

​
Bitwarden CLI Setup

​
Install

Install the Bitwarden CLI: 
# macOS
brew install bitwarden-cli

# Linux/Windows - download from
# https://bitwarden.com/help/cli/

​
Log In

Log in using one of these methods: 
bw login $BITWARDEN_EMAIL

​
Unlock

If required, unlock your vault (API key and SSO logins always require an explicit unlock): 
bw unlock
Set the BW_SESSION environment variable as instructed.

​
Quick Session Setup

export BW_SESSION=$(bw unlock --raw)

​
Template Functions

​
bitwarden

Get structured data from an item: 
username = {{ (bitwarden "item" "example.com").login.username }}
password = {{ (bitwarden "item" "example.com").login.password }}
This runs bw get item example.com and returns parsed JSON.

​
bitwardenFields

Access custom fields: 
{{ (bitwardenFields "item" "example.com").token.value }}

​
bitwardenAttachment

Retrieve attachments by item ID: 
{{ bitwardenAttachment "id_rsa" "bf22e4b4-ae4a-4d1c-8c98-ac620004b628" }}

​
bitwardenAttachmentByRef

Retrieve attachments by item reference: 
{{ bitwardenAttachmentByRef "id_rsa" "item" "example.com" }}

​
Usage Examples

​
Login Credentials

# ~/.gitconfig.tmpl
[user]
    name = {{ (bitwarden "item" "git-config").login.username }}
    email = {{ (bitwarden "item" "git-config").notes }}

[github]
    user = {{ (bitwarden "item" "github").login.username }}

​
Custom Fields

# ~/.config/tokens.env.tmpl
GITHUB_TOKEN={{ (bitwardenFields "item" "github-api").token.value }}
GITLAB_TOKEN={{ (bitwardenFields "item" "gitlab-api").api_token.value }}
OPENAI_API_KEY={{ (bitwardenFields "item" "openai").api_key.value }}

​
Attachments

# ~/.ssh/work_id_rsa
{{ bitwardenAttachment "id_rsa" "bf22e4b4-ae4a-4d1c-8c98-ac620004b628" }}

​
Configuration

​
Automatic Unlock

Enable automatic unlocking if BW_SESSION is not set:
~/.config/chezmoi/chezmoi.toml
[bitwarden]
    unlock = "auto"

​
Custom Command

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

​
Bitwarden Secrets CLI

The Secrets CLI (bws) is for Bitwarden Secrets Manager.

​
Setup

  1. Generate an access token for a service account
  2. Either set the environment variable or store in config:
export BWS_ACCESS_TOKEN="0.48c78342-1635-48a6-accd-afbe01336365.C0tMmQqHnAp1h0gL8bngprlPOYutt0:B3h5D+YgLvFiQhWkIq6Bow=="

​
bitwardenSecrets

Retrieve secrets: 
{{ (bitwardenSecrets "be8e0ad8-d545-4017-a55a-b02f014d4158").value }}
With token from config: 
{{ (bitwardenSecrets "be8e0ad8-d545-4017-a55a-b02f014d4158" .accessToken).value }}

​
Usage Examples

# ~/.config/secrets.env.tmpl
API_KEY={{ (bitwardenSecrets "api-key-uuid").value }}
DB_PASSWORD={{ (bitwardenSecrets "db-password-uuid").value }}
JWT_SECRET={{ (bitwardenSecrets "jwt-secret-uuid").value }}

​
Unofficial Alternative: rbw

rbw is an unofficial Bitwarden CLI with better daemon support. See the rbw template functions reference for usage.

​
Complete Examples

​
AWS Credentials

~/.aws/credentials.tmpl
[default]
aws_access_key_id = {{ (bitwardenFields "item" "aws-personal").access_key_id.value }}
aws_secret_access_key = {{ (bitwardenFields "item" "aws-personal").secret_access_key.value }}
region = {{ (bitwardenFields "item" "aws-personal").region.value }}

[work]
aws_access_key_id = {{ (bitwardenFields "item" "aws-work").access_key_id.value }}
aws_secret_access_key = {{ (bitwardenFields "item" "aws-work").secret_access_key.value }}
region = us-east-1

​
NPM Configuration

~/.npmrc.tmpl
//registry.npmjs.org/:_authToken={{ (bitwardenFields "item" "npm").token.value }}
email={{ (bitwarden "item" "npm").login.username }}

​
Multiple API Keys

~/.config/api-keys.sh.tmpl
#!/bin/bash

# Cloud providers
export AWS_ACCESS_KEY_ID="{{ (bitwardenFields "item" "aws").access_key_id.value }}"
export AWS_SECRET_ACCESS_KEY="{{ (bitwardenFields "item" "aws").secret_access_key.value }}"
export DIGITALOCEAN_TOKEN="{{ (bitwardenFields "item" "digitalocean").token.value }}"

# APIs
export GITHUB_TOKEN="{{ (bitwardenFields "item" "github").token.value }}"
export GITLAB_TOKEN="{{ (bitwardenFields "item" "gitlab").token.value }}"
export OPENAI_API_KEY="{{ (bitwardenFields "item" "openai").api_key.value }}"

# Databases
export POSTGRES_PASSWORD="{{ (bitwarden "item" "postgres").login.password }}"
export REDIS_PASSWORD="{{ (bitwarden "item" "redis").login.password }}"

​
Troubleshooting

​
Session Not Set

If you get “Session key is invalid”: 
export BW_SESSION=$(bw unlock --raw)

​
Vault Locked

bw unlock
export BW_SESSION=$(bw unlock --raw)

​
Command Not Found

Ensure Bitwarden CLI is installed: 
which bw
bw --version

​
Item Not Found

Verify the item exists: 
bw list items --search "example.com"

​
Testing Templates

Test your template functions: 
chezmoi execute-template '{{ (bitwarden "item" "test").login.username }}'

​
Enable Auto-Unlock

To avoid manually unlocking:
~/.config/chezmoi/chezmoi.toml
[bitwarden]
    unlock = "auto"

​
Best Practices

  1. Use auto-unlock: Set bitwarden.unlock = "auto" for convenience
  2. Organize items: Use clear naming conventions for items
  3. Use custom fields: Store structured data in custom fields
  4. Session management: Set BW_SESSION in your shell profile
  5. Test incrementally: Test templates before adding more complexity
  6. Use Secrets Manager: For production/CI/CD, use Bitwarden Secrets Manager

​
See Also