🗝️ Envilder ☁️

Automate .env and secret management with Envilder
Streamline your environment setup with AWS SSM Parameter Store or Azure Key Vault

Why centralize environment variables?

Envilder is a CLI tool for .env automation, cloud secrets management, and secure environment variable sync. Generating and maintaining consistent .env files is a real pain point for any development team. From outdated secrets to insecure practices, the risks are tangible. Envilder eliminates these pitfalls by centralizing and automating secret management across real-world environments (dev, test, production) in a simple, secure, and efficient way. Use Envilder to automate .env files, sync secrets with AWS SSM Parameter Store or Azure Key Vault, and streamline onboarding and CI/CD workflows.

---

❗ What Envilder solves

• Desync between environments (dev, prod)
• Secrets not properly propagated across team members
• CI/CD pipeline failures due to outdated or missing .env files
• Slow and manual onboarding processes
• Security risks from sharing secrets via Slack, email, or other channels
• Insecure .env practices and manual secret sharing

✅ How Envilder makes life easier

• 🛡️ Centralizes secrets in AWS SSM Parameter Store or Azure Key Vault
• ☁️ Multi-provider support — choose aws or azure with the --provider flag
• ⚙️ Generates .env files automatically for every environment
• 🔄 Applies changes idempotently and instantly
• 🔐 Improves security: no need to share secrets manually; everything is managed via your cloud provider
• 👥 Simplifies onboarding and internal rotations
• 🚀 Enables cloud-native, infrastructure-as-code secret management
• 🤖 Perfect for DevOps, CI/CD, and team sync

---

📚 Table of Contents

• 🗝️ Envilder ☁️
  • Why centralize environment variables?
  • ❗ What Envilder solves
  • ✅ How Envilder makes life easier
  • 📚 Table of Contents
  • ⚙️ Features
    • 🧱 Feature Status
  • 💾 Installation
    • 🤖 GitHub Action
  • 🚀 Quick Start
    • 🎥 Video Demonstration
    • 🏁 Get Started (3 steps)
      • AWS SSM (default)
      • Azure Key Vault
    • 📚 Quick Links
  • 🗺️ Mapping File Format
    • Basic Format (AWS SSM — default)
    • With $config (explicit provider)
    • $config Options
    • Configuration Priority
  • 🛠️ How it works
  • Frequently Asked Questions (FAQ)
  • 🔍 Envilder vs. Alternatives
    • Secrets sync tools (direct alternatives)
    • Runtime & credential tools (not direct alternatives)
    • When to use what
    • Why choose Envilder?
    • Where Envilder fits best
  • 🏁 Roadmap
  • 🤝 Contributing
  • 📜 License

---

⚙️ Features

• 🔒 Strict access control — IAM policies (AWS) or RBAC (Azure) define access to secrets across stages (dev, staging, prod)
• 📊 Auditable — All reads/writes are logged in AWS CloudTrail or Azure Monitor
• 🧩 Single source of truth — No more Notion, emails or copy/paste of envs
• 🔁 Idempotent sync — Only what's in your map gets updated. Nothing else is touched
• 🧱 Zero infrastructure — Fully based on native cloud services. No Lambdas, no servers, no fuss

🧱 Feature Status

• 🤖 GitHub Action — Integrate directly in CI/CD workflows
• 📤 Push & Pull — Bidirectional sync between local .env and your cloud provider
• ☁️ Multi-provider — AWS SSM Parameter Store and Azure Key Vault
• 🎯 AWS Profile support — Use --profile flag for multi-account setups

---

💾 Installation

🛠 Requirements:

• Node.js v20+ (cloud-native compatible)
• AWS provider: AWS CLI installed and configured; IAM user/role with ssm:GetParameter, ssm:PutParameter
• Azure provider: Azure CLI installed; vault URL configured via $config.vaultUrl in your map file or --vault-url flag

pnpm add -g envilder

Or use your preferred package manager:

npm install -g envilder

💡 Want to try without installing? Run npx envilder --help to explore the CLI instantly.

💡 New to AWS SSM? AWS Systems Manager Parameter Store provides secure storage for configuration data and secrets:

• AWS SSM Parameter Store Overview
• Setting up AWS CLI credentials
• IAM permissions for SSM

💡 New to Azure Key Vault? Azure Key Vault safeguards cryptographic keys and secrets used by cloud apps:

• Azure Key Vault Overview
• Setting up Azure CLI
• Key Vault access policies

🤖 GitHub Action

Use Envilder directly in your CI/CD workflows with our official GitHub Action:

AWS SSM (default):

- name: Configure AWS Credentials
  uses: aws-actions/configure-aws-credentials@v5
  with:
    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    aws-region: us-east-1

- name: Pull secrets from AWS SSM
  uses: macalbert/envilder/github-action@v0.8.0
  with:
    map-file: param-map.json
    env-file: .env

Azure Key Vault:

