Map file

Define environment variable mappings and provider settings in envilder.json.

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

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

This generates:

.envdotenv

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

{
  "$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.jsonjson

{
  "$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.jsonjson

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

config/prod/envilder.jsonjson

{
  "$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).

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.