envseal-vault 0.2.0

Secure, centralized environment variable management for AI coding era - SOPS + age encryption for multi-project .env files

🔐 EnvSeal

Secure, centralized environment variable management for the AI coding era

English | 中文

---

🤖 Why EnvSeal for AI Coding?

The reality of AI-powered development: project explosion

Working with Claude Code, Cursor, Gemini CLI, or Windsurf? You know the drill:

• 🚀 Today: 3 new demos
• 🎯 Tomorrow: 5 more repos
• 📂 Each one: .env, .env.dev, .env.prod

Then what happens?

• 💔 Migration Pain: Switching machines? The hardest part isn't code—it's "where are all those .env files?"
• 🔀 Sync Chaos: Updated DATABASE_URL in project A, forgot about project B
• ⚠️ Leakage Risk: AI screenshots, logs, and shares easily expose secrets
• 🚫 Onboarding Nightmare: New developer clones in 30 seconds, spends 3 hours hunting for credentials

EnvSeal's Solution:

Scan repos → Normalize .env → Encrypt with SOPS → Unified Git vault → One-command recovery

📖 What is EnvSeal?

EnvSeal is a CLI tool that helps you manage .env files across multiple repositories with end-to-end encryption. It scans your projects, normalizes environment files, and syncs them to a Git-backed vault using SOPS encryption.

Key Benefits:

• 🔒 Secure: SOPS + age encryption (modern, battle-tested)
• 📦 Centralized: One vault for all secrets across unlimited projects
• 🔍 Safe Diffs: Key-only diffs never expose values
• 🔄 Version Control: Full Git history for audit and rollback
• 🚀 Simple: One command to sync everything
• 💻 Multi-Device: Restore entire dev environment in minutes

🧭 Architecture at a Glance

graph LR
  Dev((Developer))
  CLI[EnvSeal CLI]
  Repos[[Projects<br/>.env* files]]
  Vault[(Private secrets-vault<br/>Git repo)]
  Dev -->|init / push / pull| CLI
  CLI -->|scan & normalize .env*| Repos
  CLI -->|encrypt via SOPS+age| Vault
  Vault -->|pull decrypt| CLI
  CLI -->|write .env to temp or project| Dev

🎯 Use Cases

• 🤖 AI Coding / Vibe Coding: Using Claude Code/Cursor? Manage 10+ projects without env chaos
• 💻 Multi-Device Development: Work laptop ↔ Home desktop ↔ GitHub Codespaces
• 🔄 Environment Migration: New machine? One command restores all project secrets
• 👥 Team Collaboration: Share secrets securely via private vault (supports multiple age keys)
• 🔐 Secret Rotation: Git history tracks "who changed what key and why"

⚡ Quick Start

📋 Complete First-Time Setup (Beginner-Friendly)

Step 1: Create Your Secrets Vault Repository

1. Go to GitHub and create a new private repository

   • Repository name suggestions: secrets-vault or my-secrets
   • ⚠️ Must be Private
   • Don't add README, .gitignore, etc. (create empty repo)

2. Clone it locally:

   # Replace USERNAME with your GitHub username
   # Replace secrets-vault with your repository name
   cd ~/Github  # Or wherever you keep your code
   git clone [e-mail]:USERNAME/secrets-vault.git
   

Step 2: Locate Your "Projects Root Directory"

This is the folder that contains all your projects, for example:

~/Github/                    ← This is your "root directory"
├── my-api/                 ← Project 1 (has .env files)
├── my-web/                 ← Project 2 (has .env files)
├── my-worker/              ← Project 3 (has .env files)
└── secrets-vault/          ← Your vault repo you just created

Step 3: Install and Initialize EnvSeal

Continue with the steps below 👇

Prerequisites

# macOS
brew install age sops

# Verify installation
age-keygen --version
sops --version

Installation

# Install with pipx (recommended)
pipx install envseal-vault

# Or with pip
pip install envseal-vault

# Verify
envseal --version

Initialize

# Navigate to your "projects root directory" (the folder containing all your projects)
cd ~/Github  # Replace with your actual directory, e.g., ~/projects or ~/code

# Run initialization
envseal init

During initialization, it will:

1. ✅ Generate an age encryption key
2. 🔍 Scan current directory for all Git repositories (finds my-api, my-web, etc.)
3. 📝 Create configuration at ~/.config/envseal/config.yaml
4. 🗂️ Ask for your vault path (enter: ~/Github/secrets-vault)

Sync Secrets

# Push all .env files to vault (encrypted)
envseal push

# Commit to YOUR secrets vault (the private repo you created)
cd ~/Github/secrets-vault  # Your vault repo, NOT the envseal tool repo
git add .
git commit -m "Add encrypted secrets"
git push

Check Status

envseal status

Output:

📊 Checking secrets status...

my-project
  ✓ .env       - up to date
  ⚠ .env.prod  - 3 keys changed

api-service
  + .env       - new file (not in vault)
  ✓ .env.prod  - up to date

