Referencia del modo push

Requisitos previos

• La CLI de envilder. El push de un solo secreto registra el mapeo desde la 0.16.
• Acceso de escritura al destino: ssm:PutParameter en AWS, o el permiso Set de secretos en Azure Key Vault, por ejemplo con el rol Key Vault Secrets Officer.
• Para --push, un archivo de mapeo y un archivo .env con los valores. El push de un solo secreto no necesita ninguno de los dos: crea el archivo de mapeo si no existe.

Sinopsis

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 tiene dos formas. --push sube valores de un archivo .env. --key, --value y --secret-path juntos suben un solo secreto; con ellos, --push es opcional (bastan las tres opciones), y la documentación lo escribe por claridad. No hay ningún subcomando push. --ssm-path es un alias obsoleto de --secret-path y muestra un aviso.

Subir un archivo .env

Para cada variable que declara el archivo de mapeo, Envilder lee su valor del archivo .env y lo escribe en la ruta mapeada. Las variables del archivo .env que el archivo de mapeo no declara se ignoran.

Con este archivo de mapeo y este .env, envilder --push escribe dos secretos e ignora LOG_LEVEL. Salida esperada con AWS (Azure muestra las mismas líneas sin la de identidad):

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

• Una variable mapeada que no está en el archivo .env se omite con un aviso. Que el archivo .env no exista tampoco es un error: se omiten todas las variables y la ejecución sale con 0.
• Varias variables pueden apuntar a la misma ruta solo si tienen el mismo valor. Si no, Envilder se detiene antes de escribir nada.
• Los secretos se escriben en paralelo. Los errores de limitación (throttling) se reintentan hasta 5 veces con espera creciente. Cualquier otro error detiene la ejecución con código 1, y los secretos ya escritos se quedan escritos.

Subir un solo secreto

Pasa el nombre de la variable, el valor y la ruta del secreto. Envilder escribe el secreto y registra "NOMBRE": "<ruta>" en el archivo de mapeo, para que el siguiente envilder o envilder exec lo resuelva. El valor nunca se escribe en el archivo de mapeo.

En un directorio sin archivo de mapeo, sube un secreto. El comando, la salida esperada y el archivo de mapeo que crea:

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"
}

Cómo se actualiza el archivo de mapeo

• Sin archivo: Envilder lo crea. Un archivo llamado envilder.json o envilder.*.json no recibe la línea $schema, porque los editores ya lo reconocen a través de SchemaStore; cualquier otro nombre la recibe.
• La variable no está en el archivo: se añade la entrada, manteniendo la sangría y los saltos de línea del archivo (✓ Added API_KEY to envilder.json).
• La variable ya apunta a la misma ruta: el archivo no se toca (✓ API_KEY already mapped in envilder.json, no changes).
• La variable apunta a otra ruta: no se sube nada y Envilder sale con 1.
• El archivo apunta a otro proveedor o vault que el push: el secreto se sube, el archivo se queda como está y un aviso nombra los dos destinos.
• El archivo de mapeo se escribe antes que el secreto. Si el push falla, Envilder restaura el archivo anterior, o borra el que ha creado, de modo que el archivo nunca lista un secreto que no se ha subido.

Cómo se guardan los valores

AWS SSM. Cada valor se escribe con PutParameter como SecureString, con la sobrescritura activada: se crea un parámetro nuevo o el existente recibe una versión nueva. Envilder no pasa ninguna clave KMS, así que SSM usa la clave por defecto de la cuenta.

Azure Key Vault. Cada valor se escribe con Set Secret, que crea el secreto o le añade una versión nueva. El nombre del secreto es la ruta sin las barras iniciales y con el resto de barras convertidas en guiones: /my-app/dev/api-key pasa a ser my-app-dev-api-key. No cambia nada más, así que un nombre que Key Vault no acepta, por ejemplo uno con _ o ., falla con el error propio de Key Vault. Dos referencias que dan el mismo nombre en una misma ejecución son un error.

Errores habituales

Páginas relacionadas

• Referencia del archivo de mapeo: campos de $config y reglas de validación
• Modo pull: escribe los secretos subidos en un archivo .env
• Configuración de Azure Key Vault: roles y directivas de acceso para leer y escribir secretos