- name: Azure Login
  uses: azure/login@v2
  with:
    client-id: ${{ secrets.AZURE_CLIENT_ID }}
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

- name: Pull secrets from Azure Key Vault
  uses: macalbert/envilder/github-action@v0.8.0
  with:
    map-file: param-map.json
    env-file: .env
    provider: azure
    vault-url: ${{ secrets.AZURE_KEY_VAULT_URL }}

📖 View full GitHub Action documentation

---

🚀 Quick Start

🎥 Video Demonstration

Watch how easy it is to automate your .env management in less than 1 minute:

🏁 Get Started (3 steps)

After configuring your cloud provider credentials, you can begin managing your secrets.

AWS SSM (default)

1. Create a mapping file:

   {
     "DB_PASSWORD": "/my-app/db/password"
   }

2. Push a secret to AWS SSM:

   envilder --push --key=DB_PASSWORD --value=12345 --secret-path=/my-app/db/password

3. Generate your .env file from AWS SSM:

   envilder --map=param-map.json --envfile=.env

Azure Key Vault

1. Add $config to your mapping file:

   {
     "$config": {
       "provider": "azure",
       "vaultUrl": "https://my-vault.vault.azure.net"
     },
     "DB_PASSWORD": "my-app-db-password"
   }

2. Pull secrets from Azure Key Vault:

   envilder --map=param-map.json --envfile=.env

   Or use CLI flags to override:

   envilder --provider=azure --vault-url=https://my-vault.vault.azure.net --map=param-map.json --envfile=.env

Your secrets are now managed and versioned from your cloud provider. Add .env to your .gitignore for security. Envilder is designed for automation, onboarding, and secure cloud-native workflows.

📚 Quick Links

• 📖 Full Documentation — Visit envilder.com for the complete guide
• Requirements & Installation
• Push Command Guide
• Pull Command Guide

---

🗺️ Mapping File Format

The mapping file (param-map.json) is the core of Envilder. It maps environment variable names to secret paths in your cloud provider. You can optionally include a $config section to declare which provider and settings to use.

Basic Format (AWS SSM — default)

When no $config is present, Envilder defaults to AWS SSM Parameter Store:

{
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password",
  "SECRET_TOKEN": "/myapp/prod/secret-token"
}

Values are SSM parameter paths (e.g., /myapp/prod/api-key).

With $config (explicit provider)

Add a $config key to declare the provider and its settings. Envilder reads $config for configuration and uses all other keys as secret mappings:

AWS SSM with profile:

{
  "$config": {
    "provider": "aws",
    "profile": "prod-account"
  },
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password"
}

Azure Key Vault:

{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "API_KEY": "myapp-prod-api-key",
  "DB_PASSWORD": "myapp-prod-db-password"
}

Azure naming: Key Vault secret names only allow alphanumeric characters and hyphens. Envilder automatically normalizes names — slashes and underscores become hyphens (e.g., /myapp/db/password → myapp-db-password).

$config Options

Key	Type	Default	Description
provider	"aws" | "azure"	"aws"	Cloud provider to use
vaultUrl	string	—	Azure Key Vault URL (required when provider is "azure")
profile	string	—	AWS CLI profile for multi-account setups (AWS only)

Configuration Priority

CLI flags and GitHub Action inputs always override $config values:

CLI flags / GHA inputs  >  $config in map file  >  defaults (AWS)

This means you can set a default provider in $config and override it per invocation:

# Uses $config from the map file
envilder --map=param-map.json --envfile=.env

# Overrides provider and vault URL from the map file
envilder --provider=azure --vault-url=https://other-vault.vault.azure.net --map=param-map.json --envfile=.env

---

🛠️ How it works

graph LR
    A["Mapping File (param-map.json)"] --> B[Envilder]:::core
    C["Environment File (.env or --key)"] --> B
    D["Cloud Credentials (AWS or Azure)"]:::cloud --> B
    E["AWS SSM / Azure Key Vault"]:::cloud --> B
    B --> F["Pull/Push Secrets"]

    classDef cloud fill:#ffcc66,color:#000000,stroke:#333,stroke-width:1.5px;
    classDef core fill:#1f3b57,color:#fff,stroke:#ccc,stroke-width:2px;

Loading

1. Define mappings in a JSON file: {"DB_PASSWORD": "/myapp/db/password"}
2. Pull secrets into a .env file: envilder --map=param-map.json --envfile=.env
3. Push local values back: envilder --push --map=param-map.json --envfile=.env
4. Envilder syncs secrets securely with AWS SSM or Azure Key Vault using your cloud credentials
5. Use --provider=azure to switch from the default AWS provider
6. Result: your secrets are always up-to-date, secure, and ready for any environment

---

Frequently Asked Questions (FAQ)

Q: What is Envilder?
A: Envilder is a CLI tool for automating .env and secret management using AWS SSM Parameter Store or Azure Key Vault.

