What is EnvGuard?

EnvGuard is a modern CLI tool that solves the age-old problem of managing secrets in development environments. Instead of storing sensitive data in .env files (which can accidentally end up in Git), EnvGuard uses your operating system’s native secure keychain.

The problem with .env files:

Easy to accidentally commit to Git
Stored as plaintext on disk
Shared between developers via insecure channels
No encryption, no audit trail

The EnvGuard solution:

Secrets stored in OS keychain (hardware-encrypted)
Never touch your filesystem as plaintext
Per-project isolation with namespacing
Multi-environment support built-in

What It Does

Currently Implemented:

Store secrets in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
Interactive CLI for adding, viewing, and managing secrets
Support for multiple environments (development, staging, production)
Copy secrets between environments
Security checks for .env files in your repository
Migration from existing .env files
Template generation for team onboarding

Recently Added:

Node.js Runtime - Drop-in replacement for dotenv (@envguard/node)
- Auto-loading secrets from keychain
- Multi-environment support
- Full TypeScript support
- Testing utilities included

In Development:

Secret validation and schema enforcement
Encrypted backup and restore
Python and Docker runtime support

Quick Start

Installation

# Install globally (requires Node.js 18+)
npm install -g @envguard/cli

# Or use without installing
npx @envguard/cli status

Basic Usage

# 1. Initialize in your project (one-time setup)
cd my-project
envg init

# 2. Add your secrets interactively
envg edit
# Opens interactive menu to add/edit secrets

# Or set them directly
envg set DATABASE_URL postgresql://localhost/mydb
envg set API_KEY sk_live_abc123

# 3. View your secrets (masked by default)
envg show all
# Tip: Use --reveal to see actual values

# 4. That's it! Your secrets are safely stored in your OS keychain

Migrating from .env Files

Already have a .env file? Migrate in seconds:

envg init
envg migrate  # Reads .env, stores in keychain, secures your repo
# Your secrets are now safe! The .env file can be deleted.

Common Workflows

Adding Your First Secret

# Interactive way (easiest!)
envg edit
# Select "Add new secret" and follow the prompts

# Direct way
envg set API_KEY abc123

Viewing Secrets Safely

# View all secrets (masked for security)
envg show all
# Output: API_KEY (required): ab***23

# View specific secret
envg show API_KEY

# Reveal actual value (when you need it)
envg show API_KEY --reveal

Working with Multiple Environments

# Set secrets for different environments
envg set DATABASE_URL postgres://localhost/dev
envg set DATABASE_URL postgres://prod-server/db --env production

# Copy development secrets to staging
envg copy --from development --to staging

# Copy specific secret to production (with confirmation)
envg copy API_KEY --from development --to production

# View staging environment secrets
envg show all --env staging

Checking Project Health

# Full security and secrets check
envg check

# Just check if secrets are configured properly
envg check --secrets

# Just check for security issues (.env files, etc.)
envg check --security

Generating Template for Team

# Create .env.template for your team
envg template
# Team members can see what secrets they need without seeing values!

How It Works

EnvGuard stores your secrets in your operating system’s secure keychain:

Initialize - Run envg init to set up EnvGuard in your project
Store - Use envg set or envg edit to save secrets to your OS keychain
Retrieve - Use envg get or envg show to view your secrets
Manage - Copy between environments, export templates, run security checks

my-project/
├── .envguard/
│   ├── config.json        # Project config (gitignored)
│   └── manifest.json      # Secret manifest (gitignored)
└── .env.template          # Team documentation (optional, can commit)

Where secrets are stored:

macOS: Keychain Access (Security.framework)
Windows: Credential Manager
Linux: Secret Service API (GNOME Keyring, KWallet)

Secrets are stored with a namespaced key: {package-name}:{environment}:{secret-name}

This ensures no conflicts between different projects on your machine.

Commands Reference

Getting Started

Command	Description
`envg init`	Initialize EnvGuard in current directory
`envg status`	Show EnvGuard status and configuration
`envg migrate`	Migrate from .env files to EnvGuard

Managing Secrets

Command	Description
`envg edit`	Interactive menu to add/edit secrets
`envg edit <key>`	Edit a specific secret
`envg set <key> <value>`	Quickly set a secret
`envg show all`	View all secrets (masked)
`envg show <key>`	View specific secret (use —reveal to unmask)
`envg get <key>`	Retrieve a secret value
`envg del <key>`	Delete a secret
`envg list`	List all secret keys

Environment Management

Command	Description
`envg copy --from dev --to staging`	Copy all secrets between envs
`envg copy <key> --from dev --to prod`	Copy specific secret
`envg set <key> <value> --env production`	Set secret in specific environment
`envg show all --env staging`	View secrets in specific env

Project Health

Command	Description
`envg check`	Check secrets and security issues
`envg check --secrets`	Only check missing/invalid secrets
`envg check --security`	Only check security issues (.env files, etc.)
`envg template`	Generate .env.template from current secrets

Export (Use Sparingly!)

Command	Description
`envg export --unsafe --to .env`	Export to .env file (INSECURE - be careful!)

Security Model

What EnvGuard Does:

Stores secrets in your OS keychain (hardware-encrypted, platform-specific)
Secrets are bound to your machine and can’t easily be copied
Tracks when secrets were last updated for audit purposes
Supports marking secrets as required or optional

What EnvGuard Doesn’t Do (Yet):

Schema validation of secret values
Secret rotation automation
Git hooks for preventing commits
Encrypted backup/sync between machines

EnvGuard focuses on being a simple, reliable tool for local development. For production secret management, consider dedicated solutions like HashiCorp Vault, AWS Secrets Manager, or similar.

Project Structure

This is a TypeScript monorepo using pnpm workspaces:

envguard/
├── packages/
│   ├── cli/       # Main CLI application (@envguard/cli)
│   ├── node/      # Node.js runtime integration (@envguard/node)
│   └── core/      # Core business logic (internal)
├── package.json   # Root workspace config
└── pnpm-workspace.yaml

Development Status

EnvGuard is in alpha. Core functionality works, but expect bugs and changes.

What Works:

OS keychain storage (macOS, Windows, Linux)
All CLI commands (init, set, get, edit, show, copy, check, migrate, etc.)
Multi-environment support
Interactive secret management
Security checks

In Progress:

Runtime integration (Node.js, Python, Docker)
Secret validation and schema enforcement
Encrypted backup/restore
Comprehensive test coverage

Roadmap

Completed:

Project setup and configuration
Keychain integration
Basic CLI commands
Config parser and validation
Multi-environment support
Security checks for .env files
Migration from .env files
Interactive secret management
Template generation
Copying secrets between environments
Export to .env file (unsafe) for backwards compatibility
Node.js runtime integration

Planned:

Secret validation/schema enforcement
Backup/restore system
Encrypted sync between machines
Secret rotation
Git integration
Python runner
Docker integration
GUI applications (macOS, Windows, Linux)

EnvGuard

Tech Stack