`bash
envx config exclude remove build
`

#### envx config reset

Reset 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

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

Or edit .envxrc directly as JSON.

$3

EnvX follows the convention: _SECRET

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

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-kit

Customizing exclusions:

`bash


View current exclusions

`
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

`bash
envx interactive
`

4. Encrypt production secrets:

`bash
envx encrypt -e production
`

5. Copy environment for application use:

`bash


For development

`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

`bash


Copy production environment to ALL services at once

`bash


Copy production environment locally (be careful!)

`bash


Use development environment across all services

`bash
git clone
cd

For development

`bash


Edit .env.production directly or copy from .env after changes

`bash


Copy production environment to all services

`bash


Encrypt all environment files

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

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

- Which files would be processed
- The passphrase source (provided, .envrc, or interactive)
- Total file count

No 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

`bash


macOS

`bash


For bash

`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

Problem: gpg: can't connect to the agent

`bash


Restart GPG agent

Problem: EACCES: permission denied

`bash


Check file permissions

Problem: Template file not found

`bash


Check if template exists

- 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

- 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

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`
6. Submit a pull request

#### 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

Changelog

See CHANGELOG.md for detailed release notes.

License

MIT © rahulretnan

Support

- 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._