Envilder

A CLI that securely centralizes your environment variables from AWS SSM as a single source of truth

npm version MIT License Coverage Report

## ๐ŸŒŸ Key benefits - **๐Ÿ”’ Strict access control** - AWS IAM policies control who accesses which secrets (dev vs prod) - **๐Ÿ“Š Full audit trail** - All parameter access is logged in CloudTrail for compliance requirements - **๐Ÿงฉ Single source of truth** - No more copying .env files from Notion or emails - SSM is your only source - **๐Ÿ” Idempotent operations** - Overwrites values in your `.env` file *only* for variables defined in your mapping file, using the latest from SSM. Variables not in the mapping file are preserved. Safe for automation. - **โš™๏ธ Environment-aware** - Use templates like `/project/${ENV}/DB_PASSWORD` to dynamically fetch the right secrets - **๐Ÿงฑ No extra infrastructure** - Uses AWS SSM's existing reliability instead of additional secret managers ## โšก Quick start ```bash # Install globally npm install -g envilder # Create a simple mapping file echo '{"DB_PASSWORD": "/my-app/db/password"}' > param-map.json # Generate your .env file envilder --map=param-map.json --envfile=.env ``` ## ๐Ÿค” What problem does Envilder solve?
โŒ Without Envilder โœ… With Envilder
```plaintext - Secrets committed to repos - Manual .env file updates - Inconsistent environments - Password sharing via chat/email - CI/CD secrets management pain ``` ```plaintext - Secrets stored securely in AWS SSM - Automated .env file generation - Consistent environments - No need to share raw credentials - Simple CI/CD integration ```
## ๐Ÿ’ก Why Envilder? - ๐Ÿ” **No more secrets in git** - Store credentials in AWS SSM Parameter Store instead of version control - ๐Ÿค– **Automate everything** - One command to generate your `.env` files across all environments - ๐Ÿ”„ **Always in sync** - Keep your local, dev, and production environments consistent - ๐ŸŽ๏ธ **Fast to set up** - Configure once, then generate `.env` files with a single command - ๐Ÿชถ **Simple but powerful** - Easy interface with support for encrypted parameters and multiple AWS profiles ## ๐ŸŽฏ Perfect for teams Envilder is the tool you need if you: - ๐Ÿ‘ฅ **Work in a development team** - Ensure everyone has the same environment without sharing raw secrets - ๐Ÿ”‘ **Deal with API keys & tokens** - Securely store and retrieve sensitive credentials - โš™๏ธ **Run CI/CD pipelines** - Automatically generate environment files during deployments - โ˜๏ธ **Use AWS already** - Leverage your existing AWS infrastructure more effectively - ๐ŸŒ **Manage multiple environments** - Switch easily between dev, staging, and production ## ๐Ÿ” How it works (simple!) ```mermaid graph LR A[Mapping File] --> B[Envilder] C[AWS Credentials] --> B B --> D[.env File] E[SSM Parameters] --> B ``` 1. ๐Ÿ“– **Define your mapping** - Simple JSON mapping env vars to SSM paths 2. ๐Ÿš€ **Run Envilder** - One command with your mapping file 3. ๐Ÿ”„ **Auto-fetch from AWS** - Retrieves values using your AWS credentials 4. ๐Ÿ’พ **Get your .env file** - Ready to use in your project ## โš™๏ธ Prerequisites You'll need: - โœ… **AWS CLI** - Installed and configured with proper permissions to access SSM Parameter Store - โœ… **Node.js** - Version 20.0.0 or higher (as specified in `package.json`) ### AWS CLI setup 1. Install the AWS CLI by following the [official instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 2. After installation, configure the AWS CLI: ```bash aws configure ``` You'll be prompted to provide: - AWS Access Key ID - AWS Secret Access Key - Default region name (e.g., `us-east-1`) - Default output format (e.g., `json`) Make sure your AWS credentials have the appropriate permissions to access the SSM Parameter Store. ## ๐Ÿ“ฆ Installation ```bash # Using npm npm install -g envilder ``` ## ๐Ÿš€ Usage ```bash envilder --map= --envfile= [--profile=] ``` | Option | Description | |--------|-------------| | `--map` | Path to JSON mapping file (required) | | `--envfile` | Path to output .env file (required) | | `--profile` | AWS CLI profile to use (optional) | ## ๐Ÿ”ง Quick example 1. Create a mapping file `param-map.json`: ```json { "SECRET_TOKEN": "/path/to/ssm/token", "SECRET_KEY": "/path/to/ssm/password" } ``` 2. Generate your `.env` file: ```bash envilder --map=param-map.json --envfile=.env ``` 3. Use a specific AWS profile: ```bash envilder --map=param-map.json --envfile=.env --profile=dev-account ``` ## ๐ŸŒ Working with multiple AWS profiles For multiple AWS accounts or environments, configure different profiles in your AWS credentials file: 1. Edit your AWS credentials file (typically located at `~/.aws/credentials` on Linux/Mac or `%USERPROFILE%\.aws\credentials` on Windows): ```ini [default] aws_access_key_id=YOUR_DEFAULT_ACCESS_KEY aws_secret_access_key=YOUR_DEFAULT_SECRET_KEY [dev-account] aws_access_key_id=YOUR_DEV_ACCESS_KEY aws_secret_access_key=YOUR_DEV_SECRET_KEY [prod-account] aws_access_key_id=YOUR_PROD_ACCESS_KEY aws_secret_access_key=YOUR_PROD_SECRET_KEY ``` 2. Specify which profile to use: ```bash # Development environment envilder --map=param-map.json --envfile=.env.development --profile=dev-account # Production environment envilder --map=param-map.json --envfile=.env.production --profile=prod-account ``` ## ๐Ÿ› ๏ธ Advanced usage: environment-specific parameters Envilder works brilliantly with environment variables for dynamic parameter paths: 1. Set up your SSM parameters with environment-specific paths: ```text /project/dev/DB_PASSWORD /project/stage/DB_PASSWORD /project/prod/DB_PASSWORD ``` 2. Create a template-based mapping file `env-map.json`: ```json { "DB_PASSWORD": "/project/${ENV}/DB_PASSWORD" } ``` 3. Generate environment-specific .env files: ```powershell # Development $env:ENV = "dev" envilder --map=env-map.json --envfile=.env.dev # Staging $env:ENV = "stage" envilder --map=env-map.json --envfile=.env.stage # Production $env:ENV = "prod" envilder --map=env-map.json --envfile=.env.prod --profile=prod-account ``` This approach ensures the right variables are pulled for each environment with minimal configuration. ## ๐Ÿ“‚ Sample `.env` output ```ini SECRET_TOKEN=mockedEmail@example.com SECRET_KEY=mockedPassword ``` ## ๐ŸŽฏ Why use Envilder in practice? Envilder eliminates common problems in development teams: - **๐Ÿ›‘ No more "it works on my machine"** - Everyone uses the exact same environment variables from the same source - **๐Ÿ”„ Always fresh credentials** - Update a secret in SSM and everyone gets it automatically on next run - **๐Ÿ›ก๏ธ Access control built-in** - Developers only see dev secrets, CI/CD systems see what they need - **๐Ÿง  Zero mental overhead** - No need to remember which variables are needed - the mapping defines everything - **๐Ÿšซ No more sharing secrets** - Stop pasting credentials in Slack, email, or Notion documents - **๐Ÿ“‹ Compliance ready** - All accesses are logged in AWS CloudTrail for auditing ## ๐Ÿงช Running tests ```bash npm test ``` Check the current coverage report: [Coverage Report](https://macalbert.github.io/envilder/) ## ๐Ÿ“ License This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details. ## ๐Ÿ™Œ Contributing Contributions are welcome! Feel free to submit issues and pull requests.