vault — Encrypted .env Backup

vault is a centralized encrypted backup manager for .env files across all your projects. It uses SOPS (Secrets OPerationS) with GPG encryption to securely store environment variables in a central location at ~/Git/dotenvs/.

Installation

Part of the claude-code-tools package. See Quick Start for installation.

How It Works

1. Central Storage — All encrypted backups live in ~/Git/dotenvs/
2. Project-based — Each project’s .env file is backed up with the project directory name (e.g., myproject.env.encrypt)
3. GPG Encryption — Uses your GPG key to encrypt and decrypt files
4. Smart Sync — Automatically detects which version is newer and syncs accordingly
5. Safety First — Always creates timestamped backups before overwriting

Requirements

Before using vault, ensure you have:

• A GPG key configured on your system
• SOPS installed (brew install sops on macOS)

Commands

sync

vault sync

Smart synchronization that automatically detects the sync direction:

• If only local .env exists, encrypts to vault
• If only vault backup exists, decrypts to local
• If local is newer, encrypts to vault (with confirmation)
• If vault is newer, decrypts to local (with confirmation)

vault sync           # Auto-detect direction
vault sync --push    # Force local -> vault
vault sync --pull    # Force vault -> local

encrypt

vault encrypt

Explicitly encrypt your local .env file to the centralized vault:

vault encrypt

Features:

• Creates a timestamped backup if the encrypted file already exists
• Requires confirmation before overwriting existing backups

decrypt

vault decrypt

Explicitly decrypt from the centralized vault to your local .env:

vault decrypt

Features:

• Creates a timestamped backup of the current .env before overwriting
• Warns if the local .env is newer than the backup
• Requires confirmation in case of conflicts

list

vault list

List all encrypted backups in the central vault:

vault list

Shows all .env.encrypt files in ~/Git/dotenvs/ with their sizes.

status

vault status

Show detailed sync status for the current project:

vault status

Displays:

• Whether the local .env exists
• Whether a backup exists in the vault
• Which version is newer (with timestamps)
• Sync status (in sync, local newer, backup newer, etc.)

Workflow Examples

Initial Setup

1. Navigate to your project directory:

   cd myproject

2. Create your .env file with the required secrets.

3. Back up to the central vault:

   vault encrypt

Cloning a Project

1. Clone the repository:

   git clone https://github.com/user/project
   cd project

2. Restore .env from the central vault:

   vault decrypt

Regular Development

1. After modifying your .env file, sync to vault:

   vault sync  # Automatically encrypts to vault

2. On a different machine, pull the latest:

   vault sync  # Automatically decrypts newer version

Conflict Resolution

When both local and vault versions exist but differ:

1. Check which version is newer:

   vault status

2. Force the direction you want:

   vault sync --push  # Force local -> vault
   vault sync --pull  # Force vault -> local

Security Notes

Caution

The central vault directory (~/Git/dotenvs/) should be included in your regular backups. Consider version controlling the encrypted files for additional safety.

• Files are encrypted using your GPG key
• Only you can decrypt the files (with your private key)
• Encrypted files are safe to store in version control
• Timestamped backups protect against accidental overwrites

Troubleshooting

”No GPG key found”

Generate a GPG key:

gpg --gen-key

Follow the prompts to create a new key pair. Once created, vault will automatically detect and use it.

”SOPS not found”

Install SOPS for your platform:

macOS

brew install sops

Linux

Download the latest release from the SOPS releases page.

Permission Issues

Ensure you have write access to the vault directory:

mkdir -p ~/Git/dotenvs
chmod 700 ~/Git/dotenvs

The 700 permission ensures only your user can read, write, or list the directory contents.