envsec

Sichere Verwaltung von Umgebungsgeheimnissen unter Verwendung nativer Betriebssystem-Anmeldeinformationsspeicher.

Demo

Funktionen

• Geheimnisse im nativen Anmeldeinformationsspeicher Ihres Betriebssystems speichern (nicht in Klartextdateien)
• Plattformübergreifend: macOS, Linux, Windows
• Geheimnisse nach Kontext organisieren (z. B. myapp.dev, stripe-api.prod, work.staging)
• Metadaten von Geheimnissen verfolgen (Schlüsselnamen, Zeitstempel) über SQLite
• Kontexte und Geheimnisse mit Glob-Mustern durchsuchen
• Befehle mit Geheimnis-Interpolation ausführen
• Befehle mit cmd speichern und erneut ausführen (suchen, auflisten, ausführen, löschen)
• Geheimnisse in .env-Dateien exportieren (mit Generierungsverfolgung über audit)
• Geheimnisse als Shell-Umgebungsvariablen exportieren (eval $(envsec env))
• Geheimnisse aus .env-Dateien laden (mit Konflikterkennung)
• Geheimnisse verschlüsselt mit GPG für Teammitglieder teilen
• Interaktive Terminal-Benutzeroberfläche (envsec tui) zur Verwaltung von Geheimnissen, ohne Befehle auswendig lernen zu müssen

Pakete

Dies ist ein Monorepo, das die folgenden Pakete enthält:

Paket	Beschreibung	npm
envsec	CLI-Tool zur Verwaltung von Geheimnissen
@envsec/sdk	Node.js / Bun SDK zum programmatischen Laden von Geheimnissen
@envsec/core	Kern-Engine — Adapter für Betriebssystem-Anmeldeinformationsspeicher + Metadaten-DB
@envsec/tui	Interaktive Terminal-Benutzeroberfläche zur Verwaltung von Geheimnissen

SDK-Schnellstart

Für den programmatischen Zugriff auf Geheimnisse von Node.js oder Bun aus verwenden Sie @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();

Siehe die vollständige SDK-Dokumentation für alle APIs, Multi-Context-Unterstützung und Optionen.

Anforderungen

• Node.js >= 22

macOS

Keine zusätzlichen Abhängigkeiten. Verwendet den integrierten Keychain über das security CLI-Tool.

Linux

Erfordert libsecret-tools (stellt den Befehl secret-tool bereit), das über D-Bus mit GNOME Keyring, KDE Wallet oder einem beliebigen Secret Service API-Anbieter kommuniziert.

# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

Eine laufende D-Bus-Sitzung und ein Keyring-Daemon (z. B. gnome-keyring-daemon) müssen aktiv sein. Die meisten Desktop-Umgebungen erledigen dies automatisch.

Windows

Keine zusätzlichen Abhängigkeiten. Verwendet den integrierten Windows Credential Manager über cmdkey und PowerShell.

Installation

Homebrew (macOS / Linux)

brew tap davidnussio/homebrew-tap
brew install envsec

npm

npm install -g envsec

npx (ohne Installation)

npx envsec

mise

mise use -g npm:envsec

Verwendung

Die meisten Befehle erfordern einen Kontext, der mit --context (oder -c) angegeben wird. Ein Kontext ist ein frei wählbares Label zur Gruppierung von Secrets — z. B. myapp.dev, stripe-api.prod, work.staging.

Globale Optionen

Diese Optionen sind für alle Befehle verfügbar:

• --context, -c — Kontextname (z. B. myapp.dev, stripe-api.prod). Liest auch die Umgebungsvariable ENVSEC_CONTEXT
• --debug, -d — Debug-Logging aktivieren
• --json — Ausgabe im JSON-Format für Skripting
• --db — Pfad zur SQLite-Datenbankdatei (Standard: ~/.envsec/store.sqlite). Liest auch die Umgebungsvariable ENVSEC_DB

Benutzerdefinierter Datenbankpfad

Standardmäßig werden Metadaten unter ~/.envsec/store.sqlite gespeichert. Sie können dies mit --db oder der Umgebungsvariable ENVSEC_DB überschreiben:

# 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

Das Flag --db hat Vorrang vor ENVSEC_DB. Anwendungsfälle umfassen projektspezifische Datenbanken, teamübergreifend genutzte Datenbanken auf Netzwerklaufwerken und CI/CD mit kurzlebigem Speicher.

Ein Secret hinzufügen

Speichern Sie ein Secret im Betriebssystem-Anmeldeinformationsspeicher.

• <key> — Name des Secret-Schlüssels (z. B. api.key, db.password)
• --value, -v — Zu speichernder Wert (weglassen für interaktive maskierte Eingabeaufforderung)
• --expires, -e — Ablaufdauer (z. B. 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

Ein Secret abrufen

Ruft einen Secret-Wert aus dem OS-Credential-Store ab.

• <key> — Name des abzurufenden Secret-Schlüssels
• --quiet, -q — Gibt nur den Rohwert aus (keine Warnungen oder zusätzliche Ausgabe)
• --json — Ausgabe im JSON-Format (enthält 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

Ein Secret löschen

Ein Secret aus dem OS-Credential-Store entfernen.

• <key> — Name des zu löschenden Secret-Keys (optional, wenn --all verwendet wird)
• --yes, -y — Bestätigungsaufforderung überspringen
• --all — Alle Secrets im Kontext löschen

envsec -c myapp.dev delete api.key

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

Ein Secret umbenennen

Benennt einen Secret-Schlüssel innerhalb desselben Kontexts um. Der Wert und die Ablauf-Metadaten bleiben erhalten.

• <old-key> — Aktueller Name des Secret-Schlüssels
• <new-key> — Neuer Name des Secret-Schlüssels
• --force, -f — Ziel überschreiben, falls es bereits existiert

# 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

Alle Secrets in einem Kontext auflisten

Alle Secret-Schlüssel und Metadaten in einem Kontext auflisten.

• --json — Ausgabe im JSON-Format

envsec -c myapp.dev list

Alle Kontexte auflisten

Listet alle verfügbaren Kontexte mit Geheimnisanzahl auf.

• --json — Ausgabe im JSON-Format