Q: Which cloud providers are supported?
A: AWS SSM Parameter Store (default) and Azure Key Vault. Use --provider=azure to switch providers.

Q: How does Envilder improve security?
A: Secrets are never stored in code or shared via chat/email. All secrets are managed and synced securely via your cloud provider.

Q: Can I use Envilder in CI/CD pipelines?
A: Yes! Use the official Envilder GitHub Action to pull secrets directly in your workflows — no extra setup needed.

Q: Does Envilder support multiple AWS profiles?
A: Yes, you can use the --profile flag to select different AWS credentials.

Q: How do I configure Azure Key Vault?
A: Add a $config section to your map file with "provider": "azure" and "vaultUrl": "https://my-vault.vault.azure.net", or use --provider=azure --vault-url=https://my-vault.vault.azure.net CLI flags. Authentication uses Azure Default Credentials (Azure CLI, managed identity, etc.).

Q: What environments does Envilder support?
A: Any environment supported by your cloud provider—dev, test, staging, production, etc.

Q: Is Envilder open source?
A: Yes, licensed under MIT.

---

🔍 Envilder vs. Alternatives

Envilder is not a secrets manager. It is a deterministic projection layer from cloud secret stores into .env files. It does not store secrets, does not require a backend, and integrates cleanly into CI/CD pipelines.

To make a fair comparison, it's important to separate tools by what they actually do:

Secrets sync tools (direct alternatives)

These tools manage secrets as data and project them into .env or runtime:

Feature	Envilder	dotenv-vault	infisical
Source of truth	External (SSM / Key Vault)	dotenv vault (SaaS)	Infisical backend
Sync direction	Bidirectional	Pull only	Bidirectional
Declarative mapping	✅ JSON mapping	❌	❌
Multi-provider (AWS + Azure)	✅	❌	⚠️ (primarily its own backend)
Local .env generation	✅	✅	✅
CI/CD integration	✅ Native GitHub Action	Manual	✅ Native
Requires SaaS	❌	✅	Optional
Self-hosted	N/A (no server needed)	❌	✅
Complexity	Low	Low	Medium
Vendor lock-in	Low	High	Medium
Open source	✅ MIT	Partial	✅

Runtime & credential tools (not direct alternatives)

These tools serve different purposes and are better seen as complements, not competitors:

Tool	Purpose	Manages app secrets?	Works with .env?
chamber	Injects SSM params at runtime (exec with env)	❌	❌
aws-vault	Safely assumes AWS IAM roles / STS credentials	❌	❌

When to use what

• Need a full vault with its own backend? → Infisical
• Need SaaS simplicity for .env sync? → dotenv-vault
• Need a projection layer from existing cloud stores? → Envilder

Why choose Envilder?

If you already use AWS SSM or Azure Key Vault and want a lightweight, zero-infrastructure CLI that generates .env files from a declarative JSON mapping — without a SaaS dependency or extra servers — Envilder is the simplest path.

Envilder also brings unique strengths in determinism and testability:

• Versioned mappings — your param-map.json lives in source control, making secret projections reproducible across environments
• Mockable architecture — hexagonal design with port interfaces makes offline testing and CI validation straightforward
• Audit trail — all reads/writes are logged by your cloud provider (AWS CloudTrail / Azure Monitor), not by a third-party SaaS

Where Envilder fits best

Envilder generates .env files on disk. This is ideal for:

• Local development — onboard new team members with a single command
• CI/CD pipelines — inject secrets at build time without hardcoding them
• SSG/SSR builds — frameworks like Next.js, Nuxt, or Astro that read env vars at build time

For production runtime, container orchestrators (ECS, Kubernetes) and platform services (Vercel, Fly.io) can inject secrets directly as environment variables — no .env file needed. In those cases, prefer native secret injection over writing secrets to disk.

Coming soon: An --exec mode is planned to inject secrets directly into a child process without writing to disk (e.g., envilder exec -- node server.js). See the Roadmap.

---

🏁 Roadmap

We're continuously improving Envilder based on community feedback. Upcoming features include:

• ✅ Azure Key Vault support — now available alongside AWS SSM
• � Exec mode — inject secrets into a child process without writing to disk
• 🔍 Check/sync mode for drift detection
• 🌐 Documentation website — dedicated docs site with guides and examples
• 🧠 Auto-discovery for bulk parameter fetching
• 🔌 More backends (HashiCorp Vault, GCP Secret Manager, etc.)

👉 View full roadmap with priorities

---

🤝 Contributing

All help is welcome — PRs, issues, ideas!

• 🔧 Use our Pull Request Template
• 🧪 Add tests where possible
• 💬 Feedback and discussion welcome
• 🏗️ Check our Architecture Documentation
• 🔒 Review our Security Policy

---

📜 License

MIT © Marçal Albert
See LICENSE | CHANGELOG | Security Policy