Primeros pasos en 5 minutos

¿Cómo llevas un secreto de AWS SSM Parameter Store o Azure Key Vault a una app en marcha? Instala la CLI de Envilder, asocia el secreto a un nombre de variable en envilder.json y arranca la app con envilder exec, que pasa el valor al proceso sin escribir ningún archivo .env. Todo lleva unos cinco minutos cuando tus credenciales de la nube ya funcionan.

Qué vas a hacer

  1. Instalar la CLI de envilder.
  2. Subir un secreto de prueba a AWS SSM Parameter Store o a Azure Key Vault con envilder, que también escribe envilder.json.
  3. Revisar el envilder.json que ha creado: asocia un nombre de variable al secreto, nunca al valor.
  4. Arrancar una pequeña app de Node.js con envilder exec y comprobar que recibe el valor.

Requisitos previos

  • Node.js 22.12 o posterior.
  • AWS SSM: la AWS CLI con credenciales que funcionen (aws configure, o aws sso login para perfiles SSO) y una identidad con permiso para llamar a ssm:GetParameter sobre los parámetros que mapees. Si un parámetro SecureString está cifrado con una clave KMS gestionada por el cliente, la identidad también necesita kms:Decrypt sobre esa clave. Configuración de AWS SSM
  • Azure Key Vault: un Key Vault existente, la Azure CLI con la sesión iniciada mediante az login y el rol Key Vault Secrets User sobre el vault (o una directiva de acceso con Get sobre secretos). Envilder se autentica con DefaultAzureCredential, así que una identidad administrada o credenciales en variables de entorno también sirven. Configuración de Azure Key Vault

El paso 2 crea un secreto, lo que requiere permiso de escritura (ssm:PutParameter, o Key Vault Secrets Officer). Si el secreto ya existe, sáltalo y escribe envilder.json a mano como se muestra en el paso 3.

1. Instala la CLI

Instala envilder de forma global. Si prefieres no instalarlo, antepón npx a cada comando de esta guía.

npm install -g envilder
pnpm add -g envilder
npx envilder --version

Comprueba que el comando está en el PATH. Muestra la versión:

envilder --version
0.20.0

2. Sube un secreto de prueba

Elige tu proveedor. Un solo comando de envilder guarda el secreto en el vault y registra la asociación en envilder.json, así que este paso no necesita ni la AWS CLI ni la Azure CLI. La guía usa un único secreto: la contraseña de la base de datos de un entorno de desarrollo. El valor queda en el historial de la terminal; para secretos reales, haz el push desde un archivo .env con el modo push.

envilder --push --provider=aws --profile=default \
  --key=DB_PASSWORD --value=local-dev-password \
  --secret-path=/my-app/dev/db-password

En AWS, --provider=aws y --profile son opcionales: aws es el proveedor por defecto y, sin --profile, Envilder usa la cadena de credenciales por defecto de AWS. El perfil es una elección local y no se escribe en envilder.json.

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

Los nombres de Key Vault solo admiten letras, dígitos y guiones. Envilder convierte las barras en guiones y elimina la barra inicial antes de llamar a Azure, así que "/my-app/dev/db-password" resolvería el mismo secreto. Todo lo demás se envía tal como está escrito.

3. Revisa envilder.json

El push ha creado envilder.json en el directorio actual, o ha añadido la entrada si el archivo ya existía. Cada clave es el nombre de variable que lee tu app y cada valor es el identificador del secreto en tu vault. Para Azure también ha escrito $config con provider y vaultUrl; AWS no necesita $config.

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

El archivo contiene rutas de secretos, nunca valores, así que guárdalo en el repositorio junto al código. Los editores validan envilder.json a través de SchemaStore sin línea $schema. Para subir un secreto sin tocar el archivo de mapeo, añade --no-map-update.

4. Ejecuta tu app con envilder exec

Crea un pequeño script que lea la variable y arráncalo a través de Envilder. Todo lo que va después de -- es tu comando, que se pasa tal cual, sin shell.

app.jstypescript
const password = process.env.DB_PASSWORD;
console.log(
  password
    ? `DB_PASSWORD loaded (${password.length} characters)`
    : 'DB_PASSWORD missing',
);
envilder exec -- node app.js

