Documentation

Everything you need to get started with Envilder.

What is Envilder?

Envilder is a model-driven configuration resolution system. You define a JSON mapping between variable names and cloud secret paths, and Envilder resolves them consistently: via the CLI for local dev, the GitHub Action for CI/CD, or runtime SDKs for application startup. It works with AWS SSM Parameter Store and Azure Key Vault.

⚠️

Without Envilder, teams fragment secret management across tools and stages. Local dev uses .env files, CI/CD reads from vault integrations, production has its own method. This leads to configuration drift, leaked credentials, and slow onboarding.

✅

With Envilder, one mapping model is the single source of truth. Secrets are resolved from your cloud vault on demand: same contract, same behavior, whether you run the CLI locally, the GitHub Action in CI, or an SDK at app startup.

Requirements

Node.js v20+ – Download
AWS CLI (for AWS SSM) – Install guide
Azure CLI (for Azure Key Vault) – Install guide

Installation

pnpm

pnpm add -g envilder

npm

npm install -g envilder

npx

npx envilder --help

Cloud credentials

AWS (default)

Envilder uses your AWS CLI credentials. Set up the default profile:

aws configure

Or use a named profile:

aws configure --profile dev-account

# Then pass it to envilder
envilder --map=envilder.json --envfile=.env --profile=dev-account

Azure Key Vault

Envilder uses Azure Default Credentials. Log in with:

az login

Provide the vault URL via $config in your map file or the --vault-url flag.

IAM permissions

AWS

Your IAM user or role needs:

Operation	Permission
Pull	`ssm:GetParameter`
Push	`ssm:PutParameter`

Example IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["ssm:GetParameter", "ssm:PutParameter"],
    "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/myapp/*"
  }]
}

Azure

Operation	Permission
Pull	Get
Push	Set

Recommended: assign Key Vault Secrets Officer via RBAC:

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee {YOUR_OBJECT_ID} \
  --scope /subscriptions/{SUB}/resourceGroups/{RG}/providers/Microsoft.KeyVault/vaults/{VAULT}

For pull-only access, Key Vault Secrets User is sufficient.

Mapping file

The mapping file (envilder.json) is the core of Envilder. It's a JSON file that maps environment variable names (keys) to secret paths (values) in your cloud provider.

📄

Structure: Each key becomes an env var name in your .env file. Each value is the path where the secret lives in your cloud provider.

Basic format (AWS SSM, default)

When no $config section is present, Envilder defaults to AWS SSM Parameter Store. Values must be valid SSM parameter paths (typically starting with /):

envilder.json json

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

This generates:

.env dotenv

API_KEY={value from /myapp/prod/api-key}
DB_PASSWORD={value from /myapp/prod/db-password}
SECRET_TOKEN={value from /myapp/prod/secret-token}

The $config section

Add a $config key to your mapping file to declare which cloud provider to use and its settings. Envilder reads $config for configuration, and treats all other keys as secret mappings.

$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)

AWS SSM with profile

To use a specific AWS CLI profile (useful for multi-account setups), add profile to $config:

envilder.json json

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

This tells Envilder to use the prod-account profile from your ~/.aws/credentials file instead of the default profile.

Azure Key Vault

For Azure Key Vault, set provider to "azure" and provide the vaultUrl:

envilder.json json

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

⚠️

Azure naming convention: 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).

Key differences by provider

	AWS SSM	Azure Key Vault
Secret path format	Parameter paths with slashes `/myapp/prod/api-key`	Hyphenated names `myapp-prod-api-key`
Required $config	None (AWS is the default)	`provider + vaultUrl`
Optional $config	`profile`	—
Authentication	AWS CLI credentials	Azure Default Credentials

Multiple environments

A common pattern is having one mapping file per environment. The structure is the same, only the secret paths change:

config/dev/envilder.json json

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

config/prod/envilder.json json

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

Then pull the right one:

# Development
envilder --map=config/dev/envilder.json --envfile=.env.dev

# Production
envilder --map=config/prod/envilder.json --envfile=.env.prod

Overriding $config with CLI flags

CLI flags always take priority over $config values. This lets you set defaults in the file and override per invocation:

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

# Overrides provider and vault URL, ignoring $config
envilder --provider=azure \
  --vault-url=https://other-vault.vault.azure.net \
  --map=envilder.json --envfile=.env

# Overrides just the AWS profile
envilder --map=envilder.json --envfile=.env --profile=staging-account

Priority order: CLI flags / GHA inputs → $config in map file → defaults (AWS).

Pull command

Download secrets from your cloud provider and generate a local .env file.

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

Options

Option	Description
`--map`	Path to JSON mapping file
`--envfile`	Path to write .env
`--provider`	aws (default) or azure
`--vault-url`	Azure Key Vault URL
`--profile`	AWS CLI profile to use

Examples

