davidnussio/envsecSecure CLI tool for managing environment secrets using native OS credential stores (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)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 via cmdkey and PowerShell.
brew tap davidnussio/homebrew-tap
brew install envsec
npm install -g envsec
npx envsec
mise use -g npm: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), y (years)
# 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.
<old-key> — Current secret key name<new-key> — New secret key name--force, -f — Overwrite target if it already exists# 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
List all secret keys and metadata in a context.
--json — Output in JSON formatenvsec -c myapp.dev list
List all available contexts with secret counts.
--json — Output in JSON format# Without --context, lists all available contexts with secret counts
envsec list
Search secrets or contexts using glob patterns.
<pattern> — Glob pattern to search for (e.g. api.*, myapp.*)--json — Output in JSON format# Search secrets within a context
envsec -c myapp.dev search "api.*"
# Search contexts by pattern (without --context)
envsec search "myapp.*"
Move secrets from one context to another. The source secrets are removed after moving.
<pattern> — Glob pattern or exact key to move (optional if --all is used)--to, -t — Target context to move secrets to--all — Move all secrets from source context--force, -f — Overwrite existing secrets in the target context--yes, -y — Skip confirmation prompt# Move a single secret
envsec -c myapp.dev move api.token --to myapp.prod