Update Changed Secrets (Interactive)

# Interactively select and update changed secrets
envseal update

# Only show changes for specific environment
envseal update --env prod

The update command will:

1. Scan all repositories for changed .env files
2. Show an interactive selection menu
3. Let you choose which repos to update
4. Push selected changes to the vault
5. Show next steps for git commit/push

📚 Commands

Command	Description	Options
envseal init	Initialize configuration and generate keys	--root DIR
envseal push [repos...]	Encrypt and push secrets to vault	--env ENV
envseal status	Show sync status for all repos	-
envseal update	Interactively update changed secrets to vault	--env ENV
envseal diff REPO	Show key-only changes	--env ENV
envseal pull REPO	Decrypt and pull from vault	--env ENV, --replace, --stdout

🔄 Push / Status Flow (Key-Only)

sequenceDiagram
  participant Dev
  participant CLI as EnvSeal CLI
  participant SOPS
  participant Vault as secrets-vault repo
  Dev->>CLI: envseal push
  CLI->>CLI: scan repos & map env files
  CLI->>SOPS: normalize .env* and encrypt (age)
  SOPS-->>CLI: encrypted files
  CLI->>Vault: write secrets/<repo>/<env>.env
  Dev->>Vault: git add/commit/push (manual)

🚀 New Machine? Restore Everything in 10 Minutes

Just 4 steps:

1. 📋 Copy age private key (from password manager)
2. 📦 Clone your secrets vault repository
3. 🔧 Install EnvSeal: pipx install envseal-vault
4. ⬇️ Pull secrets: envseal pull <project> --env <environment> --replace

See detailed steps in the "Multi-Device Setup" section below 👇

🔐 Security

Age Key Management:

• Private key: ~/Library/Application Support/sops/age/keys.txt (macOS), ~/.config/sops/age/keys.txt (Linux), ~/AppData/Local/sops/age/keys.txt (Windows) (NEVER commit!)
• Public key: Stored in vault/.sops.yaml (safe to commit)

Backup Your Private Key:

# Display full key file
cat ~/Library/Application\ Support/sops/age/keys.txt

# Save to password manager (1Password, Bitwarden, etc.)

Linux/Windows users: use the OS-specific key path listed in Age Key Management.

⚠️ Critical: Losing your private key = permanent data loss!

Vault Repository Best Practices:

• ✅ Keep vault repository private (even though files are encrypted)
• ✅ Enable branch protection and require PR reviews
• ✅ Use GitHub's secret scanning push protection
• ✅ Backup private key in password manager

See SECURITY.md for complete security model.

🌍 Multi-Device Setup

Two repositories you need to know:

• 📦 EnvSeal tool: chicogong/envseal (this repo - install via PyPI, no need to clone)
• 🔐 Your secrets vault: USERNAME/my-secrets-vault (your private repo for encrypted .env files)

On a new machine:

1. Copy your age key from backup:

   mkdir -p ~/Library/Application\ Support/sops/age/
   nano ~/Library/Application\ Support/sops/age/keys.txt
   # Paste the 3-line key file (created, public key, private key)
   chmod 600 ~/Library/Application\ Support/sops/age/keys.txt
   

   Linux/Windows users: use the OS-specific key path listed in Security.

2. Clone YOUR secrets vault and install EnvSeal tool:

   # Clone YOUR vault (NOT the envseal tool repo)
   git clone [e-mail]:USERNAME/my-secrets-vault.git ~/Github/secrets-vault
   
   # Install EnvSeal tool from PyPI
   pipx install envseal-vault
   envseal init
   

3. Pull secrets:

   envseal pull my-project --env prod --replace
   

📁 Configuration

Location: ~/.config/envseal/config.yaml

vault_path: /path/to/secrets-vault
repos:
  - name: my-api
    path: /Users/you/projects/my-api
  - name: web-app
    path: /Users/you/projects/web-app
env_mapping:
  ".env": "local"
  ".env.dev": "dev"
  ".env.prod": "prod"
  ".env.staging": "staging"
scan:
  include_patterns:
    - ".env"
    - ".env.*"
  exclude_patterns:
    - ".env.example"
    - ".env.sample"
  ignore_dirs:
    - ".git"
    - "node_modules"
    - "venv"

🛠️ Development

Only for contributing to EnvSeal tool itself:

# Clone the EnvSeal TOOL repository (for development)
git clone https://github.com/chicogong/envseal.git
cd envseal

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
make lint
make format

# Type check
make type-check

Note: Regular users don't need to clone this repo - just pipx install envseal-vault

📝 Documentation

• USAGE.en.md - Complete usage guide (English)
• USAGE.md - 完整使用指南（中文）
• SECURITY.md - Security model and best practices
• PUBLISHING.md - Guide for publishing to PyPI

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📄 License

Apache-2.0 License - see LICENSE for details.

---

Built for developers navigating the AI coding era

PyPI · Report Bug · Request Feature