Push mode reference

Prerequisites

• The envilder CLI. Single-secret push records the mapping since 0.16.
• Write access to the target: ssm:PutParameter on AWS, or the Set secret permission on Azure Key Vault, for example through the Key Vault Secrets Officer role.
• For --push, a map file and a .env file with the values. A single-secret push needs neither: it creates the map file when it is missing.

Synopsis

envilder --push [--envfile=<file>] [--map=<file>] \
  [--provider=aws|azure] [--vault-url=<url>] [--profile=<name>]

envilder [--push] --key=<NAME> --value=<value> --secret-path=<path> \
  [--map=<file>] [--no-map-update] \
  [--provider=aws|azure] [--vault-url=<url>] [--profile=<name>]

Push has two forms. --push uploads values from a .env file. --key, --value and --secret-path together upload one secret; --push is optional with them (the three options are enough), and the docs write it for clarity. There is no push subcommand. --ssm-path is a deprecated alias of --secret-path and prints a warning.

Push a .env file

For each variable the map file declares, Envilder reads its value from the .env file and writes it to the mapped path. Variables in the .env file that the map file does not declare are ignored.

With this map file and .env file, envilder --push writes two secrets and ignores LOG_LEVEL. Expected output with AWS (Azure prints the same lines without the identity line):

{
  "DB_PASSWORD": "/my-app/dev/db-password",
  "API_TOKEN": "/my-app/dev/api-token"
}

DB_PASSWORD=rotated-password-2026
API_TOKEN=prod-token-91c2e4
LOG_LEVEL=debug

envilder --push

☁ AWS identity · account=123456789012 · region=eu-west-1 · profile=default
Starting push operation from '.env' using map 'envilder.json'
Loading parameter map from 'envilder.json'
Loading environment variables from '.env'
Found 2 parameter mappings in map file
Found 3 environment variables in env file
Validated 2 environment variables mapping to 2 unique secrets
Processing 2 unique secrets
Pushed DB_PASSWORD=******************026 to secret store at path ********************ord
Pushed API_TOKEN=**************2e4 to secret store at path ******************ken
Successfully pushed environment variables from '.env' to secret store.

• A mapped variable that is missing from the .env file is skipped with a warning. A missing .env file is not an error either: every variable is skipped and the run exits with 0.
• Several variables can map to the same path only when they hold the same value. Otherwise Envilder stops before writing anything.
• Secrets are written in parallel. Throttling errors are retried up to 5 times with backoff. Any other error stops the run with exit code 1, and secrets already written stay written.

Push a single secret

Pass the variable name, the value and the secret path. Envilder writes the secret and records "NAME": "<path>" in the map file, so the next envilder or envilder exec resolves it. The value is never written to the map file.

In a directory without a map file, push one secret. The command, its expected output and the map file it creates:

envilder --push --key=API_KEY --value=dev-api-key-4821 --secret-path=/my-app/dev/api-key

envilder --push --provider=azure --vault-url=https://my-vault.vault.azure.net \
  --key=API_KEY --value=dev-api-key-4821 --secret-path=/my-app/dev/api-key

Using configuration: provider=aws

☁ AWS identity · account=123456789012 · region=eu-west-1 · profile=default

📤 PUSHING SECRET
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  → API_KEY → ****************key

⭐ SECRET PUSHED  —  API_KEY=*************821 → ****************key

✓ Created envilder.json

Using configuration: provider=azure, vault=https://my-vault.vault.azure.net

📤 PUSHING SECRET
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  → API_KEY → ****************key

⭐ SECRET PUSHED  —  API_KEY=*************821 → ****************key

✓ Created envilder.json

{
  "API_KEY": "/my-app/dev/api-key"
}

{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "API_KEY": "/my-app/dev/api-key"
}

How the map file is updated

• No file: Envilder creates it. A file named envilder.json or envilder.*.json gets no $schema line, because editors already recognise it through SchemaStore; any other name gets one.
• The variable is not in the file: the entry is appended, keeping the indentation and line endings of the file (✓ Added API_KEY to envilder.json).
• The variable already maps to the same path: the file is not touched (✓ API_KEY already mapped in envilder.json, no changes).
• The variable maps to another path: nothing is pushed and Envilder exits with 1.
• The file targets another provider or vault than the push: the secret is pushed, the file is left as it is and a warning names both targets.
• The map file is written before the secret. If the push fails, Envilder restores the previous file, or deletes the one it created, so the file never lists a secret that was not pushed.

How values are stored

AWS SSM. Every value is written with PutParameter as a SecureString, with overwrite enabled: a new parameter is created and an existing one gets a new version. Envilder passes no KMS key, so SSM uses the default key of the account.

Azure Key Vault. Every value is written with Set Secret, which creates the secret or adds a new version. The secret name is the path with its leading slashes removed and the other slashes turned into hyphens: /my-app/dev/api-key becomes my-app-dev-api-key. Nothing else changes, so a name Key Vault does not accept, for example one with _ or ., fails with Key Vault's own error. Two references that resolve to the same name in one run are an error.

Common errors

Related pages

• Map file reference: $config fields and validation rules
• Pull mode: write the pushed secrets to a .env file
• Azure Key Vault setup: roles and access policies for reading and writing secrets