envsec

Gestión segura de secretos de entorno utilizando los almacenes de credenciales nativos del sistema operativo.

Demo

Características

• Almacena secretos en el almacén de credenciales nativo de tu sistema operativo (no en archivos de texto plano)
• Multiplataforma: macOS, Linux, Windows
• Organiza secretos por contexto (p. ej. myapp.dev, stripe-api.prod, work.staging)
• Rastrea metadatos de secretos (nombres de claves, marcas de tiempo) mediante SQLite
• Busca contextos y secretos con patrones glob
• Ejecuta comandos con interpolación de secretos
• Guarda y vuelve a ejecutar comandos con cmd (search, list, run, delete)
• Exporta secretos a archivos .env (con seguimiento de generación mediante audit)
• Exporta secretos como variables de entorno del shell (eval $(envsec env))
• Carga secretos desde archivos .env (con detección de conflictos)
• Comparte secretos cifrados con GPG para miembros del equipo
• Interfaz de terminal interactiva (envsec tui) para gestionar secretos sin memorizar comandos

Paquetes

Este es un monorepo que contiene los siguientes paquetes:

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 del almacén de credenciales del SO + base de datos de metadatos
@envsec/tui	Interfaz de terminal interactiva para la gestión de secretos

Inicio rápido del SDK

Para acceder programáticamente a los secretos desde Node.js o Bun, utiliza @envsec/sdk:

npm install @envsec/sdk

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.

Requisitos

• Node.js >= 22

macOS

Sin dependencias adicionales. Utiliza el Keychain integrado a través de la herramienta CLI security.

Linux

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.

# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

Debe haber una sesión de D-Bus en ejecución y un demonio de keyring (p. ej. gnome-keyring-daemon) activo. 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)

brew tap davidnussio/homebrew-tap
brew install envsec

npm

npm install -g envsec

npx (sin instalación)

npx envsec

mise

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 formato libre para agrupar secretos — por ejemplo, myapp.dev, stripe-api.prod, work.staging.

Opciones globales

Estas opciones están disponibles en todos los comandos:

• --context, -c — Nombre del contexto (por ejemplo, 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:

# 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.

Añadir un secreto

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)

# Store a value inline
envsec -c myapp.dev add api.key --value "sk-abc123"

# Or use the short alias
envsec -c myapp.dev add api.key -v "sk-abc123"

# Omit --value for an interactive masked prompt
envsec -c myapp.dev add api.key

# Set an expiry duration with --expires (-e)
envsec -c myapp.dev add api.key -v "sk-abc123" --expires 30d

# Supported duration units: m (minutes), h (hours), d (days), w (weeks), mo (months), y (years)
# Combinable: 1y6mo, 2w3d, 1d12h
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo

Obtener un secreto

Recupera un valor secreto del almacén de credenciales del sistema operativo.

• <key> — Nombre de la clave secreta a recuperar
• --quiet, -q — Imprime solo el valor sin procesar (sin advertencias ni salida adicional)
• --json — Salida en formato JSON (incluye contexto, clave, valor, expires_at)

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

Eliminar un secreto

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 el aviso de confirmación
• --all — Eliminar todos los secretos en el contexto

envsec -c myapp.dev delete api.key

# or use the alias
envsec -c myapp.dev del api.key

Renombrar un secreto

Renombra una clave de secreto dentro del mismo contexto. El valor y los metadatos de expiración se conservan.

• <old-key> — Nombre actual de la clave del secreto
• <new-key> — Nuevo nombre de la clave del secreto
• --force, -f — Sobrescribir el destino si ya existe

# 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

Listar todos los secretos en un contexto

Listar todas las claves de secretos y metadatos en un contexto.

• --json — Salida en formato JSON

envsec -c myapp.dev list

Listar todos los contextos

Lista todos los contextos disponibles con el recuento de secretos.

• --json — Salida en formato JSON