🗝️ Envilder ☁️

<p align="center"> <img src="https://github.com/user-attachments/assets/8a7188ef-9d8d-45fb-8c37-3af718fb5103" alt="Envilder"> </p> <p align="center"> <b>Automate .env and secret management with Envilder</b><br> <span>Streamline your environment setup with AWS SSM Parameter Store or Azure Key Vault</span> </p>

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
  • 💜 Sponsors
  • 📜 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":