davidnussio/envsecHerramienta CLI segura para gestionar secretos de entorno utilizando almacenes de credenciales nativos del SO (macOS Keychain, Linux Secret Service, Windows Credential Manager)
Secure environment secrets management using native OS credential stores.
myapp.dev, stripe-api.prod, work.staging)cmd (search, list, run, delete).env files (with generation tracking via audit)eval "$(envsec env)").env files (with conflict detection).env file in a directory tree into the keychain (envsec rescue ~/projects --import)envsec tui) for managing secrets without memorizing commandsThis is a monorepo containing the following packages:
| Package | Description | npm |
|---|---|---|
envsec | CLI tool for managing secrets |  |
@envsec/sdk | Node.js / Bun SDK for loading secrets programmatically |  |
@envsec/core | Core engine — OS credential store adapters + metadata DB |  |
@envsec/tui | Interactive terminal UI for secrets management |  |
For programmatic access to secrets from Node.js or Bun, use @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();
See the full SDK documentation for all APIs, multi-context support, and options.
No extra dependencies. Uses the built-in Keychain via the security CLI tool.
Requires libsecret-tools (provides the secret-tool command), which talks to GNOME Keyring, KDE Wallet, or any Secret Service API provider via D-Bus.
# Debian / Ubuntu
sudo apt install libsecret-tools
# Fedora
sudo dnf install libsecret
# Arch
sudo pacman -S libsecret
A running D-Bus session and a keyring daemon (e.g. gnome-keyring-daemon) must be active. Most desktop environments handle this automatically.
No extra dependencies. Uses the built-in Windows Credential Manager, calling the Win32 CredWriteW / CredReadW / CredDeleteW APIs from PowerShell (P/Invoke).
Installs the standalone binary (no Node.js), with shell completions for bash, zsh and fish.
brew tap davidnussio/homebrew-tap
brew install envsec
npm install -g envsec
npx envsec
mise use -g npm:envsec
Every GitHub release ships self-contained executables for macOS (arm64, x64), Linux (x64, arm64, glibc and musl) and Windows (x64), plus a SHA256SUMS file:
TARGET=darwin-arm64 # or darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl
curl -fsSL "https://github.com/davidnussio/envsec/releases/latest/download/envsec-${TARGET}.tar.gz" | tar -xz envsec
sudo mv envsec /usr/local/bin/
On Windows, download envsec-windows-x64.zip and put envsec.exe on your PATH.
Prereleases (vX.Y.Z-beta.N) are published on npm under the beta dist-tag and on Homebrew as a separate envsec-beta formula. It conflicts with envsec, since both install the envsec command:
npm install -g envsec@beta
brew uninstall envsec # if the stable formula is installed
brew install davidnussio/tap/envsec-beta
Go back to stable with npm install -g envsec@latest, or brew uninstall envsec-beta && brew install envsec.
Most commands require a context specified with --context (or -c). A context is a free-form label for grouping secrets — e.g. myapp.dev, stripe-api.prod, work.staging.
These options are available on all commands:
--context, -c — Context name (e.g. myapp.dev, stripe-api.prod). Also reads ENVSEC_CONTEXT env var--debug, -d — Enable debug logging--json — Output in JSON format for scripting--db — Path to SQLite database file (default: ~/.envsec/store.sqlite). Also reads ENVSEC_DB env varBy default, metadata is stored at ~/.envsec/store.sqlite. You can override this with --db or the ENVSEC_DB environment variable:
# 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
The --db flag takes precedence over ENVSEC_DB. Use cases include per-project databases, team-shared databases on network drives, and CI/CD with ephemeral storage.
Store a secret in the OS credential store.
<key> — Secret key name (e.g. api.key, db.password)--value, -v — Value to store (omit for interactive masked prompt)--expires, -e — Expiry duration (e.g. 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, counted as 30 days), y (years, counted as 365 days)
# Combinable: 1y6mo, 2w3d, 1d12h
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo
Retrieve a secret value from the OS credential store.
<key> — Secret key name to retrieve--quiet, -q — Print only the raw value (no warnings or extra output)--json — Output in JSON format (includes context, key, value, 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
Remove a secret from the OS credential store.
<key> — Secret key name to delete (optional if --all is used)--yes, -y — Skip confirmation prompt--all — Delete all secrets in the contextenvsec -c myapp.dev delete api.key
# or use the alias
envsec -c myapp.dev del api.key
Rename a secret key within the same context. The value and expiry metadata are preserved.