Referencia del modo pull

Requisitos previos

• La CLI de envilder.
• Un archivo de mapeo, envilder.json por defecto, que asocia cada variable a un identificador de secreto.
• Acceso de lectura a todos los secretos mapeados: ssm:GetParameter en AWS (más kms:Decrypt cuando un parámetro usa una clave administrada por el cliente), o el permiso Get de secretos en Azure Key Vault, por ejemplo con el rol Key Vault Secrets User.
• Credenciales que el SDK del proveedor pueda encontrar: un perfil de AWS, una sesión SSO o variables de entorno, o un inicio de sesión de Azure como az login o una identidad administrada.

Sinopsis

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

Pull es el modo por defecto: no hay ningún subcomando pull. Ejecuta envilder sin opciones para leer envilder.json y escribir .env en el directorio actual. Añadir --push, o --key, --value y --secret-path, cambia al modo push, y envilder exec es un subcomando aparte.

Opciones

Una opción que recibe una ruta o un nombre nunca acepta un valor que empiece por -. En envilder --map --envfile=.env, --map no tiene valor, así que la ejecución se detiene con error: option '--map <path>' argument missing en lugar de leer --envfile=.env como ruta. envilder --help lista todas las opciones.

Cómo se combinan $config y las opciones

Cada ajuste sale de la primera fuente que lo define: la opción, después $config en el archivo de mapeo y después el valor por defecto. Una opción sustituye solo el campo que nombra, así que el resto de campos de $config se siguen aplicando. Toma este archivo de producción:

{
  "$config": { "provider": "aws", "profile": "prod-account" },
  "DB_PASSWORD": "/my-app/prod/db-password"
}

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

El primer comando usa la configuración del archivo. El segundo sustituye un campo y mantiene el resto:

envilder --map=envilder.prod.json --envfile=.env.prod
envilder --map=envilder.prod.json --envfile=.env.prod --profile=ci-readonly

envilder --map=envilder.prod.json --envfile=.env.prod
envilder --map=envilder.prod.json --envfile=.env.prod \
  --vault-url=https://my-app-dr.vault.azure.net

Reglas de precedencia completas en la referencia del archivo de mapeo

Ejemplo: actualizar un .env existente

El archivo de mapeo declara cuatro variables. En el vault, SENTRY_DSN no existe y FEATURE_FLAG está vacío. El proyecto ya tiene un archivo .env:

{
  "DB_PASSWORD": "/my-app/dev/db-password",
  "API_TOKEN": "/my-app/dev/api-token",
  "SENTRY_DSN": "/my-app/dev/sentry-dsn",
  "FEATURE_FLAG": "/my-app/dev/feature-flag"
}

# Local settings
LOG_LEVEL=debug
DB_PASSWORD=old-password
SENTRY_DSN=https://old-dsn.example.com/1

Ejecuta envilder desde la raíz del proyecto. Salida esperada con AWS:

envilder

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

🪙  RESOLVING SECRETS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ DB_PASSWORD         → ***************ord
  ✓ API_TOKEN           → ***************c21
  ✗ SENTRY_DSN           secret not found (path: *******************dsn) — skipped
  ⚠ FEATURE_FLAG         no value found (path: *********************lag) — skipped

⭐ LEVEL CLEARED  —  2/4 secrets loaded · .env written

Con Azure no se muestra la línea de identidad de AWS; el resto es igual. Los valores van enmascarados: uno de más de 10 caracteres muestra los 3 últimos, uno más corto se oculta entero, y las rutas muestran sus 3 últimos caracteres. Las líneas omitidas son avisos en stderr; el resto va a stdout.

El archivo .env después:

# Local settings
LOG_LEVEL=debug
DB_PASSWORD=local-dev-password
SENTRY_DSN=https://old-dsn.example.com/1
API_TOKEN=dev-token-7f3a9c21

Cómo se actualiza un .env existente

• Una variable mapeada que ya está en el archivo se sustituye en su sitio: la misma línea, el mismo comentario en línea y las mismas comillas cuando todavía representan el valor nuevo.
• Una línea que ya tiene el valor correcto no se reescribe, así que una ejecución sin nada nuevo deja el archivo idéntico byte a byte.
• Se conservan las líneas que el archivo de mapeo no declara (LOG_LEVEL en el ejemplo), los comentarios, las líneas en blanco, el orden y los saltos de línea.
• Las variables que todavía no están en el archivo se añaden al final. Un archivo nuevo termina con un salto de línea.
• Un secreto omitido conserva el valor que el archivo ya tenía (SENTRY_DSN en el ejemplo). Envilder nunca elimina una línea.
• Antes de escribir, Envilder vuelve a leer el resultado como lo hace dotenv. Si se perdiera o cambiara algún valor, no escribe nada y se detiene con un error que nombra las variables, nunca los valores.

Las comillas, los valores multilínea y el único valor que un archivo .env no puede contener se describen en qué puede contener un secreto

Secretos que faltan, vacíos o que fallan

Un secreto que no existe (ParameterNotFound en AWS SSM, 404 en Key Vault) o cuyo valor está vacío se omite con un aviso. Los demás secretos se escriben igualmente, el resumen cuenta solo los resueltos (2/4 en el ejemplo) y el código de salida es 0.

Cualquier otro fallo, como un acceso denegado, credenciales que faltan o un error de red, detiene la ejecución. Envilder lista cada variable afectada con su ruta enmascarada y el motivo, no toca el archivo .env y sale con 1:

💥 GAME OVER — some secrets could not be fetched
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✗ API_TOKEN           → ******************ken

  ⮕ WHY?
     User: arn:aws:sts::123456789012:assumed-role/dev/session is not authorized to perform: ssm:GetParameter on resource: arn:aws:ssm:eu-west-1:123456789012:parameter/my-app/dev/api-token …

Cuando una sesión SSO de AWS ha caducado y stdin y stdout son un terminal, Envilder pregunta Run 'aws sso login --profile dev' now? [y/N]. Si aceptas y el inicio de sesión funciona, lo vuelve a intentar una vez. En CI, o si lo rechazas, muestra el comando que hay que ejecutar y sale con 1. Si un secreto que falta también debe detener la ejecución, usa envilder exec: nunca arranca un comando con un conjunto de secretos incompleto.

Errores habituales

Páginas relacionadas

• Referencia del archivo de mapeo: campos de $config, reglas de validación y precedencia de las opciones
• envilder exec: ejecuta un comando con los mismos secretos y sin archivo .env
• Modo push: sube un archivo .env o un solo secreto
• Guía: carga parámetros de AWS SSM en un archivo .env, paso a paso