envsec

Secure environment secrets management using native OS credential stores.

Demo

Features

• Store secrets in your OS native credential store (not plain text files)
• Cross-platform: macOS, Linux, Windows
• Organize secrets by context (e.g. myapp.dev, stripe-api.prod, work.staging)
• Track secret metadata (key names, timestamps) via SQLite
• Search contexts and secrets with glob patterns
• Run commands with secret interpolation
• Save and rerun commands with cmd (search, list, run, delete)
• Export secrets to .env files (with generation tracking via audit)
• Export secrets as shell environment variables (eval "$(envsec env)")
• Load secrets from .env files (with conflict detection)
• Rescue every plaintext .env file in a directory tree into the keychain (envsec rescue ~/projects --import)
• Share secrets encrypted with GPG for team members
• Interactive terminal UI (envsec tui) for managing secrets without memorizing commands

Packages

This 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

SDK Quick Start

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.

Requirements

• Node.js >= 22.13 — only for npm, npx and mise installs. Homebrew and the standalone binaries embed their own runtime.

macOS

No extra dependencies. Uses the built-in Keychain via the security CLI tool.

Linux

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.

Windows

No extra dependencies. Uses the built-in Windows Credential Manager, calling the Win32 CredWriteW / CredReadW / CredDeleteW APIs from PowerShell (P/Invoke).

Installation

Homebrew (macOS / Linux)

Installs the standalone binary (no Node.js), with shell completions for bash, zsh and fish.

brew tap davidnussio/homebrew-tap
brew install envsec

npm

npm install -g envsec

npx (no install)

npx envsec

mise

mise use -g npm:envsec

Standalone binary (no Node.js)

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.

Beta channel

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.

Usage

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.

Global options

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 var

Custom database path

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

Add a secret

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

Get a secret

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

Delete a secret

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 context

envsec -c myapp.dev delete api.key

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

Rename a secret

Rename a secret key within the same context. The value and expiry metadata are preserved.