davidnussio/envsecHerramienta CLI segura para gestionar secretos de entorno utilizando almacenes de credenciales nativos del SO (macOS Keychain, Linux Secret Service, Windows Credential Manager)
Gestión segura de secretos de entorno mediante almacenes de credenciales nativos del sistema operativo.
myapp.dev, stripe-api.prod, work.staging)cmd (buscar, listar, ejecutar, eliminar).env (con seguimiento de generación mediante audit)eval $(envsec env)).env (con detección de conflictos)envsec tui) para gestionar secretos sin memorizar comandosEste es un monorepo que contiene los siguientes paquetes:
Para acceso programático a secretos desde Node.js o Bun, usa @envsec/sdk:```bash
npm install @envsec/sdk
Aquí tienes la traducción al español del chunk 3 de 85:
---
**Nota:** El texto original no fue proporcionado en el mensaje. Para traducir el contenido, necesito el texto del chunk 3. Por favor, proporciona el contenido del chunk 3 para poder traducirlo.```typescript
import { loadSecrets } from "@envsec/sdk";
// Load and inject into process.env
await loadSecrets({ context: "myapp.dev", inject: true });
// Or use the client for full control
import { EnvsecClient } from "@envsec/sdk";
const client = await EnvsecClient.create({ context: "myapp.dev" });
const apiKey = await client.get("api.key");
await client.close();
Consulta la documentación completa del SDK para todas las APIs, soporte multi-contexto y opciones.
Sin dependencias adicionales. Utiliza el Llavero integrado mediante la herramienta CLI security.
Requiere libsecret-tools (proporciona el comando secret-tool), que se comunica con GNOME Keyring, KDE Wallet o cualquier proveedor de la API Secret Service a través de D-Bus.```bash
sudo apt install libsecret-tools
sudo dnf install libsecret
sudo pacman -S libsecret
Debe estar activa una sesión D-Bus en ejecución y un demonio de llavero (por ejemplo, `gnome-keyring-daemon`). La mayoría de los entornos de escritorio gestionan esto automáticamente.
### Windows
Sin dependencias adicionales. Utiliza el Administrador de credenciales integrado de Windows mediante `cmdkey` y PowerShell.
## Instalación
### Homebrew (macOS / Linux)```bash
brew tap davidnussio/homebrew-tap
brew install envsec
npm install -g envsec
### npx (sin instalación)```bash
npx envsec
mise use -g npm:envsec
## Uso
La mayoría de los comandos requieren un contexto especificado con `--context` (o `-c`).
Un contexto es una etiqueta de forma libre para agrupar secretos — p. ej. `myapp.dev`, `stripe-api.prod`, `work.staging`.
### Opciones globales
Estas opciones están disponibles en todos los comandos:
- `--context`, `-c` — Nombre del contexto (p. ej. `myapp.dev`, `stripe-api.prod`). También lee la variable de entorno `ENVSEC_CONTEXT`
- `--debug`, `-d` — Habilita el registro de depuración
- `--json` — Salida en formato JSON para scripting
- `--db` — Ruta al archivo de base de datos SQLite (predeterminado: `~/.envsec/store.sqlite`). También lee la variable de entorno `ENVSEC_DB`
### Ruta de base de datos personalizada
De forma predeterminada, los metadatos se almacenan en `~/.envsec/store.sqlite`. Puedes sobrescribir esto con `--db` o la variable de entorno `ENVSEC_DB`:```bash
# Use a project-local database
envsec --db ./local-store.sqlite -c myapp.dev list
# Or via environment variable
export ENVSEC_DB=/shared/team/envsec.sqlite
envsec -c myapp.dev list
El flag --db tiene prioridad sobre ENVSEC_DB. Los casos de uso incluyen bases de datos por proyecto, bases de datos compartidas por equipos en unidades de red y CI/CD con almacenamiento efímero.
Almacena un secreto en el almacén de credenciales del sistema operativo.
<key> — Nombre de la clave del secreto (p. ej. api.key, db.password)--value, -v — Valor a almacenar (omitir para un prompt interactivo enmascarado)--expires, -e — Duración de expiración (p. ej. 30m, 2h, 7d, 4w, 3mo, 1y)```bashenvsec -c myapp.dev add api.key --value "sk-abc123"
envsec -c myapp.dev add api.key -v "sk-abc123"
envsec -c myapp.dev add api.key
envsec -c myapp.dev add api.key -v "sk-abc123" --expires 30d
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo
### Obtener un secreto
Recupera un valor de secreto del almacén de credenciales del sistema operativo.
- `<key>` — Nombre de la clave del secreto a recuperar
- `--quiet`, `-q` — Imprime solo el valor bruto (sin advertencias ni salida adicional)
- `--json` — Salida en formato JSON (incluye contexto, clave, valor, expires_at)```bash
envsec -c myapp.dev get api.key
# Print only the raw value (no warnings or extra output)
envsec -c myapp.dev get api.key --quiet
envsec -c myapp.dev get api.key -q
Elimina un secreto del almacén de credenciales del sistema operativo.
<key> — Nombre de la clave del secreto a eliminar (opcional si se usa --all)--yes, -y — Omitir la solicitud de confirmación--all — Eliminar todos los secretos en el contexto```bash
envsec -c myapp.dev delete api.keyenvsec -c myapp.dev del api.key
### Renombrar un secreto
Renombra una clave de secreto dentro del mismo contexto. Se conservan el valor y los metadatos de caducidad.
- `<old-key>` — Nombre actual de la clave de secreto
- `<new-key>` — Nuevo nombre de la clave de secreto
- `--force`, `-f` — Sobrescribe el destino si ya existe```bash
# Rename a key
envsec -c myapp.dev rename old.key new.key
# Overwrite target if it already exists
envsec -c myapp.dev rename old.key existing.key --force
Lista todas las claves secretas y metadatos en un contexto.
--json — Salida en formato JSON```bash
envsec -c myapp.dev list### Listar todos los contextos
Lista todos los contextos disponibles con el número de secretos.
- `--json` — Salida en formato JSON```bash
# Without --context, lists all available contexts with secret counts
envsec list
Busque secretos o contextos usando patrones glob.
<pattern> — Patrón glob para buscar (p. ej. api.*, myapp.*)--json — Salida en formato JSON```bashenvsec -c myapp.dev search "api.*"
envsec search "myapp.*"
### Mover secretos entre contextos
Mueve secretos de un contexto a otro. Los secretos de origen se eliminan después de moverlos.
- `<pattern>` — Patrón glob o clave exacta a mover (opcional si se usa `--all`)
- `--to`, `-t` — Contexto de destino al que mover los secretos
- `--all` — Mover todos los secretos del contexto de origen
- `--force`, `-f` — Sobrescribir secretos existentes en el contexto de destino
- `--yes`, `-y` — Omitir la solicitud de confirmación```bash
# Move a single secret
envsec -c myapp.dev move api.token --to myapp.prod
# Move secrets matching a glob pattern
envsec -c myapp.dev move "redis.*" --to myapp.prod -y
# Move all secrets from one context to another
envsec -c myapp.dev move --all --to myapp.prod -y
# Overwrite existing secrets in the target context
envsec -c myapp.dev move "redis.*" --to myapp.prod --force -y
Copia secretos de un contexto a otro. Los secretos de origen permanecen intactos.
<pattern> — Patrón glob o clave exacta a copiar (opcional si se usa --all)--to, -t — Contexto de destino al que copiar los secretos--all — Copiar todos los secretos del contexto de origen--force, -f — Sobrescribir secretos existentes en el contexto de destino--yes, -y — Omitir la solicitud de confirmación```bashenvsec -c myapp.dev copy api.token --to myapp.staging
envsec -c myapp.dev copy "redis.*" --to myapp.staging -y
envsec -c myapp.dev copy --all --to myapp.staging -y
envsec -c myapp.dev copy "redis.*" --to myapp.staging --force -y
### Ejecutar un comando con secretos
Ejecuta un comando con valores secretos interpolados mediante marcadores de posición o inyectados como variables de entorno.
- `<command>` — Comando a ejecutar. Usa marcadores de posición `{key}` para la interpolación de secretos
- `--inject`, `-i` — Inyecta todos los secretos del contexto como variables de entorno (`KEY.NAME` → `KEY_NAME`)
- `--save`, `-s` — Guarda este comando para uso posterior
- `--name`, `-n` — Nombre para el comando guardado (se solicita de forma interactiva si se omite con `--save`)```bash
# Placeholders {key} are resolved with secret values before execution
envsec -c myapp.dev run 'curl {api.url} -H "Authorization: Bearer {api.token}"'
# Any {dotted.key} in the command string is replaced with its value
envsec -c myapp.prod run 'psql {db.connection_string}'
# Inject ALL context secrets as environment variables (KEY.NAME → KEY_NAME)
envsec -c myapp.dev run --inject 'node server.js'
envsec -c myapp.dev run -i 'docker compose up'
# Combine --inject with placeholders
envsec -c myapp.dev run --inject 'curl {api.url} -H "Authorization: Bearer $API_TOKEN"'
# Save the command for later use with --save (-s) and --name (-n)
envsec -c myapp.dev run --save --name deploy 'kubectl apply -f - <<< {k8s.manifest}'
# If you use --save without --name, you'll be prompted interactively
envsec -c myapp.dev run --save 'psql {db.connection_string}'
Si algún marcador de posición hace referencia a un secreto que no existe, el comando no se ejecutará y verás un error claro:``` ❌ Missing secrets in context "myapp.dev":
Add them with: envsec -c myapp.dev add
### Comandos guardados
Los comandos guardados se encuentran bajo el subcomando `cmd`, manteniéndolos separados de las operaciones secretas.
#### cmd list
Lista todos los comandos guardados.```bash
envsec cmd list
Ejecuta un comando guardado (usa el contexto con el que se guardó).
<name> — Nombre del comando guardado que se va a ejecutar--override-context, -o — Sobrescribe el contexto guardado en el momento de la ejecución--quiet, -q — Suprime la salida informativa (imprime solo la salida del comando)--inject, -i — Inyecta todos los secretos del contexto como variables de entorno```bash
envsec cmd run deployenvsec cmd run deploy --quiet envsec cmd run deploy -q
envsec cmd run deploy --override-context myapp.prod envsec cmd run deploy -o myapp.prod
envsec cmd run deploy --inject envsec cmd run deploy -i
#### cmd search
Busca comandos guardados por nombre o cadena de comando.
- `<pattern>` — Patrón de búsqueda
- `--name`, `-n` — Buscar solo en nombres de comandos
- `--command`, `-m` — Buscar solo en cadenas de comandos```bash
envsec cmd search psql
# Search only by name
envsec cmd search deploy -n
# Search only by command string
envsec cmd search kubectl -m
Elimina un comando guardado.
<name> — Nombre del comando a eliminar```bash
envsec cmd delete deploy### Generar un archivo .env
Exporta todos los secretos de un contexto a un archivo `.env`.
- `--output`, `-o` — Ruta del archivo de salida (predeterminado: `.env`)```bash
# Creates .env with all secrets from the context
envsec -c myapp.dev env-file
# Specify a custom output path
envsec -c myapp.dev env-file --output .env.local
Las claves se convierten a UPPER_SNAKE_CASE (p. ej. api.token → API_TOKEN).
Genera sentencias de exportación para usar con eval o al cargar el shell.
--shell, -s — Sintaxis del shell de destino: bash (predeterminado), zsh, fish, powershell--unset, -u — Genera comandos de unset/eliminación en lugar de exportación```basheval $(envsec -c myapp.dev env)
envsec -c myapp.dev env --shell fish envsec -c myapp.dev env --shell powershell
eval $(envsec -c myapp.dev env --unset)
envsec -c myapp.dev env --unset --shell fish
Shells compatibles: `bash` (predeterminado), `zsh`, `fish`, `powershell`. Las claves se convierten a `UPPER_SNAKE_CASE` (p. ej. `api.token` → `API_TOKEN`). La salida va a stdout para poder canalizarse a `eval` o cargarse directamente — no se escribe ningún archivo en disco.
### Iniciar una sesión de shell con ámbito de secretos
Abre un subshell interactivo con todos los secretos del contexto inyectados como
variables de entorno. Cuando ejecutes `exit`, los secretos desaparecen — no se necesita limpieza.
- `--shell`, `-s` — Shell a iniciar (`bash`, `zsh`, `fish`, `powershell`). Predeterminado: detección automática
- `--no-inherit` — No heredar variables de entorno del proceso padre
- `--quiet`, `-q` — Suprimir el banner de inicio/salida```bash
envsec -c myapp.dev shell
## 🛡️ Características
- **Escaneo de puertos**: Detecta puertos abiertos y servicios en ejecución.
- **Detección de vulnerabilidades**: Identifica vulnerabilidades conocidas en servicios y aplicaciones.
- **Fuerza bruta**: Prueba credenciales débiles en servicios como SSH, FTP, HTTP, etc.
- **Explotación**: Ejecuta exploits para comprometer sistemas vulnerables.
- **Post-explotación**: Recopila información y mantiene el acceso después de la explotación.
- **Informes**: Genera informes detallados de los hallazgos.
▶ envsec shell — context: myapp.dev (8 secrets loaded) Type 'exit' or press Ctrl+D to leave the session.
(envsec:myapp.dev) ~ $ echo $DATABASE_URL postgres://user:pass@localhost/mydb
(envsec:myapp.dev) ~ $ exit → Exiting envsec shell — secrets cleared.
Aquí tienes la traducción al español del fragmento 55 de 85:
---
**Nota:** El contenido de entrada está vacío. No hay texto que traducir.```bash
# Force a specific shell
envsec -c myapp.dev shell --shell zsh
# Only envsec secrets in env (no parent variables, except PATH)
envsec -c myapp.dev shell --no-inherit
# Suppress the startup/exit banner
envsec -c myapp.dev shell --quiet
La variable ENVSEC_CONTEXT siempre está establecida dentro de la sesión, por lo que puedes
hacer referencia a ella en scripts o personalizaciones del prompt.
Importa secretos desde un archivo .env a un contexto.
--input, -i — Ruta del archivo .env de entrada (predeterminado: .env)--force, -f — Sobrescribir secretos existentes sin preguntar--batch, -b — Modo por lotes: diferir la persistencia en la base de datos hasta que se importen todos los secretos```bashenvsec -c myapp.dev load
envsec -c myapp.dev load --input .env.local
envsec -c myapp.dev load --force
Las claves se convierten de `UPPER_SNAKE_CASE` a `dotted.lowercase` (p. ej., `API_TOKEN` → `api.token`). Si una clave ya existe, se omite con una advertencia a menos que se proporcione `--force` (`-f`).
### Compartir secretos (cifrado GPG)
Cifra todos los secretos de un contexto para un miembro del equipo usando GPG.
- `--encrypt-to` — Clave de destinatario GPG (correo electrónico, ID de clave o huella digital) para cifrar
- `--output`, `-o` — Ruta del archivo de salida (predeterminado: stdout). Use `-` para stdout explícitamente
- `--json` — Use formato JSON dentro de la carga útil cifrada (predeterminado: formato `.env`)```bash
# Encrypt all secrets from a context for a team member
envsec -c myapp.dev share --encrypt-to [email protected]
# Save encrypted output to a file
envsec -c myapp.dev share --encrypt-to [email protected] -o secrets.enc
# Use JSON format inside the encrypted payload
envsec -c myapp.dev --json share --encrypt-to [email protected] -o secrets.enc
El destinatario puede descifrar con gpg --decrypt secrets.enc y canalizar el resultado hacia envsec load. Por defecto, la carga útil cifrada utiliza el formato .env (KEY="value"); con --json utiliza un objeto JSON estructurado. Requiere que GPG esté instalado y que la clave pública del destinatario esté en tu llavero de claves.
Comprueba si hay secretos caducados o próximos a caducar y exportaciones de archivos .env rastreados.
--within, -w — Muestra los secretos que caducan dentro de esta duración (por defecto: 30d). Usa 0d para mostrar solo los ya caducados--json — Salida en formato JSON```bashenvsec -c myapp.dev audit
envsec -c myapp.dev audit --within 7d
envsec -c myapp.dev audit --within 0d
envsec audit
envsec -c myapp.dev audit --json
Los secretos con una duración `--expires` establecida mediante `envsec add` se rastrean en los metadatos. El comando `audit` busca secretos que ya hayan expirado o que expiren dentro de la ventana especificada. Los comandos `get` y `list` también muestran advertencias de expiración en línea.
El comando `audit` también rastrea los archivos `.env` generados. Cada vez que se usa `env-file`, se registran la ruta de salida, el contexto y la marca de tiempo. La salida de auditoría incluye una segunda sección que lista estos archivos. Si un archivo `.env` rastreado ya no existe en el disco, la auditoría lo elimina automáticamente de los metadatos e informa de la limpieza.
### Generar un secreto aleatorio
Genera un secreto aleatorio criptográficamente seguro, con la opción de almacenarlo.
- `<key>` — Nombre de la clave del secreto (opcional; omitir para la generación independiente de contraseñas)
- `--length`, `-l` — Longitud del secreto generado (predeterminado: `32`)
- `--prefix`, `-p` — Prefijo a anteponer al secreto generado (p. ej. `sk_`)
- `--expires`, `-e` — Duración de expiración (p. ej. `30m`, `2h`, `7d`, `4w`, `3mo`, `1y`)
- `--alphanumeric`, `-a` — Usar solo caracteres alfanuméricos `[a-zA-Z0-9]` (predeterminado)
- `--special`, `-s` — Incluir caracteres especiales comunes `[a-zA-Z0-9!@#$%^&*]`
- `--all-chars`, `-A` — Usar todos los caracteres ASCII imprimibles para máxima entropía```bash
# Generate and store a 32-char alphanumeric secret
envsec -c myapp.dev secret api.key
# Custom length and prefix
envsec -c myapp.dev secret api.key --prefix "sk_" --length 48
# Character sets:
# --alphanumeric (-a) [a-zA-Z0-9] (default)
# --special (-s) [a-zA-Z0-9] + !@#$%^&*
# --all-chars (-A) all printable ASCII
envsec -c myapp.dev secret db.password --special --length 64
# With expiry
envsec -c myapp.dev secret api.key --prefix "sk_" -l 48 --expires 90d
# Standalone password generator (no store, just print)
envsec secret --length 32
envsec secret --special --length 64 --prefix "pk_"
Cuando se proporcionan tanto el contexto como la clave, el valor generado se almacena y se imprime. Sin ninguno de los dos, el valor sin procesar va a stdout, lo que resulta útil para canalizarlo a pbcopy, xclip u otras herramientas.
envsec incluye una interfaz de terminal a pantalla completa para gestionar secretos de forma interactiva, sin necesidad de memorizar comandos.```bash
envsec tui
envsec -c myapp.dev tui
La TUI proporciona ocho pantallas accesibles desde el menú principal:
- **Contextos** — explora todos los contextos, establece el contexto activo con `s`, limpia el contexto con `x`, consulta los recuentos de secretos, elimina contextos completos
- **Secretos** — lista los secretos en una tabla, revela valores, añade o elimina secretos
- **Añadir secreto** — formulario interactivo con entrada enmascarada y duración de expiración opcional
- **Buscar** — búsqueda con patrón glob entre secretos o contextos
- **Comandos guardados** — lista, consulta y elimina plantillas de comandos guardadas
- **Auditoría** — comprueba secretos expirados o próximos a expirar, revisa las exportaciones de archivos `.env` rastreadas
- **Importar .env** — carga secretos desde un archivo `.env` al contexto actual
- **Exportar .env** — exporta secretos a un archivo `.env` (rastreado para auditoría)
Atajos de teclado:
| Tecla | Acción |
|-----|--------|
| `↑` / `↓` | Navegar por los elementos del menú y las filas de la tabla |
| `Enter` | Seleccionar / confirmar |
| `c` | Abrir la vista de contextos (menú principal) |
| `s` | Establecer el elemento seleccionado como contexto activo (vista de contextos) |
| `x` | Limpiar el contexto activo (vista de contextos) |
| `a` | Añadir un nuevo secreto (vista de secretos) |
| `d` | Eliminar el elemento seleccionado |
| `r` | Revelar el valor del secreto (vista de detalle) |
| `Esc` | Volver atrás / cancelar |
| `q` | Salir de la TUI |
### Diagnostica tu configuración
Ejecuta comprobaciones de estado para verificar tu instalación de envsec.
- `--json` — Salida en formato JSON para scripting```bash
# Run all health checks
envsec doctor
# JSON output for scripting
envsec --json doctor
El comando doctor verifica que tu instalación de envsec funcione correctamente. Comprueba:
ENVSEC_DB, ENVSEC_CONTEXT)envsec admite el completado dinámico con tabulador para bash, zsh y fish. Los completados son sensibles al contexto: sugieren tus nombres de contexto reales, claves secretas y nombres de comandos guardados en tiempo real consultando la base de datos de metadatos.```bash
eval "$(envsec --completions bash)"
eval "$(envsec --completions zsh)"
envsec --completions fish | source
Lo que se completa dinámicamente:
- `--context` / `-c` — lista todos tus contextos
- Argumentos de clave secreta (`get`, `add`, `delete`) — lista claves para el contexto actual
- `cmd run` / `cmd delete` — lista nombres de comandos guardados
- `--override-context` / `-o` — lista contextos para `cmd run`
- Subcomandos, banderas y opciones estáticas (shells, etc.) también se completan
## Comparación
¿Cómo se compara envsec con otras herramientas para gestionar secretos de entorno?
| Característica | envsec | dotenv / dotenvx | CLI de 1Password (`op`) |
|---|---|---|---|
| Almacenamiento de secretos | Almacén de credenciales del SO (Keychain, Secret Service, Credential Manager) | Archivos `.env` en disco (dotenvx añade cifrado) | Bóveda en la nube de 1Password |
| Cifrado en reposo | Delegado al SO (Keychain, GNOME Keyring, DPAPI) | Ninguno (dotenv) / ECIES por archivo (dotenvx) | AES-256 en la nube de 1Password |
| Secretos en disco | Nunca — los valores van directamente al almacén de credenciales del SO | Siempre — los archivos `.env` son texto plano por defecto | Nunca localmente (se obtienen en tiempo de ejecución desde la nube) |
| Acceso sin conexión | Completo — los secretos son locales en el almacén del SO | Completo — los archivos son locales | Requiere red (los elementos en caché están disponibles sin conexión en la app) |
| Cuenta / suscripción | Ninguna — gratis, código abierto, sin registro | Gratis (dotenv) / código abierto gratuito (dotenvx) | Suscripción de pago (desde ~$3/mes individual, ~$8/usuario/mes negocio) |
| Multiplataforma | macOS, Linux, Windows | Cualquier plataforma con Node.js / cualquier runtime (dotenvx) | macOS, Linux, Windows |
| Organización por contexto / entorno | Contextos (p. ej. `myapp.dev`, `stripe.prod`) | Archivos `.env` separados por entorno | Bóvedas y elementos |
| Ejecutar comandos con secretos | `envsec run` — interpolación de marcadores + variables de entorno `--inject` | `dotenvx run -- cmd` — inyecta desde `.env` cifrado | `op run -- cmd` — inyecta mediante referencias secretas |
| Exportar a archivo `.env` | `envsec env-file` (registrado para auditoría) | Formato nativo — los archivos `.env` son la fuente de verdad | `op inject --out-file` |
| Importar desde archivo `.env` | `envsec load` (con detección de conflictos) | N/D — `.env` es el almacén principal | Creación manual de elementos |
| Exportación de entorno de shell | `eval $(envsec env)` — bash, zsh, fish, powershell | `dotenvx run` o `node -r dotenv/config` | `op run --env-file` |
| Sesión de shell interactiva | `envsec shell` — sub-shell con ámbito y limpieza automática | No integrado | No integrado |
| Búsqueda de secretos | Patrones glob en claves y contextos | No integrado | Filtrado con `op item list --tags/--category` |
| Auditoría de caducidad / rotación | `envsec audit` — caducados, por caducar, archivos `.env` registrados | No integrado | Watchtower (en la app, no en CLI) |
| Comandos guardados | `envsec cmd` — guardar, listar, buscar, ejecutar, eliminar | No integrado | No integrado |
| Mover / copiar secretos | `envsec move` y `envsec copy` entre contextos | Copia manual de archivos | `op item move` entre bóvedas |
| Renombrar secretos | `envsec rename` (conserva valor y metadatos) | Edición manual del archivo `.env` | `op item edit` |
| Compartición cifrada con GPG | `envsec share --encrypt-to` | Archivos `.env` cifrados confirmados en git (dotenvx) | Compartición de bóvedas integrada, aprovisionamiento de equipos |
| TUI interactivo | `envsec tui` — interfaz de terminal a pantalla completa | No integrado | No integrado |
| Diagnóstico de salud | `envsec doctor` — comprueba plataforma, keychain, integridad de la BD | No integrado | No integrado |
| Completado de shell | Dinámico (contextos, claves, comandos) para bash, zsh, fish | No integrado | Completado estático para bash, zsh, fish, powershell |
| SDK / acceso programático | `@envsec/sdk` para Node.js / Bun | `require('dotenv').config()` — caso de uso principal | SDKs de 1Password (Node.js, Python, Go, etc.) |
| Equipo / multiusuario | Compartición GPG (manual) | Compartición basada en git con `.env` cifrado (dotenvx) | Gestión de equipos integrada, RBAC, registros de auditoría |
<!-- | Integración CI/CD | CLI estándar — funciona en cualquier lugar donde se ejecute Node.js | `dotenvx run` en cualquier pipeline de CI | Cuentas de servicio, integraciones nativas de CI/CD | -->
| Autenticación biométrica | Hereda la biometría del SO (p. ej. desbloqueo de Keychain en macOS) | Ninguna | Huella dactilar / Touch ID mediante integración de la app |
| Seguimiento de metadatos | SQLite (nombres de claves, marcas de tiempo — nunca valores) | Ninguno | Historial de elementos y registros de auditoría en la nube |
En resumen: dotenv es el enfoque más simple (archivos en disco), la CLI de 1Password es la más rica en funciones para equipos con sincronización en la nube y RBAC, y envsec se sitúa en medio — ofreciendo cifrado nativo del SO con cero cuentas, cero dependencias de la nube y un flujo de trabajo centrado en el desarrollador que va más allá de lo que los archivos `.env` pueden hacer.
## Cómo funciona
Los secretos se almacenan en el almacén de credenciales nativo del SO. El backend se selecciona automáticamente según la plataforma:
| SO | Backend | Herramienta / API |
|---------|--------------------------------|-------------------------------------|
| macOS | Keychain | CLI `security` |
| Linux | API Secret Service (D-Bus) | `secret-tool` (libsecret) |
| Windows | Credential Manager | `cmdkey` + PowerShell (advapi32) |
Los metadatos (nombres de claves, marcas de tiempo) se guardan en una base de datos SQLite en `~/.envsec/store.sqlite` (configurable mediante `--db` o `ENVSEC_DB`). Las claves deben contener al menos un separador de punto (p. ej., `service.account`), que se asigna a la estructura de servicio/cuenta del almacén de credenciales.
## Seguridad
envsec se construye sobre un principio simple: tus secretos pertenecen a tu SO, no a tus dotfiles. Cada decisión de diseño parte de esa base.
### Cómo protege envsec tus secretos
**Cifrado nativo del SO, cero criptografía personalizada.** Los valores de los secretos se almacenan directamente en Keychain de macOS, GNOME Keyring / KDE Wallet o Credential Manager de Windows. envsec nunca inventa su propio cifrado — delega en los almacenes de credenciales probados en batalla que tu sistema operativo ya proporciona, protegidos por tu sesión de usuario y (en macOS) el keychain de inicio de sesión.
**Soporte Unicode completo.** Los valores de los secretos pueden contener cualquier carácter Unicode, incluidos emojis y letras acentuadas. Los valores se codifican en base64 antes de almacenarse en el almacén de credenciales del SO, evitando peculiaridades de codificación específicas de la plataforma (p. ej. la CLI `security` de macOS codifica en hexadecimal la salida no ASCII). Los secretos heredados en texto plano se leen de forma transparente para compatibilidad hacia atrás.
**Los secretos nunca tocan el disco como texto plano.** Los valores van directamente desde tu terminal al almacén de credenciales del SO. Nunca se escriben en archivos de configuración, registros ni almacenamiento intermedio.
**Sin secretos en la salida del terminal.** Los comandos `list` y `search` muestran solo nombres de claves — los valores nunca se imprimen. Esto mantiene los secretos fuera de los buffers de scrollback, grabaciones de pantalla y el alcance de miradas indiscretas.
**Ejecución segura de comandos.** El comando `run` inyecta los secretos como variables de entorno del proceso hijo en lugar de interpolarlos en la cadena del comando. Esto significa que los valores de los secretos no aparecen en la salida de `ps` ni en el historial del shell. Si falta algún secreto referenciado, el comando se bloquea por completo — sin ejecución parcial con credenciales incompletas.
**Validación de entrada y prevención de inyección.** Los nombres de contexto se validan contra una lista de permitidos estricta (alfanuméricos, puntos, guiones, guiones bajos) con comprobaciones de path traversal y contaminación de prototipos. Todas las consultas SQLite usan sentencias preparadas con parámetros vinculados, lo que previene la inyección SQL. Los argumentos de PowerShell en Windows se escapan para protegerse contra la inyección de comandos.
**Permisos de archivo restrictivos.** El directorio de metadatos (`~/.envsec/`) se crea con permisos `0700` y la base de datos SQLite con `0600`, limitando el acceso al usuario propietario.
### Limitaciones conocidas y áreas de mejora
Creemos en ser transparentes sobre lo que envsec aún no cubre. Son compensaciones reales, no errores — y comprenderlas te ayuda a tomar decisiones informadas.
**Los metadatos son visibles.** La base de datos SQLite en `~/.envsec/store.sqlite` almacena nombres de claves, nombres de contexto y marcas de tiempo — nunca valores de secretos, pero suficiente para revelar *qué* secretos existen. Las plantillas de comandos guardados (con marcadores `{key}`) también se almacenan allí. Si la confidencialidad de los metadatos te importa, asegúrate de que tu directorio de inicio esté en un volumen cifrado.
**Las exportaciones de `env-file` son texto plano.** El comando `env-file` escribe valores de secretos en un archivo `.env` en disco. Esto es inherentemente sensible — trata el archivo de salida en consecuencia y nunca lo confirmes en control de versiones. Considéralo un puente de conveniencia, no un mecanismo de almacenamiento.
**La ejecución de shell conlleva riesgo inherente.** El comando `run` pasa tu plantilla de comando a través de `/bin/sh` (o `cmd.exe` en Windows). Si la plantilla proviene de entrada no confiable, es posible la inyección de shell. Solo ejecuta plantillas de comando que hayas escrito o en las que confíes.
**Sin control de acceso entre contextos.** Cualquier proceso que se ejecute como tu usuario del SO puede leer todos los secretos de todos los contextos. envsec depende del aislamiento de usuarios a nivel del SO — no añade su propia capa de autorización entre contextos.
**Entornos Linux sin interfaz gráfica.** En Linux, envsec depende de una sesión D-Bus activa y un demonio de keyring (p. ej. `gnome-keyring-daemon`). En contenedores o servidores sin sesión gráfica, el keyring puede no estar disponible o puede almacenar secretos con protección más débil.
**El cifrado depende de tu SO.** envsec no añade cifrado adicional en reposo más allá del que proporciona el almacén de credenciales nativo. En sistemas sin cifrado de disco completo, un atacante con acceso físico podría potencialmente extraer secretos del keychain. Recomendamos habilitar el cifrado de disco completo (FileVault, LUKS, BitLocker) para la protección más sólida.
## Desarrollo
### Requisitos previos
- Node.js >= 22
- pnpm
Los paquetes core, SDK, CLI y TUI usan Effect 4 y actualmente están fijados en
`4.0.0-rc.112`. Mantén las versiones de Effect y `@effect/platform-node` alineadas
en todo el workspace mientras Effect 4 permanezca en estado de candidato a versión final.
### Configuración```bash
git clone https://github.com/davidnussio/envsec.git
cd envsec
pnpm install
pnpm run build
packages/
cli/ → envsec CLI (published as envsec)
sdk/ → Node.js/Bun SDK (published as @envsec/sdk)
core/ → Core engine, shared by CLI and SDK (published as @envsec/core)
tui/ → Interactive terminal UI (published as @envsec/tui)
apps/
website/ → Documentation website
### Comandos comunes```bash
# Build all packages
pnpm run build
# Lint and format check (all packages)
pnpm run check
# Auto-fix lint and formatting
pnpm run fix
# Run package unit and contract tests
pnpm run test:unit
# Run the CLI end-to-end suite with isolated database and credential fixtures
pnpm --filter envsec test
# Release (build + changeset publish)
pnpm run release
El conjunto E2E aislado nunca accede al almacén de credenciales nativo. Para ejercitar
el adaptador real del sistema operativo en macOS o Linux, compila primero y opta explícitamente:```bash
ENVSEC_E2E_CLI="$PWD/packages/cli/dist/main.js"
ENVSEC_E2E_ISOLATED=0
pnpm --filter envsec test
Native E2E tests use dedicated `test.e2e*` contexts and remove them afterward.
### Ejecutar localmente sin instalar
Crea un alias temporal para usar la compilación local como si estuviera instalada globalmente:```bash
# Bash / Zsh
alias envsec="node $(pwd)/packages/cli/dist/main.js"
# Fish
alias envsec "node (pwd)/packages/cli/dist/main.js"
Después de compilar y configurar el alias, carga las completaciones en tu sesión actual:```bash
alias envsec="node $(pwd)/packages/cli/dist/main.js" eval "$(envsec --completions bash)"
alias envsec="node $(pwd)/packages/cli/dist/main.js" eval "$(envsec --completions zsh)"
alias envsec "node (pwd)/packages/cli/dist/main.js" envsec --completions fish | source
Luego presiona TAB después de `envsec -c ` para ver tus contextos, o después de `envsec -c myapp.dev get ` para ver las claves secretas.
### Ejecutar pruebas
Las pruebas de integración de extremo a extremo cubren todo el ciclo de vida de la CLI (add, get, list, search, env-file, load, delete, run, cmd, audit, share, completions).```bash
# Build first
pnpm run build
# macOS / Linux
bash packages/cli/test/e2e-test.sh
# Windows (PowerShell)
pwsh packages/cli/test/e2e-test.ps1
CI se ejecuta automáticamente en push/PR a main mediante GitHub Actions, ejecutando e2e-test.sh en macOS y Ubuntu, y e2e-test.ps1 en Windows.
MIT
| Paquete | Descripción | npm |
|---|
envsec | Herramienta CLI para gestionar secretos |  |
@envsec/sdk | SDK de Node.js / Bun para cargar secretos programáticamente |  |
@envsec/core | Motor principal: adaptadores de almacén de credenciales del SO + base de datos de metadatos |  |
@envsec/tui | Interfaz de terminal interactiva para la gestión de secretos |  |