Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us