EnvGuard

Simple, local secret management using your OS keychain

EnvGuard is a command-line tool that stores environment variables in your operating system's secure keychain instead of .env files. Secrets stay on your machine, encrypted by the OS, and never touch your Git repository.

Documentation

For Users

• Quick Start - Get started in 5 minutes
• Commands Reference - All available commands
• Common Workflows - Real-world usage examples
• How It Works - Architecture and file structure
• Security Model - How secrets are protected

Packages

• CLI Package - Command-line interface for managing secrets
• Node.js Runtime - Drop-in dotenv replacement for Node.js
• Core Package - Core business logic (internal)

For Contributors

• Contributing Guide - Development setup and guidelines
• Development Scripts - Available npm/pnpm scripts
• Claude AI Guidelines - Instructions for AI assistants
• Project Structure - Monorepo architecture
• Roadmap - Development timeline and progress

Package-Specific Guides

• Node.js Runtime
  • Best Practices
  • Contributing Guide
  • CI/CD Guide

For Maintainers

• Quick Publish Guide - Fast reference for publishing packages
• Detailed Publishing Guide - Complete publishing documentation
• GitHub Actions Setup - CI/CD configuration
• CLI Publishing Checklist - Pre-publish verification
• CLI Publishing Guide - CLI-specific publishing steps

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 (Just Like .env Files!)

# 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 - just like editing a .env file!

# 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
# No .env file, no plaintext secrets in your repo

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

Editing Multiple Secrets

# Interactive menu - edit one or many
envg edit

# Options:
# 1. Edit all secrets
# 2. Edit specific secret
# 3. Add new secret
# 4. Cancel

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:

1. Initialize - Run envg init to set up EnvGuard in your project
2. Store - Use envg set or envg edit to save secrets to your OS keychain
3. Retrieve - Use envg get or envg show to view your secrets
4. 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.

Build and Use

EnvGuard ships as a standard Node.js CLI. Use whichever workflow matches your needs:

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 8 (recommended for development)

Option A — Run without installing

pnpm dlx @envguard/cli@latest status

Option B — Global install

npm install -g @envguard/cli
envguard status

Option C — From source (monorepo contributors)

# Install workspace dependencies
pnpm install

# Build the CLI package
pnpm --filter @envguard/cli run build

# Execute the compiled CLI
device envguard status
node packages/cli/dist/cli.cjs status

# Or use watch mode during development
pnpm --filter @envguard/cli run dev

Local linking for adjacent projects

# Link the CLI into another project without publishing
pnpm --filter @envguard/cli link --global
cd ../your-app
pnpm link @envguard/cli
envguard status

---

Commands

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 (Interactive & Easy!)

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
│   └── node/                   # Node.js runtime integration
├── package.json                # Root workspace config
└── pnpm-workspace.yaml         # Workspace definition

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

See Roadmap below for planned features.

Contributing

We welcome contributions! Please see our development workflow:

Prerequisites

• Node.js ≥18.0.0
• pnpm ≥8.0.0
• Git

Setup

# Clone the repository
git clone https://github.com/envguard/envguard.git
cd envguard

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Start development
pnpm dev

Development Scripts

Command	Description
pnpm dev	Start CLI in development mode
pnpm build	Build all packages
pnpm test	Run full test suite
pnpm lint	Lint and format code
pnpm typecheck	Type check all packages
pnpm validate	Run lint, typecheck, and tests

Package Structure

• packages/cli/ - Main EnvGuard CLI application
• packages/node/ - Node.js runtime integration

Roadmap

• Project setup and configuration
• Implementation planning
• 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
• Secret validation/schema enforcement
• Backup/restore system
• GUI application for macOS
• GUI application for Windows
• GUI application for Linux

Planned Features

• Encrypted sync between machines
• Secret rotation
• Git integration
• Python runner
• Docker integration

Support

• Documentation
• Issue Tracker
• Discussions

License

MIT © EnvGuard Contributors

See LICENSE for details.