Migration Guides

Step-by-step guides to switch from other secret management tools to xenvsync.

From dotenv-vault

dotenv-vault uses a cloud service to manage encrypted vaults. xenvsync does everything locally with no cloud dependency.

1. Export your secrets

If you have a .env.vault from dotenv-vault, you need to decrypt it first using your DOTENV_KEY:

# Decrypt your dotenv-vault secrets to a plain .env file
# (use your dotenv-vault tooling or dashboard to export)
npx dotenv-vault@latest pull

# Verify your .env has all expected variables
cat .env

2. Set up xenvsync

# Initialize xenvsync (generates encryption key)
xenvsync init

# Encrypt your .env
xenvsync push

# Verify the vault
xenvsync verify

3. Clean up dotenv-vault

# Remove dotenv-vault artifacts (keep .env.vault — xenvsync already overwrote it)
rm -f .env.keys

# Remove dotenv-vault from dependencies
npm uninstall dotenv-vault

# Commit the new xenvsync vault
git add .env.vault .gitignore
git commit -m "Migrate from dotenv-vault to xenvsync"

4. Verify

# Delete .env and restore from vault
rm .env
xenvsync pull
cat .env  # should match your original secrets

# Test in-memory injection
xenvsync run -- env | grep YOUR_KEY

Key differences: xenvsync vaults are not compatible with dotenv-vault vaults. The .env.vault file format is different. xenvsync uses AES-256-GCM with a local key, while dotenv-vault uses a cloud-managed key.

From sops

sops encrypts individual values within YAML/JSON/ENV files. xenvsync encrypts the entire .env file as a single unit.

1. Export your secrets

# Decrypt your sops-encrypted file to plain .env
sops -d secrets.enc.env > .env

# Or from YAML/JSON:
sops -d secrets.yaml | yq -r 'to_entries[] | "\(.key)=\(.value)"' > .env

2. Set up xenvsync

# Initialize xenvsync
xenvsync init

# Encrypt your .env
xenvsync push

# Verify
xenvsync diff  # should show no differences

3. Clean up sops

# Remove sops-encrypted files
rm -f secrets.enc.env secrets.yaml
rm -f .sops.yaml

# Update .gitignore if needed
# (xenvsync init already added .xenvsync.key and .env)

# Commit
git add .env.vault .gitignore
git rm secrets.enc.env .sops.yaml  # if tracked
git commit -m "Migrate from sops to xenvsync"

4. Verify

rm .env
xenvsync pull
xenvsync verify

Key differences: sops supports KMS, PGP, and age keys with per-value encryption. xenvsync uses a single AES-256-GCM key (or X25519 team keys) and encrypts the entire file. If you need per-value encryption or cloud KMS integration, sops may be a better fit.

From git-crypt

git-crypt transparently encrypts files in a Git repo. xenvsync uses explicit push/pull commands and encrypts only .env files.

1. Export your secrets

# Ensure your repo is unlocked (files are decrypted in working tree)
git-crypt unlock

# Copy your .env (it's already in plaintext when unlocked)
cp .env .env.backup

# Verify contents
cat .env

2. Remove git-crypt

# Lock first to see what was encrypted
git-crypt lock

# Remove git-crypt configuration
rm -rf .git-crypt/
rm -f .gitattributes  # or remove git-crypt filter lines

# Unlock to restore plaintext
git-crypt unlock

3. Set up xenvsync

# Initialize xenvsync
xenvsync init

# Restore .env if needed
cp .env.backup .env

# Encrypt
xenvsync push

# Verify
xenvsync verify

4. Commit the migration

git add .env.vault .gitignore
git commit -m "Migrate from git-crypt to xenvsync"

# Clean up backup
rm .env.backup

Key differences: git-crypt encrypts transparently on git operations and works with any file type. xenvsync is focused specifically on .env files and adds features like in-memory injection (run), multi-environment support, and vault diff/status.

Team Migration

If your team uses xenvsync's V2 (team) mode, follow these additional steps after any migration:

# Each team member generates their keypair (once)
xenvsync keygen

# Share public keys and add to roster
xenvsync team add alice <alice-public-key>
xenvsync team add bob <bob-public-key>

# Re-push to create V2 vault with per-member encryption
xenvsync push

# Commit the roster and vault
git add .xenvsync-team.json .env.vault
git commit -m "Enable V2 team vault"

Feature Comparison

Feature	xenvsync	dotenv-vault	sops	git-crypt
No cloud required	Yes	No	Yes	Yes
In-memory injection	Yes	No	No	No
Multi-environment	Yes	Yes	Manual	No
Team sharing	X25519	Cloud	KMS/PGP	GPG
Key rotation	Yes	Cloud	Manual	No
Diff / audit log	Yes	No	Partial	No
Single binary	Yes	No	Yes	No
Passphrase protection	Yes	No	No	No

PreviousInstallation Next FAQ