davidnussio/envsecStrumento CLI sicuro per la gestione dei segreti di ambiente utilizzando i depositi di credenziali nativi del sistema operativo (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.