# Default (AWS SSM)
envilder --map=envilder.json --envfile=.env

# With AWS profile
envilder --map=envilder.json --envfile=.env --profile=prod-account

# Azure via $config in map file
envilder --map=envilder.azure.json --envfile=.env

# Azure via CLI flags
envilder --provider=azure \
  --vault-url=https://my-vault.vault.azure.net \
  --map=envilder.json --envfile=.env

Output

.env dotenv

# Generated by Envilder
API_KEY=abc123
DB_PASSWORD=secret456

Push command

Upload environment variables from a local .env file to your cloud provider using a mapping file.

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

Options

Option	Description
`--push`	Enable push mode (required)
`--envfile`	Path to your local .env file
`--map`	Path to parameter mapping JSON
`--provider`	aws (default) or azure
`--vault-url`	Azure Key Vault URL
`--profile`	AWS CLI profile (AWS only)

Examples

# Push to AWS SSM
envilder --push --envfile=.env --map=envilder.json

# With AWS profile
envilder --push --envfile=.env.prod --map=envilder.json --profile=prod-account

# Azure via $config in map file
envilder --push --envfile=.env --map=envilder.azure.json

# Azure via CLI flags
envilder --push --provider=azure \
  --vault-url=https://my-vault.vault.azure.net \
  --envfile=.env --map=envilder.json

Push single variable

Push a single environment variable directly without any files.

envilder --push --key=API_KEY --value={SECRET} --secret-path=/myapp/api/key

Options

Option	Description
`--push`	Enable push mode (required)
`--key`	Environment variable name
`--value`	Value to store
`--secret-path`	Full secret path in your cloud provider
`--provider`	aws (default) or azure
`--vault-url`	Azure Key Vault URL
`--profile`	AWS CLI profile (AWS only)

.NET SDK

Load secrets directly into your .NET application at startup. One-liner facade, fluent builder, IConfiguration integration, or full programmatic control.

📦 NuGet v0.4.0

Install

dotnet add package Envilder

One-liner: resolve + inject

Resolve secrets from the map file and inject into Environment in a single call:

using Envilder;

// Resolve secrets and inject into Environment
Env.Load("envilder.json");

var dbPassword = Environment.GetEnvironmentVariable("DB_PASSWORD");

Resolve without injecting

Get secrets as a dictionary without modifying the environment:

using Envilder;

var secrets = Env.ResolveFile("envilder.json");
var dbPassword = secrets["DB_PASSWORD"];

Fluent builder with overrides

Override provider settings programmatically using the fluent API:

using Envilder;

var secrets = Env.FromMapFile("envilder.json")
    .WithProvider(SecretProviderType.Azure)
    .WithVaultUrl("https://my-vault.vault.azure.net")
    .Resolve();

// Or inject directly
Env.FromMapFile("envilder.json")
    .WithProfile("staging")
    .Inject();

Environment-based loading

Route secret loading based on your current environment. Each environment maps to its own secrets file:

using Envilder;

var env = Environment.GetEnvironmentVariable("APP_ENV") ?? "development";

Env.Load(env, new Dictionary<string, string?>
{
    ["production"] = "prod-secrets.json",
    ["development"] = "dev-secrets.json",
    ["test"] = null,  // no secrets loaded
});

Secret validation

Opt-in validation ensures all resolved secrets have non-empty values:

using Envilder;

var secrets = Env.ResolveFile("envilder.json");
secrets.ValidateSecrets(); // throws SecretValidationException if any value is empty

Via IConfiguration (ASP.NET)

Add Envilder as a configuration source in your ASP.NET application:

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddEnvilder("envilder.json");
var app = builder.Build();

Advanced: full programmatic control

Parse the map file, resolve secrets, and inject them into environment variables:

using Envilder;

var secrets = await Env.ResolveFileAsync("envilder.json");
EnvilderClient.InjectIntoEnvironment(secrets);

Full documentation →

Python SDK

Load secrets directly into your Python application at startup. One-liner setup or fine-grained control with the fluent builder.

📦 PyPI v0.4.0

Install

uv add envilder
# or
pip install envilder

Quick start: one-liner

Load secrets from a map file and inject them into the environment:

from envilder import Envilder

Envilder.load('envilder.json')

Environment-based loading

Recommended for multi-environment apps. Map each environment to its own secrets file:

from envilder import Envilder
import os

env = os.getenv('APP_ENV', 'development')

Envilder.load(env, {
    'production': 'prod-secrets.json',
    'development': 'dev-secrets.json',
    'test': None,
})

Resolve without injecting

Get secrets as a dictionary without modifying the environment:

secrets = Envilder.resolve_file('envilder.json')

Fluent builder with overrides

Override provider settings programmatically using the fluent API:

from envilder import Envilder, SecretProviderType

