Tutorial

In this tutorial you will encrypt a secret file into a git-safe vault and restore it on a fresh clone. Here is the end result:

$ nimvault status
------------------------------------------------------------------------
  Vault status
------------------------------------------------------------------------
  [in-sync]   ~/.config/myapp/secrets.env

Your secrets are now committed as opaque GPG blobs. Clone on another machine, run nimvault unseal, and the plaintext files reappear.

Install nimvault

# Requires Nim >= 2.0
nimble install nimvault

Verify:

nimvault --version
# nimvault 0.1.0

Set up a test repo

# Create a throwaway repo to practice with
mkdir /tmp/vault-demo && cd /tmp/vault-demo
git init

Create a secret file

# This file will be encrypted into the vault
mkdir -p ~/.config/myapp
echo "DB_PASSWORD=hunter2" > ~/.config/myapp/secrets.env

Configure the vault recipient

# Find your GPG key ID
gpg --list-keys --keyid-format long
# pub   rsa4096/9CCCE36402CB49A6 2024-01-01 [SC]
#                ^^^^^^^^^^^^^^^^ copy this

# Tell nimvault which key to encrypt to
mkdir -p .vault
echo "recipient = 9CCCE36402CB49A6" > .vault/config
# ^ replace with YOUR key ID

Add the file to the vault

nimvault add ~/.config/myapp/secrets.env
# Added:
#   id:   7f3a2b1c9e4d8f06
#   path: ~/.config/myapp/secrets.env
#   blob: .vault/7f3a2b1c9e4d8f06.gpg

The file path is stored with ~/ so it works on any machine. The ID is a random 16-char hex string.

Seal the vault

nimvault seal
# Encrypting ~/.config/myapp/secrets.env
# Sealed 1 file(s).

Commit

git add .vault/
git commit -m "vault: add myapp secrets"

Only encrypted blobs and the encrypted manifest are committed. The original filename (secrets.env) never appears in git history.

Check status

nimvault status
# [in-sync]   ~/.config/myapp/secrets.env

Simulate a fresh checkout

# Delete the plaintext to simulate a new machine
rm ~/.config/myapp/secrets.env

nimvault status
# [missing]   ~/.config/myapp/secrets.env

# Restore from the vault
nimvault unseal
# Unsealing ~/.config/myapp/secrets.env
# Unsealed 1 file(s).

# Verify the file is back (permissions: 600)
cat ~/.config/myapp/secrets.env
# DB_PASSWORD=hunter2

ls -la ~/.config/myapp/secrets.env
# -rw------- 1 user user ... secrets.env

Clean up

# Remove the demo repo and test file
rm -rf /tmp/vault-demo
rm ~/.config/myapp/secrets.env
rmdir ~/.config/myapp 2>/dev/null

Next steps