Environment file encryption and management tool
npm install envx-cliEnvironment file encryption and management tool for secure development workflows.


- Overview
- Features
- Prerequisites
- Installation
- Quick Start
- Commands
- envx init
- envx create
- envx encrypt
- envx decrypt
- envx interactive
- envx list
- envx copy
- envx status
- envx config
- Configuration
- .envrc File
- .envxrc File (Project Config)
- Secret Variable Naming
- Environment Filtering
- File Structure
- Workflow Examples
- Basic Workflow
- Deployment Workflow
- Team Workflow
- Multi-Service Management
- Batch Operations
- Copy to .env Workflow
- Dry Run Workflow
- Security Best Practices
- Integration with Direnv
- Troubleshooting
- API Reference
- Environment Variables
- Exit Codes
- Testing
- Running Tests
- Testing Philosophy
- Test Coverage
- Test Structure
- Development
- Building from Source
- Architecture
- Development Workflow
- Contributing
- Changelog
- License
- Support
EnvX is a command-line tool that helps you securely manage environment files across different stages (development, staging, production) using GPG encryption. It provides a simple workflow for encrypting sensitive environment variables while maintaining ease of use for development teams.
- GPG-based encryption for maximum security
- Stage-based management (development, staging, production, etc.)
- Interactive setup with guided configuration
- Batch operations on multiple files and directories
- Secret management with .envrc integration
- Project configuration via .envxrc for per-project ignore patterns and environment tracking
- Environment filtering to auto-ignore non-secret files (example, sample, template)
- Dry run mode to preview operations without making changes
- Config management CLI for managing project settings without editing JSON
- Beautiful CLI with colored output and progress indicators
- Best practices enforcement and security recommendations
Before using EnvX, ensure you have:
- Node.js >= 14.0.0
- GPG (GNU Privacy Guard) installed and configured
#### macOS
``bash`
brew install gnupg
#### Ubuntu/Debian
`bash`
sudo apt-get install gnupg
#### Windows
Download from https://gnupg.org/download/
#### Verify Installation
`bash`
gpg --version
`bash`
npm install -g envx-cli
`bash`
npm install envx-cli
npx envx --help
1. Initialize EnvX in your project:
`bash`
envx init
2. Create environment files:
`bash`
envx create -e development
envx create -e production
3. Set up secrets for encryption:
`bash`
envx interactive
4. Encrypt your environment files:
`bash`
envx encrypt -e production
5. Commit encrypted files to git:
`bash`
git add *.gpg
git commit -m "Add encrypted environment files"
6. Copy environment to .env for use:
`bash`
envx copy -e production
7. Decrypt when needed:
`bash`
envx decrypt -e production
Initialize EnvX in a new project with guided setup.
`bash`
envx init
The init wizard will:
1. Verify GPG is available
2. Discover existing environment files, auto-ignoring non-secret files (example, sample, template)
3. Let you select which environments to manage via checkbox prompt
4. Offer to add non-selected environments to the ignore list in .envxrc.envxrc
5. Save your selected environments to .gitignore
6. Update with recommended patterns
7. Optionally start interactive secret setup
8. Optionally encrypt your environment files immediately after setup
Options:
- -c, --cwd - Working directory
Create new environment files.
`bashCreate a single environment file
envx create -e development
Options:
-
-e, --environment - Environment name
- -t, --template - Template file path
- -i, --interactive - Interactive mode
- --overwrite - Overwrite existing files
- -c, --cwd - Working directory$3
Encrypt environment files using GPG.
`bash
Encrypt specific environment
envx encrypt -e productionEncrypt all environments at once
envx encrypt --allPreview what would be encrypted (no changes made)
envx encrypt -e production --dry-runUse custom secret from .envrc
envx encrypt -e production -s CUSTOM_SECRETInteractive file selection (for single environment)
envx encrypt -e staging -iEncrypt all with specific passphrase
envx encrypt --all -p "your-passphrase"Overwrite existing encrypted files
envx encrypt -e production --overwrite
`Options:
-
-e, --environment - Environment name (required unless using --all)
- -a, --all - Process all available environments
- -p, --passphrase - Encryption passphrase
- -s, --secret - Secret variable name from .envrc
- -i, --interactive - Interactive file selection (disabled with --all)
- --overwrite - Overwrite existing encrypted files
- --dry-run - Show what would happen without making changes
- -c, --cwd - Working directory$3
Decrypt environment files.
`bash
Decrypt specific environment
envx decrypt -e productionDecrypt all environments at once
envx decrypt --allPreview what would be decrypted (no changes made)
envx decrypt -e production --dry-runOverwrite existing files without confirmation
envx decrypt -e development --overwriteDecrypt all with overwrite flag
envx decrypt --all --overwriteInteractive file selection (for single environment)
envx decrypt -e staging -i
`Options:
-
-e, --environment - Environment name (required unless using --all)
- -a, --all - Process all available environments
- -p, --passphrase - Decryption passphrase
- -s, --secret - Secret variable name from .envrc
- -i, --interactive - Interactive file selection (disabled with --all)
- --overwrite - Overwrite existing files without confirmation
- --dry-run - Show what would happen without making changes
- -c, --cwd - Working directory$3
Interactive setup for
.envrc file with secrets.`bash
Start interactive setup
envx interactiveOverwrite existing .envrc
envx interactive --overwriteGenerate random secrets for all environments
envx interactive --generate
`Options:
-
--overwrite - Overwrite existing .envrc file
- --generate - Generate random secrets
- -c, --cwd - Working directory$3
List all environment files and their status. Automatically filters out non-secret environments (example, sample, template) based on your ignore patterns.
`bash
List all environment files
envx listShort alias
envx ls
`Options:
-
-c, --cwd - Working directory$3
Copy environment file from a specific stage to
.env. This command is perfect for deployment scenarios where you need to activate a specific environment configuration.`bash
Copy production environment to .env (single directory)
envx copy -e productionCopy to ALL directories with environment files (multi-service)
envx copy -e production --allCopy development environment to .env
envx copy -e developmentCopy with overwrite (no confirmation)
envx copy -e staging --overwriteCopy from encrypted file (auto-decrypts)
envx copy -e production -p "your-passphrase"Use secret from .envrc for encrypted files
envx copy -e production -s PRODUCTION_SECRETCopy production to all services from project root
envx copy -e production --all --overwrite
`Options:
-
-e, --environment - Environment name (required)
- -a, --all - Process all directories with environment files
- -p, --passphrase - Passphrase for decryption (if source is encrypted)
- -s, --secret - Secret variable name from .envrc
- --overwrite - Overwrite existing .env file without confirmation
- -c, --cwd - Working directoryHow it works:
- Single directory mode: Copies
.env. to .env in current directory
- Multi-directory mode (--all): Finds all directories with environment files and copies to each
- If .env. exists (unencrypted), it copies directly to .env
- If .env. exists (encrypted), it decrypts and copies to .env
- Prefers unencrypted files over encrypted ones if both exist
- Creates backup of existing .env file during encrypted operations
- Shows security warnings when copying production environments$3
Show project encryption status and recommendations. Automatically filters out non-secret environments based on your ignore patterns.
`bash
envx status
`Options:
-
-c, --cwd - Working directory$3
Manage project configuration stored in
.envxrc without editing JSON manually.####
envx config showDisplay the current
.envxrc configuration, showing both custom settings and defaults.`bash
envx config show
`####
envx config ignore listList all current ignore patterns (from
.envxrc or defaults).`bash
envx config ignore list
`####
envx config ignore add Add a pattern to the ignore list. Environments matching this pattern will be excluded from operations like
--all, list, and status.`bash
Ignore the "test" environment
envx config ignore add testIgnore a custom environment name
envx config ignore add local-dev
`####
envx config ignore remove Remove a pattern from the ignore list.
`bash
envx config ignore remove test
`####
envx config exclude listList all excluded directories (from
.envxrc or defaults). These directories are skipped during environment file discovery, which is useful in monorepos and projects with build artifacts.`bash
envx config exclude list
`####
envx config exclude add Add a directory to the exclusion list.
`bash
Exclude Vercel build output
envx config exclude add .vercelExclude a custom build directory
envx config exclude add out
`####
envx config exclude remove Remove a directory from the exclusion list.
`bash
envx config exclude remove build
`####
envx config resetReset the configuration to defaults, removing all custom ignore patterns and directory exclusions.
`bash
envx config reset
`Configuration
$3
EnvX uses
.envrc files to store encryption secrets. The format follows the direnv convention:`bash
Environment secrets generated by envx
export DEVELOPMENT_SECRET="your-development-secret"
export STAGING_SECRET="your-staging-secret"
export PRODUCTION_SECRET="your-production-secret"
`$3
EnvX supports a
.envxrc JSON file in your project root for per-project configuration. This file is automatically managed by envx init and envx config commands.`json
{
"ignore": ["example", "sample", "template", "local-dev"],
"environments": ["development", "staging", "production"],
"excludeDirs": ["node_modules", ".git", "dist", ".next", ".turbo", "build"]
}
`Fields:
| Field | Type | Description |
| -------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
ignore | string[] | Patterns to exclude from environment discovery. Environments whose names match any pattern (case-insensitive) are filtered from --all, list, and status operations. Defaults to ["example", "sample", "template"] if not set. |
| environments | string[] | List of managed environments. Set during envx init based on your selection. |
| excludeDirs | string[] | Directories to exclude from file discovery. Prevents scanning into build artifacts and dependency directories. Defaults to ["node_modules", ".git", "dist", ".next", ".turbo", ".output", ".nuxt", ".cache", "build", "coverage", ".svelte-kit"]. |You can manage this file through the CLI:
`bash
View current config
envx config showAdd a custom ignore pattern
envx config ignore add testRemove a pattern
envx config ignore remove sampleAdd a directory exclusion
envx config exclude add .vercelRemove a directory exclusion
envx config exclude remove buildReset to defaults
envx config reset
`Or edit
.envxrc directly as JSON.$3
EnvX follows the convention:
Examples:
-
DEVELOPMENT_SECRET
- STAGING_SECRET
- PRODUCTION_SECRET
- LOCAL_SECRET$3
EnvX automatically filters non-secret environment files from discovery operations. By default, files matching
example, sample, or template are excluded.This filtering applies to:
-
envx encrypt --all / envx decrypt --all (batch operations)
- envx list (environment listing)
- envx status (project status)
- envx init (environment discovery)How it works:
1. If
.envxrc exists with an ignore field, those patterns are used
2. If no .envxrc exists or ignore is not set, the defaults are used: ["example", "sample", "template"]
3. Pattern matching is case-insensitive (.env.Example matches pattern example)Customizing filters:
`bash
Add a custom pattern
envx config ignore add testRemove a default pattern (to include it in operations)
envx config ignore remove templateSee current patterns
envx config ignore list
`Bypass filtering: Pass an explicit empty ignore list programmatically via
findAllEnvironments(cwd, []) to include all environments.#### Directory Exclusion (Monorepo Support)
EnvX automatically excludes build artifact and dependency directories from file discovery. This prevents
.env.* files duplicated inside node_modules, .next, dist, .turbo, and other directories from appearing as spurious results.Default excluded directories:
node_modules, .git, dist, .next, .turbo, .output, .nuxt, .cache, build, coverage, .svelte-kitCustomizing exclusions:
`bash
View current exclusions
envx config exclude listAdd a directory
envx config exclude add .vercelRemove a directory (e.g., to scan build output)
envx config exclude remove build
`$3
`
your-project/
āāā .env.development # Unencrypted (local only)
āāā .env.staging.gpg # Encrypted (committed)
āāā .env.production.gpg # Encrypted (committed)
āāā .envrc # Secrets (local only)
āāā .envxrc # Project config (local only)
āāā .gitignore # Excludes .env. but allows .gpg
`Workflow Examples
$3
1. Create environment files:
`bash
envx create -e development
envx create -e production
`2. Edit your environment files:
`bash
Edit .env.development
echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> .env.development
echo "API_KEY=dev-api-key" >> .env.developmentEdit .env.production
echo "DATABASE_URL=postgresql://prod-server:5432/myapp" >> .env.production
echo "API_KEY=prod-api-key-secret" >> .env.production
`3. Set up encryption secrets:
`bash
envx interactive
`4. Encrypt production secrets:
`bash
envx encrypt -e production
`5. Copy environment for application use:
`bash
For development
envx copy -e developmentFor production deployment
envx copy -e production
`6. Add to version control:
`bash
echo ".env.*" >> .gitignore
echo "!*.gpg" >> .gitignore
git add .env.production.gpg .envrc
git commit -m "Add encrypted production environment"
`$3
1. Single service deployment:
`bash
On production server after pulling latest code
envx copy -e production --overwrite
`2. Multi-service deployment (from project root):
`bash
Copy production environment to ALL services at once
envx copy -e production --all --overwrite
`3. For local development with production data:
`bash
Copy production environment locally (be careful!)
envx copy -e productionOr copy to all services locally
envx copy -e production --all
`4. Switch between environments easily:
`bash
Use development environment across all services
envx copy -e development --all --overwriteSwitch to staging across all services
envx copy -e staging --all --overwriteSwitch to production (with warning)
envx copy -e production --all --overwrite
`$3
1. Clone repository and set up environment:
`bash
git clone
cd For development
envx copy -e developmentFor production deployment
envx copy -e production
`2. Make changes and re-encrypt:
`bash
Edit .env.production directly or copy from .env after changes
cp .env .env.production # if you made changes to .env
envx encrypt -e production
git add .env.production.gpg
git commit -m "Update production configuration"
`$3
From project root, manage all services at once:
`bash
Copy production environment to all services
envx copy -e production --allCopy staging environment to all services
envx copy -e staging --all --overwritePerfect for deployment scripts
#!/bin/bash
envx copy -e production --all --overwrite
docker-compose up -d
`$3
Process all environments at once:
`bash
Encrypt all environment files
envx encrypt --allDecrypt all environment files
envx decrypt --allDecrypt all with overwrite protection disabled
envx decrypt --all --overwrite
`Benefits of using
--all:- Efficiency: Process multiple environments in one command
- Consistency: Same passphrase/secret handling across all environments
- Automation: Perfect for CI/CD pipelines and scripts
- Safety: Each environment is processed independently - failures in one don't stop others
- Reporting: Comprehensive summary showing results for each environment
- Filtering: Automatically skips non-secret environments (example, sample, template)
Key Features of
--all Flag:- Sequential Processing: Environments are processed one by one to avoid resource conflicts
- Independent Operations: Failure in one environment doesn't stop processing of others
- Smart Passphrase Resolution: Uses provided passphrase, environment-specific secrets, or prompts as needed
- Comprehensive Reporting: Shows detailed results for each environment plus overall summary
- Safety Checks: Validates compatibility with other flags (incompatible with
--environment and --interactive)
- Flexible Configuration: Works with all existing options like --passphrase, --secret, --cwd, and --overwrite$3
Activate environments for your application:
`bash
Activate development environment for local work
envx copy -e developmentActivate staging for testing
envx copy -e staging --overwriteActivate production for deployment
envx copy -e production --overwrite
`Use cases for
envx copy:- Deployment: Copy environment configuration to
.env for application use
- Environment Switching: Quickly switch between different configurations
- Local Development: Use production/staging config locally for debugging
- Docker/Containers: Set up environment in containerized deployments
- CI/CD: Activate specific environments during pipeline stages
- Multi-Service: Manage environment files across multiple services from project root
- Batch Operations: Copy same environment to all services with one command$3
Preview encrypt/decrypt operations before executing them:
`bash
See what files would be encrypted
envx encrypt -e production --dry-runPreview batch encryption
envx encrypt --all -p "your-passphrase" --dry-runPreview decryption
envx decrypt -e production --dry-run
`Dry run mode shows:
- Which files would be processed
- The passphrase source (provided,
.envrc, or interactive)
- Total file countNo files are created, modified, or deleted during a dry run.
Security Best Practices
$3
- Always encrypt production and staging environment files
- Commit encrypted
.gpg files to version control
- Add .envrc and .envxrc to your .gitignore
- Use strong, unique secrets for each environment
- Regularly rotate encryption secrets
- Use envx status to check your security posture
- Use --dry-run to preview operations before executing$3
- Never commit unencrypted
.env.* files (except templates)
- Don't commit .envrc or .envxrc files to version control
- Don't use weak or predictable passphrases
- Don't share secrets through insecure channels
- Don't leave decrypted files in production environments$3
`gitignore
Environment files
.env.*
!.env.example
!.env.template
!*.gpgEnvX secrets and config
.envrc
.envxrc
`Integration with Direnv
EnvX works great with direnv for automatic environment loading:
1. Install direnv:
`bash
macOS
brew install direnvUbuntu/Debian
sudo apt install direnv
`2. Add to your shell profile:
`bash
For bash
echo 'eval "$(direnv hook bash)"' >> ~/.bashrcFor zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
`3. Allow direnv in your project:
`bash
direnv allow
`Now your secrets will be automatically loaded when you enter the project directory!
Troubleshooting
$3
Problem:
gpg: command not found`bash
Install GPG (see Prerequisites section)
`Problem:
gpg: decryption failed: Bad session key`bash
Wrong passphrase - try again or check your .envrc file
envx decrypt -e production
`Problem:
gpg: can't connect to the agent`bash
Restart GPG agent
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
`$3
Problem:
EACCES: permission denied`bash
Check file permissions
ls -la .env.*
chmod 644 .env.*
`$3
Problem:
Template file not found`bash
Check if template exists
ls -la .env.example
Or create without template
envx create -e development
`API Reference
$3
EnvX respects the following environment variables:
-
ENVX_DEFAULT_CWD - Default working directory
- ENVX_GPG_BINARY - Custom GPG binary path
- NODE_ENV - Affects error reporting verbosity$3
| Code | Constant | Description |
| ---- | ---------------- | -------------------------------- |
|
0 | SUCCESS | Operation completed successfully |
| 1 | GENERAL_ERROR | General error |
| 2 | INVALID_ARGS | Invalid arguments provided |
| 3 | FILE_ERROR | File operation failed |
| 4 | GPG_ERROR | GPG operation failed |
| 5 | USER_CANCELLED | Operation cancelled by user |Testing
EnvX includes a comprehensive test suite covering core functionality, configuration management, and real-world CLI usage scenarios.
$3
`bash
Run all tests
npm testRun core functionality tests
npm run test:coreRun integration tests
npm run test:integrationRun tests with coverage
npm run test:coverageRun tests in watch mode (for development)
npm run test:watch
`$3
The test suite prioritizes essential functionality over comprehensive coverage:
- Core business logic - Command validation, file utilities, path manipulation
- Configuration management -
.envxrc read/write/merge, ignore patterns, defaults
- Real CLI scenarios - Actual command execution in various environments
- Critical workflows - User-facing functionality that must work reliably$3
Current Status: 181 tests passing across 7 test suites
- Core Tests: 165 tests covering essential functionality
- Schema validation: 25 tests (command input validation)
- File utilities: 39 tests (path manipulation, secret generation, gitignore)
- Command logic: 25 tests (workflow patterns and decision logic)
- All-flag functionality: 15 tests (batch operations, error handling)
- EnvxrcConfig infrastructure: 23 tests (read/write/merge, ignore patterns, filtering)
- Config command: 7 tests (show, add, remove, reset operations)
- Copy command: 31 tests (single/multi-directory, encrypted/unencrypted)
- Integration Tests: 16 tests covering real CLI usage
- Help/version commands
- Create command functionality
- Init command validation
- Config subcommand (show, ignore, reset)
- Dry run flag (encrypt/decrypt)
- Copy
--all flag
- Environment filtering (list, status)
- Error handling scenarios
- Environment validation$3
`
__tests__/
āāā core/ # Essential functionality tests
ā āāā schemas.test.ts # Input validation for all commands
ā āāā file.test.ts # File utilities, path manipulation, gitignore
ā āāā commands.test.ts # Command workflow logic patterns
ā āāā all-flag.test.ts # Batch operations and --all flag functionality
ā āāā envxrc.test.ts # .envxrc config read/write/merge/filtering
ā āāā config.test.ts # Config command operations
āāā integration/ # End-to-end CLI tests
āāā cli.test.ts # Real CLI execution scenarios
`For detailed testing information, see TESTING.md.
Development
$3
`bash
git clone https://github.com/rahulretnan/envx-cli
cd envx-cli
npm install
npm run build
npm link
`$3
`
src/
āāā index.ts # Entry point, CLI framework, inline commands
āāā commands/ # Command implementations
ā āāā config.ts # envx config subcommand
ā āāā copy.ts # envx copy
ā āāā create.ts # envx create
ā āāā decrypt.ts # envx decrypt
ā āāā encrypt.ts # envx encrypt
ā āāā interactive.ts # envx interactive
āāā schemas/
ā āāā index.ts # Zod validation schemas
āāā types/
ā āāā index.ts # TypeScript interfaces and enums
āāā utils/
āāā exec.ts # GPG operations, CLI output (ExecUtils, CliUtils)
āāā file.ts # File discovery, .envrc/.envxrc, gitignore (FileUtils)
āāā interactive.ts # User prompts via inquirer (InteractiveUtils)
`Key patterns:
- Each command file exports
createXxxCommand() (Commander command) and executeXxx() (core logic)
- All utility classes use static methods, no instances
- Zod schemas validate all command inputs; --all dynamically alters schema requirements
- Configuration resolution: --passphrase flag > .envrc file > interactive prompt
- Working directory: --cwd flag > process.cwd()$3
`bash
Start development mode
npm run devRun tests in watch mode
npm run test:watchBuild and test
npm run build && npm testLint and format
npm run lint:fix && npm run format
`$3
1. Fork the repository
2. Create a feature branch:
git checkout -b feature-name
3. Make your changes and add tests
4. Run tests: npm test
5. Ensure test coverage remains high: npm run test:coverage`#### Test Requirements
- New CLI commands must include integration tests
- Core utility functions must include unit tests
- Focus on user-facing functionality over implementation details
- Keep tests simple and maintainable
- Ensure tests verify real CLI behavior
See CHANGELOG.md for detailed release notes.
MIT Ā© rahulretnan
- Issues
- Discussions
- Email: hi@rahulretnan.me
---
Made with ā¤ļø by developers, for developers.
_Remember: Security is not a feature, it's a requirement. EnvX helps you maintain security without sacrificing developer experience._