secrets = (
    Envilder.from_map_file('envilder.json')
    .with_provider(SecretProviderType.AZURE)
    .with_vault_url('https://my-vault.vault.azure.net')
    .resolve()
)

Secret validation

Opt-in validation ensures all resolved secrets have non-empty values:

from envilder import Envilder, validate_secrets

secrets = Envilder.resolve_file('envilder.json')
validate_secrets(secrets)  # raises SecretValidationError if any value is empty

Full documentation →

Node.js SDK

Load secrets directly into your Node.js application at startup. Async-first API with one-liner facade or fluent builder for full control.

📦 npm v0.2.0

Install

npm install @envilder/sdk

Quick start: one-liner

Load secrets from a map file and inject them into process.env:

import { Envilder } from '@envilder/sdk';

// Resolve secrets and inject into process.env
await Envilder.load('envilder.json');

const dbPassword = process.env.DB_PASSWORD;

Resolve without injecting

Get secrets as a Map without modifying the environment:

import { Envilder } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
const dbPassword = secrets.get('DB_PASSWORD');

Fluent builder with overrides

Override provider settings programmatically using the fluent API:

import { Envilder, SecretProviderType } from '@envilder/sdk';

const secrets = await Envilder.fromMapFile('envilder.json')
  .withProvider(SecretProviderType.Azure)
  .withVaultUrl('https://my-vault.vault.azure.net')
  .resolve();

// Or inject directly
await Envilder.fromMapFile('envilder.json')
  .withProfile('staging')
  .inject();

Environment-based loading

Recommended for multi-environment apps. Map each environment to its own secrets file:

import { Envilder } from '@envilder/sdk';

const env = process.env.APP_ENV ?? 'development';

await Envilder.load(env, {
  production: 'prod-secrets.json',
  development: 'dev-secrets.json',
  test: null,  // no secrets loaded
});

Secret validation

Opt-in validation ensures all resolved secrets have non-empty values:

import { Envilder, validateSecrets } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
validateSecrets(secrets); // throws SecretValidationError if any value is empty

Full documentation →

GitHub Action setup

The Envilder GitHub Action pulls secrets from AWS SSM or Azure Key Vault into .env files during your CI/CD workflow. No build step needed. The action is pre-built and ready to use from GitHub Marketplace.

Prerequisites

AWS: Configure credentials with aws-actions/configure-aws-credentials
Azure: Configure credentials with azure/login
An envilder.json committed to your repository

The GitHub Action only supports pull mode (no push).

Basic workflow example

.github/workflows/deploy.yml yaml

name: Deploy Application

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v6
        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
        with:
          map-file: config/envilder.json
          env-file: .env

      - uses: actions/setup-node@v6
        with:
          node-version: "20.x"

      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm deploy

Multi-environment workflow

.github/workflows/deploy-env.yml yaml

name: Deploy to Environment

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options: [dev, staging, production]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-24.04
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v5

      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-east-1

      - name: Pull ${{ inputs.environment }} secrets
        uses: macalbert/envilder/github-action@v0
        with:
          map-file: config/${{ inputs.environment }}/envilder.json
          env-file: .env

      - uses: actions/setup-node@v6
        with:
          node-version: "20.x"
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm deploy

Azure Key Vault workflow

.github/workflows/deploy-azure.yml yaml

name: Deploy with Azure Key Vault

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5

      - 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
        with:
          map-file: config/envilder.json
          env-file: .env
          provider: azure
          vault-url: https://my-vault.vault.azure.net

      - uses: actions/setup-node@v6
        with:
          node-version: "20.x"
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm deploy

Action inputs & outputs

Inputs

Input	Required	Default	Description
`map-file`	Yes	—	Path to JSON mapping file
`env-file`	Yes	—	Path to the .env file to generate
`provider`	No	`aws`	aws or azure
`vault-url`	No	—	Azure Key Vault URL

Outputs

Output	Description
`env-file-path`	Path to the generated .env file

Configuration priority

When multiple configuration sources are present, Envilder resolves them in this order (highest wins):

1. CLI flags / GHA inputs

2. $config in map file

3. Defaults (AWS)

This means --provider=azure on the CLI will override "provider": "aws" in $config.

Azure Key Vault setup

Check which access model your vault uses:

az keyvault show --name {VAULT_NAME} \
  --query properties.enableRbacAuthorization

true → true → Azure RBAC (recommended)
false / null → false / null → Vault Access Policy (classic)

Option A: Azure RBAC (recommended)

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee {YOUR_OBJECT_ID} \
  --scope /subscriptions/{SUB}/resourceGroups/{RG}/providers/Microsoft.KeyVault/vaults/{VAULT}

Option B: Vault Access Policy

az keyvault set-policy \
  --name {VAULT_NAME} \
  --object-id {YOUR_OBJECT_ID} \
  --secret-permissions get set list

For pull-only access, get list is enough. Add set for push.