envsec

Gestione sicura dei segreti d'ambiente utilizzando gli archivi di credenziali nativi del sistema operativo.

Demo

Funzionalità

• Memorizza i segreti nell'archivio di credenziali nativo del tuo sistema operativo (non in file di testo in chiaro)
• Multipiattaforma: macOS, Linux, Windows
• Organizza i segreti per contesto (ad es. myapp.dev, stripe-api.prod, work.staging)
• Traccia i metadati dei segreti (nomi delle chiavi, timestamp) tramite SQLite
• Cerca contesti e segreti con pattern glob
• Esegui comandi con interpolazione dei segreti
• Salva e riesegui comandi con cmd (search, list, run, delete)
• Esporta i segreti in file .env (con tracciamento della generazione tramite audit)
• Esporta i segreti come variabili d'ambiente della shell (eval $(envsec env))
• Carica i segreti da file .env (con rilevamento dei conflitti)
• Condividi i segreti crittografati con GPG per i membri del team
• Interfaccia terminale interattiva (envsec tui) per gestire i segreti senza memorizzare i comandi

Pacchetti

Questo è un monorepo contenente i seguenti pacchetti:

Pacchetto	Descrizione	npm
envsec	Strumento CLI per la gestione dei segreti
@envsec/sdk	SDK Node.js / Bun per caricare i segreti a livello di programmazione
@envsec/core	Motore principale — adattatori per l'archivio di credenziali del sistema operativo + database dei metadati
@envsec/tui	Interfaccia terminale interattiva per la gestione dei segreti

Avvio rapido dell'SDK

Per l'accesso programmatico ai segreti da Node.js o Bun, usa @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();

Consulta la documentazione completa dell'SDK per tutte le API, il supporto multi-contesto e le opzioni.

Requisiti

• Node.js >= 22

macOS

Nessuna dipendenza aggiuntiva. Utilizza il Keychain integrato tramite lo strumento CLI security.

Linux

Richiede libsecret-tools (fornisce il comando secret-tool), che comunica con GNOME Keyring, KDE Wallet o qualsiasi provider dell'API Secret Service tramite D-Bus.

# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

Una sessione D-Bus in esecuzione e un daemon keyring (ad es. gnome-keyring-daemon) devono essere attivi. La maggior parte degli ambienti desktop lo gestisce automaticamente.

Windows

Nessuna dipendenza aggiuntiva. Utilizza il Windows Credential Manager integrato tramite cmdkey e PowerShell.

Installazione

Homebrew (macOS / Linux)

brew tap davidnussio/homebrew-tap
brew install envsec

npm

npm install -g envsec

npx (senza installazione)

npx envsec

mise

mise use -g npm:envsec

Utilizzo

La maggior parte dei comandi richiede un contesto specificato con --context (o -c). Un contesto è un'etichetta libera per raggruppare i segreti — ad esempio myapp.dev, stripe-api.prod, work.staging.

Opzioni globali

Queste opzioni sono disponibili su tutti i comandi:

• --context, -c — Nome del contesto (ad esempio myapp.dev, stripe-api.prod). Legge anche la variabile d'ambiente ENVSEC_CONTEXT
• --debug, -d — Abilita il logging di debug
• --json — Output in formato JSON per scripting
• --db — Percorso del file di database SQLite (predefinito: ~/.envsec/store.sqlite). Legge anche la variabile d'ambiente ENVSEC_DB

Percorso personalizzato del database

Per impostazione predefinita, i metadati sono memorizzati in ~/.envsec/store.sqlite. È possibile sovrascrivere questo percorso con --db o la variabile d'ambiente ENVSEC_DB:

# 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

Il flag --db ha la precedenza su ENVSEC_DB. I casi d'uso includono database per progetto, database condivisi dal team su unità di rete e CI/CD con storage effimero.

Aggiungere un segreto

Archivia un segreto nell'archivio delle credenziali del sistema operativo.

• <key> — Nome della chiave del segreto (es. api.key, db.password)
• --value, -v — Valore da archiviare (omettere per un prompt interattivo mascherato)
• --expires, -e — Durata di scadenza (es. 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

Ottenere un segreto

Recupera un valore segreto dall'archivio delle credenziali del sistema operativo.

• <key> — Nome della chiave segreta da recuperare
• --quiet, -q — Stampa solo il valore grezzo (nessun avviso o output aggiuntivo)
• --json — Output in formato JSON (include contesto, chiave, valore, 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

Elimina un segreto

Rimuovi un segreto dall'archivio delle credenziali del sistema operativo.

• <key> — Nome della chiave del segreto da eliminare (opzionale se viene usato --all)
• --yes, -y — Salta la richiesta di conferma
• --all — Elimina tutti i segreti nel contesto

envsec -c myapp.dev delete api.key

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

Rinominare un segreto

Rinomina una chiave segreta all'interno dello stesso contesto. Il valore e i metadati di scadenza vengono preservati.

• <old-key> — Nome attuale della chiave segreta
• <new-key> — Nuovo nome della chiave segreta
• --force, -f — Sovrascrive la destinazione se esiste già

# 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

Elenca tutti i secret in un contesto

Elenca tutte le chiavi dei secret e i metadati in un contesto.

• --json — Output in formato JSON

envsec -c myapp.dev list

Elenca tutti i contesti

Elenca tutti i contesti disponibili con il conteggio dei segreti.

• --json — Output in formato JSON