Salida esperada. La primera línea es Envilder en stderr; la segunda, tu app en stdout:

envilder: 1 secret resolved (aws) → node …
DB_PASSWORD loaded (18 characters)
envilder: 1 secret resolved (azure, vault=my-vault.vault.azure.net) → node …
DB_PASSWORD loaded (18 characters)

Envilder resuelve todos los secretos mapeados y después arranca el comando con esos valores añadidos a su entorno. No escribe nada en disco. Si algún secreto falta, está vacío o no se puede leer, el comando no arranca y envilder termina con el código 125; si no, termina con el código de tu comando.

Para que esta sea la forma habitual de arrancar el proyecto, ponlo en un script de package.json y sigue usando npm run dev:

package.jsonjson
{
  "scripts": {
    "dev": "envilder exec -- node app.js"
  }
}

Alternativa: escribir un archivo .env

Algunas herramientas solo leen un archivo, como el env_file de Docker Compose o una configuración de ejecución del IDE. En esos casos, descarga los secretos a un archivo .env. Sin opciones, envilder lee envilder.json y escribe .env en el directorio actual:

envilder

Salida esperada con AWS, seguida del archivo que escribe:

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

🪙  RESOLVING SECRETS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ DB_PASSWORD         → ***************ord

⭐ LEVEL CLEARED  —  1/1 secrets loaded · .env written
.envdotenv
DB_PASSWORD=local-dev-password
⚠️
El archivo .env contiene los valores reales de los secretos: añádelo a .gitignore y bórralo cuando ya no lo necesites. A diferencia de exec, pull omite con un aviso un secreto que no existe y escribe igualmente los demás.

Errores habituales en la primera ejecución

Cada bloque muestra el texto que imprime envilder. Con exec, todos terminan con el código 125 y tu comando no llega a arrancar.

No se encuentra el archivo de mapeo

No map file found. Provide --map or create envilder.json in the current directory.

envilder busca envilder.json en el directorio actual. Ejecútalo desde la raíz del proyecto o pasa --map=ruta/a/envilder.json.

Sin credenciales de AWS

💥 GAME OVER — some secrets could not be fetched
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✗ DB_PASSWORD         → ********************ord

  ⮕ WHY?
     Could not load credentials from any providers

El SDK de AWS no ha encontrado credenciales. Ejecuta aws configure, o aws sso login para un perfil SSO. Para usar un perfil con nombre, pasa --profile=nombre o define "profile" en $config.

Acceso denegado por AWS

User: arn:aws:sts::123456789012:assumed-role/<role>/<session> is not authorized to perform: ssm:GetParameter on resource: arn:aws:ssm:eu-west-1:123456789012:parameter/my-app/dev/db-password …

Las credenciales funcionan, pero la identidad no puede leer ese parámetro. Permite ssm:GetParameter sobre el ARN del parámetro, y kms:Decrypt si el parámetro usa una clave gestionada por el cliente.

Secreto no encontrado

  ✗ DB_PASSWORD         → ********************ord

  ⮕ WHY?
     not found

El identificador o la región no son correctos. En AWS, Envilder toma la región de AWS_REGION, después de AWS_DEFAULT_REGION, después del perfil, y como último recurso usa us-east-1. Compáralo con aws ssm get-parameter --name /my-app/dev/db-password usando el mismo perfil. En Azure, revisa el nombre del secreto en el vault.

Azure sin URL del vault

vaultUrl is required when using Azure provider. Set it in $config.vaultUrl in your map file or via --vault-url flag.

Añade "vaultUrl": "https://<nombre-del-vault>.vault.azure.net" a $config, o pasa --vault-url.

Opciones antes de exec

error: Put envilder options after "exec": envilder exec --map=envilder.json -- node …

Las opciones escritas antes de exec se rechazan en lugar de ignorarse. Muévelas detrás de exec, como indica el mensaje.

--envfile con exec

error: --envfile cannot be used with exec: exec mode never reads or writes a .env file.

exec nunca escribe un archivo. Quita --envfile, o usa pull (envilder --envfile=.env) cuando necesites el archivo.

Siguientes pasos