NREDF dotfiles feature a pluggable, multi-store secret management architecture powered by chezmoi. It manages developer secrets (such as GitHub API tokens for aqua and Git SSH commit signing keys) without hardcoding credentials or duplicating them across multiple password managers.
- Direct Machine Mapping: Every machine's
~/.config/chezmoi/chezmoi.tomldeclares where its credentials come from. - Multi-Store Concurrency: You can mix and match stores on a single deployment (e.g. personal secrets from Bitwarden and work secrets from KeePassXC).
- Zero Secret Duplication: SSH keys and personal access tokens remain in their primary, canonical vault items (the same items used by Bitwarden/1Password SSH agents and your browser).
- URI-Based Routing: Secret references use a lightweight URI syntax (
bitwarden:ItemName,keepassxc:ItemName,onepassword:ItemName, or raw static string). - CI & Offline Safe: If running in CI or if a secret store CLI is not available, templates degrade gracefully without crashing.
When running chezmoi init (or chezmoi init --prompt), you are prompted to choose a secrets profile preset:
| Preset | Description | Default Mappings |
|---|---|---|
personal |
Recommended for personal laptops & home workstations | aqua_github_token: bitwarden:GitHub Tokengit_signing_key: bitwarden:SSH Keymcp_servers: bitwarden:mcp-servers |
work |
Recommended for work / corporate environments | aqua_github_token: bitwarden:GitHub Tokengit_signing_key: keepassxc:Work/Git Signing Keymcp_servers: keepassxc:Work/MCP Serverskeepassxc_db: ~/Documents/Work/work.kdbx |
custom |
Prompts for custom URIs or alternative stores (e.g. 1Password) | Custom paths, nested items, or direct UUIDs |
none |
Disables external secret stores | Relies purely on static string prompts |
Secrets configured under [data.secrets] in ~/.config/chezmoi/chezmoi.toml use prefix-based routing:
[data.secrets]
profile = "work"
aqua_github_token = "bitwarden:GitHub Token"
git_signing_key = "keepassxc:Work/Git Signing Key"| Prefix | Secret Provider | Extraction Details |
|---|---|---|
bitwarden:<item> or bw:<item> |
Bitwarden CLI (bw) |
SSH Key: .sshKey.publicKey (native SSH item), .notes, or field publicKey.Token: .login.password, field token, aqua_github_token or password, falling back to notes. |
keepassxc:<item> |
KeePassXC CLI (keepassxc-cli) |
SSH Key: attribute public_key or entry Notes.Token: entry Password or Notes. |
onepassword:<item> or op:<item> |
1Password CLI (op) |
SSH Key: field public_key or notes.Token: field password or token, falling back to notes. |
| (no prefix) | Raw string fallback | Treated as a static string literal (e.g. ssh-ed25519 AAA...). |
You can query multiple password managers in a single chezmoi apply run.
On a work machine, you may want aqua package downloads authenticated via your personal GitHub token, while Git commits are signed with a corporate key inside KeePassXC.
In ~/.config/chezmoi/chezmoi.toml:
# 1. Configure provider CLIs
[bitwarden]
command = "bw"
unlock = "auto"
[keepassxc]
command = "keepassxc-cli"
database = "C:/Users/username/Documents/Work/work.kdbx"
prompt = true
# 2. Map credentials to their respective stores
[data.secrets]
profile = "work"
aqua_github_token = "bitwarden:GitHub Token"
git_signing_key = "keepassxc:Work/Git Signing Key"During chezmoi apply:
- Chezmoi calls
bwto retrieveGitHub Token(prompting for unlock if locked). - Chezmoi calls
keepassxc-clito retrieveWork/Git Signing Key(prompting for KDBX password if required). - Both tools receive their credentials in a single apply step.
-
Template:
home/dot_config/private_nredf/private_aqua-vault.env.tmpl -
Target:
~/.config/nredf/aqua-vault.env(permissions0600) -
Variables Exported:
export AQUA_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
-
Deliberately not exported as
GITHUB_TOKEN:ghand other GitHub tools preferGITHUB_TOKEN/GH_TOKENover their own login, so a low-privilege aqua token under that name would silently replace your fullgh auth login. aqua readsAQUA_GITHUB_TOKENfirst anyway. AGITHUB_TOKEN=line left in an olderaqua-vault.env/aqua.envis ignored by the shell readers. -
Automatically sourced by:
- Bash / Zsh (
dot_local/share/nredf/shell/common/functions/nredf_aqua.bash) - Fish (
dot_local/share/nredf/shell/fish/functions/nredf_aqua.fish) - PowerShell (
dot_local/share/nredf/shell/pwsh/Defaults.ps1) - Post-apply aqua run-onchange hooks on Linux, macOS, and Windows.
- Nushell reads it too (
dot_local/share/nredf/shell/nushell/functions/nredf_aqua.nu), but — like PowerShell — parses it as plain[export] KEY=valuedata rather than sourcing/evaluating it as code, since it's POSIX-shell syntax and neither nu nor PowerShell can execute that directly.
- Bash / Zsh (
-
Not the same file as
~/.config/nredf/aqua.env: that one is written at runtime bynredf_aqua_token_setup --env(the fallback for machines without a vault configured), never by chezmoi. The two are deliberately separate files — chezmoi would otherwise delete a manually-configured token on everyapplywhenever this vault lookup comes back empty. Every consumer above sourcesaqua-vault.envfirst, thenaqua.env, so the runtime one can override.
-
Template:
home/dot_config/git/config.tmpl -
Target:
~/.config/git/config -
Output:
[user] signingkey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@email.com" [commit] gpgsign = true [gpg] format = ssh
-
When using Bitwarden or 1Password, the private key stays securely inside the password manager's desktop SSH Agent — only the public key string is rendered into
git/config.
MCP server definitions usually carry bearer tokens and API keys, so they are kept in your vault rather than in this repo. mcp_servers points at a vault item whose notes hold the definitions as YAML (or JSON):
servers:
docs:
url: https://mcp.example.com/mcp
headers:
Authorization: Bearer <token>
local-tool:
command: npx
args: ["-y", "some-mcp-server"]
env:
API_KEY: <key>- Rendered to:
~/.config/nredf/mcp.json(the single private copy the sync scripts read), VS Code'smcp.json, the Cline settings file, and~/.gemini/config/mcp_config.json. Every one of these isprivate_(mode0600); VS Code's paths are per-OS (~/.config/Codeon Linux only,~/Library/Application Support/Codeon macOS,%APPDATA%\Codeon Windows). - Claude Code:
run_onchange_after_claude_mcp.sh.tmpl(and its PowerShell twin) merges the servers into~/.claude.json.- It merges into your existing
mcpServersrather than replacing them, so servers you added withclaude mcp addsurvive. - If the vault is locked or the item is empty it does nothing instead of wiping the file. The trade-off: removing a server from the vault does not remove it from
~/.claude.json.
- It merges into your existing
- With
mcp_serversempty, the editor files are still rendered but with no servers, and~/.claude.jsonis left untouched.
- GitHub Item:
- Create a Login or Secure Note named
GitHub Token. - Put your GitHub Personal Access Token (PAT with
read:packagesor public repo access) in the Password field (or custom fieldtoken).
- Create a Login or Secure Note named
- SSH Key Item:
- Create an SSH Key item named
SSH Key. - Store your private and public key. (Bitwarden Desktop SSH Agent will automatically serve this key for daily Git and SSH operations).
- Create an SSH Key item named
- Create an entry named
Work/Git Signing Key. - Add the public key in an attribute named
public_keyor in the entry Notes.
Run chezmoi init:
chezmoi initAlready initialised? The prompts use
promptStringOnce, which keeps the value stored in~/.config/chezmoi/chezmoi.tomland does not ask again. To change a preset or a vault item name, runchezmoi init --prompt, or edit that file directly.
Choose your preset:
- For personal machines, select
personal. - For work machines, select
workand provide your.kdbxpath. - When prompted for
Git signing key, leave it blank to automatically resolve from your secret store.
chezmoi applyChezmoi will unlock your secret store(s), retrieve the credentials, and populate your configurations.
You can test template resolution in your terminal without modifying files:
# Verify Git signing key resolution
chezmoi execute-template '{{ includeTemplate "get-signing-key.tmpl" . }}'
# Verify GitHub token resolution
chezmoi execute-template '{{ includeTemplate "get-github-token.tmpl" . }}'chezmoi apply --dry-run# On Unix:
cat ~/.config/nredf/aqua-vault.env # chezmoi/vault-derived
cat ~/.config/nredf/aqua.env # runtime-local (nredf_aqua_token_setup --env)
# On Windows (PowerShell):
Get-Content "$HOME\.config\nredf\aqua-vault.env"
Get-Content "$HOME\.config\nredf\aqua.env"When running in automated CI environments (CI=true) or when NREDF_NO_BOOTSTRAP is set to any non-empty value, all secret lookups safely return empty strings, preventing interactive CLI prompts or failed builds.