Sync Azure Key Vault secrets into a local .env file
What tool can sync Azure Key Vault secrets into a local .env file for development? Envilder, an open-source CLI: list each variable and its Key Vault secret name once in envilder.json, sign in with az login and run envilder. It reads every secret and writes a .env file that parses back to the same values, or with envilder exec it starts your command with the secrets in its environment and writes no file. The secrets stay in your vault: no extra SaaS, and Azure RBAC keeps deciding who can read them.
Why read Key Vault directly
- The secrets stay in your Key Vault. There is no second store to keep in sync and no extra service that holds your values.
- Azure RBAC and your Key Vault diagnostic logs keep working as they do today: Envilder signs in as the developer, so access is granted per person.
- Nobody pastes a .env file into a chat or an email. A new teammate gets a role on the vault and runs one command.
- envilder.json holds only variable names and secret names, so it is safe to commit and the contract is reviewed in a pull request.
Prerequisites
- Node.js 22.12 or later. Run the CLI with npx envilder, or install it with npm install -g envilder.
- An existing Key Vault and its URL, in the form https://<vault-name>.vault.azure.net.
- The Azure CLI, signed in with az login. Envilder authenticates with DefaultAzureCredential from the Azure SDK, which tries several sources in turn (environment variables, workload identity, managed identity, the Azure CLI, Azure PowerShell and the Azure Developer CLI). On a developer machine the signed-in Azure CLI session is the usual one.
- A role on the vault that lets you read secrets, and one that lets you write them if you also push.
az loginPull and exec only read secrets. Push writes them. This is the least you need for each:
| Operation | Azure RBAC role | Access policy permission |
|---|---|---|
| Pull and exec | Key Vault Secrets User | Get |
| Push | Key Vault Secrets Officer | Set |
With Azure RBAC, assign the role on the vault. Give the read role to everyone who runs the app and the write role only to whoever creates secrets:
# Pull and exec: read secrets
az role assignment create \
--role "Key Vault Secrets User" \
--assignee {USER_OBJECT_ID} \
--scope /subscriptions/{SUB}/resourceGroups/{RG}/providers/Microsoft.KeyVault/vaults/{VAULT}
# Push: write secrets
az role assignment create \
--role "Key Vault Secrets Officer" \
--assignee {USER_OBJECT_ID} \
--scope /subscriptions/{SUB}/resourceGroups/{RG}/providers/Microsoft.KeyVault/vaults/{VAULT}Which of the two models your vault uses, and the access policy commands, are covered in the Azure Key Vault provider page. A role assignment can take a few minutes to apply. Azure Key Vault provider setup: access models and roles
How a map file entry becomes a secret name
Envilder applies one rule to every reference in the map file: a leading slash is dropped and each other / becomes a hyphen. Nothing else is changed:
| Reference in envilder.json | Secret read from the vault |
|---|---|
/my-app/dev/db-password | my-app-dev-db-password |
my-app-dev-db-password | my-app-dev-db-password |
/db-password | db-password |
my_app/db-password | my_app-db-password |
Key Vault accepts only letters, digits and hyphens in a secret name, and compares names without case. A reference that Key Vault rejects, for example one with _ or ., fails with the error from Key Vault itself. Two references that resolve to the same name in one run stop with a collision error. The variable name on the left of the entry is free: DB_PASSWORD is fine even though the secret cannot contain an underscore.
Example: from Key Vault secrets to a .env file
We start in a folder with no envilder.json and an empty vault, and create three secrets. Each one is read into one variable. If the project already has an envilder.json for another store, pass --map with a separate file to every push, pull and exec command:
| Secret in Key Vault | Variable in .env |
|---|---|
my-app-dev-db-password | DB_PASSWORD |
my-app-dev-api-token | API_TOKEN |
my-app-dev-database-url | DATABASE_URL |
Push each value once. A single-secret push writes the value to the vault and, in the same step, creates envilder.json or adds the entry to it (CLI 0.16 or later). Each push names the provider and the vault, so the secret goes to Key Vault whatever the map file says. The first one creates envilder.json with them in $config, so pull and exec need no flags:
envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
--key=DB_PASSWORD --value=local-dev-password \
--secret-path=/my-app/dev/db-password
envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
--key=API_TOKEN --value=dev-token-7f3a9c21 \
--secret-path=/my-app/dev/api-token
envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
--key=DATABASE_URL \
--value='postgres://app:p@ss w0rd#1@db.internal:5432/app' \
--secret-path=/my-app/dev/database-urlResult lines of each command (the header lines are left out). Values and paths are masked:
⭐ SECRET PUSHED — DB_PASSWORD=***************ord → ********************ord
✓ Created envilder.json
⭐ SECRET PUSHED — API_TOKEN=***************c21 → ******************ken
✓ Added API_TOKEN to envilder.json
⭐ SECRET PUSHED — DATABASE_URL=********************************************app → *********************url
✓ Added DATABASE_URL to envilder.jsonenvilder.json now maps the three variables. It holds names and secret references only, never values:
{
"$config": {
"provider": "azure",
"vaultUrl": "https://my-vault.vault.azure.net"
},
"DB_PASSWORD": "/my-app/dev/db-password",
"API_TOKEN": "/my-app/dev/api-token",
"DATABASE_URL": "/my-app/dev/database-url"
}If the secrets already exist in the vault, do not push them again: write envilder.json by hand with the same shape, one variable name per secret. If a variable already maps to another reference, push exits with 1 and pushes nothing. Push mode reference: every option and the map file rules
Run envilder with no options. Pull is the default mode: it reads envilder.json and writes .env in the current directory. The vault URL comes from $config, so no flag is needed:
envilder🪙 RESOLVING SECRETS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ DB_PASSWORD → ***************ord
✓ API_TOKEN → ***************c21
✓ DATABASE_URL → ********************************************app
⭐ LEVEL CLEARED — 3/3 secrets loaded · .env writtenAzure prints no identity line. Values are masked: for a value longer than 10 characters only the last three characters are shown.
The resulting .env. Envilder quotes DATABASE_URL because it contains a space and a #, and reads the result back the way dotenv does before writing:
DB_PASSWORD=local-dev-password
API_TOKEN=dev-token-7f3a9c21
DATABASE_URL='postgres://app:p@ss w0rd#1@db.internal:5432/app'Or skip the file with envilder exec
If you only need the values to start a process, envilder exec resolves the same map file and starts your command with the secrets added to its environment, writing nothing to disk:
envilder exec -- node app.jsenvilder: 3 secrets resolved (azure, vault=my-vault.vault.azure.net) → node …The summary goes to stderr, so it never mixes with the output of your command, which reads the values as ordinary environment variables.
Which one to use
- Use envilder exec when you start the process yourself: npm scripts, tests, migrations. It writes no file; if you already pulled a .env, delete it when you switch. A missing or unreadable secret stops the command before it starts (exit code 125).
- Use a .env file when a tool reads the file by path or you cannot wrap its start command: Docker Compose env_file, an IDE run configuration, a framework that loads .env itself. A missing secret is only a warning in this mode, so check the summary (2/3 instead of 3/3).
Common errors
| Message | Fix |
|---|---|
vaultUrl is required when using Azure provider. Set it in $config.vaultUrl in your map file or via --vault-url flag. | Add "vaultUrl": "https://<vault-name>.vault.azure.net" to $config in envilder.json, or pass --vault-url. With --no-map-update on push, also pass --provider=azure. |
Secret name collision: '/my-app/api-key' and 'my-app-api-key' both resolve to 'my-app-api-key'. Use distinct Key Vault secret names in your map file when targeting Azure. | Two references in the map file resolve to the same Key Vault secret. Use one reference per secret. |
secret not found (path: *******************dsn) — skipped | The secret does not exist in that vault. Check the name after the rule above. Pull skips it and still exits with 0, so read the 2/3 in the summary; exec stops with 125. |
No map file found. Provide --map or create envilder.json in the current directory. | Run envilder from the directory that holds envilder.json, or pass --map=path/to/file.json. |
Any other failure, such as missing Azure credentials or access denied on the vault, stops the run. Pull lists each affected variable with its masked reference and the reason, leaves the .env file untouched and exits with 1. Exec exits with 125 without starting your command. Run az login again, or check your role on the vault.
Every message of pull mode is listed in the pull mode reference.
When a SaaS secrets manager is the better fit
This guide fits a team that already keeps secrets in Azure Key Vault and wants them in local development without adding a product. The Envilder CLI reads and writes Key Vault and AWS SSM, nothing else, and it has no dashboard or rotation of its own. A hosted manager such as Doppler or Infisical may suit you better when:
- Your secrets are not in Key Vault yet and you want one place to manage them, with a web interface for people who do not use a terminal.
- You need workflows around the secrets themselves, such as approvals, per-environment syncing to many platforms or rotation, and prefer a product that provides them.
- You do not want to run Azure access control for every developer who needs a local .env.
Those products are good tools for those jobs. If Key Vault is already your source of truth, Envilder keeps it that way.