envsec

Gerenciamento seguro de segredos de ambiente usando armazenamentos de credenciais nativos do sistema operacional.

Demonstração

Recursos

• Armazene segredos no armazenamento de credenciais nativo do seu sistema operacional (não em arquivos de texto simples)
• Multiplataforma: macOS, Linux, Windows
• Organize segredos por contexto (ex.: myapp.dev, stripe-api.prod, work.staging)
• Rastreie metadados de segredos (nomes de chaves, timestamps) via SQLite
• Pesquise contextos e segredos com padrões glob
• Execute comandos com interpolação de segredos
• Salve e reexecute comandos com cmd (pesquisar, listar, executar, excluir)
• Exporte segredos para arquivos .env (com rastreamento de geração via audit)
• Exporte segredos como variáveis de ambiente do shell (eval $(envsec env))
• Carregue segredos de arquivos .env (com detecção de conflitos)
• Compartilhe segredos criptografados com GPG para membros da equipe
• Interface de terminal interativa (envsec tui) para gerenciar segredos sem memorizar comandos

Pacotes

Este é um monorepo contendo os seguintes pacotes:

Pacote	Descrição	npm
envsec	Ferramenta CLI para gerenciar segredos
@envsec/sdk	SDK Node.js / Bun para carregar segredos programaticamente
@envsec/core	Motor principal — adaptadores de armazenamento de credenciais do SO + banco de dados de metadados
@envsec/tui	Interface de terminal interativa para gerenciamento de segredos

Início Rápido do SDK

Para acesso programático a segredos a partir do Node.js ou 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();

Consulte a documentação completa do SDK para todas as APIs, suporte a múltiplos contextos e opções.

Requisitos

• Node.js >= 22

macOS

Sem dependências extra. Utiliza o Keychain integrado através da ferramenta CLI security.

Linux

Requer libsecret-tools (fornece o comando secret-tool), que comunica com o GNOME Keyring, KDE Wallet ou qualquer fornecedor da Secret Service API via D-Bus.

# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

Uma sessão D-Bus em execução e um daemon de keyring (por exemplo, gnome-keyring-daemon) devem estar ativos. A maioria dos ambientes de desktop faz isso automaticamente.

Windows

Sem dependências extras. Usa o Gerenciador de Credenciais integrado do Windows via cmdkey e PowerShell.

Instalação

Homebrew (macOS / Linux)

brew tap davidnussio/homebrew-tap
brew install envsec

npm

npm install -g envsec

npx (sem instalação)

npx envsec

mise

mise use -g npm:envsec

Uso

A maioria dos comandos requer um contexto especificado com --context (ou -c). Um contexto é um rótulo de formato livre para agrupar segredos — por exemplo, myapp.dev, stripe-api.prod, work.staging.

Opções globais

Estas opções estão disponíveis em todos os comandos:

• --context, -c — Nome do contexto (por exemplo, myapp.dev, stripe-api.prod). Também lê a variável de ambiente ENVSEC_CONTEXT
• --debug, -d — Ativa o registro de depuração
• --json — Saída em formato JSON para scripts
• --db — Caminho para o arquivo de banco de dados SQLite (padrão: ~/.envsec/store.sqlite). Também lê a variável de ambiente ENVSEC_DB

Caminho de banco de dados personalizado

Por padrão, os metadados são armazenados em ~/.envsec/store.sqlite. Você pode substituir isso com --db ou a variável de 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

O flag --db tem precedência sobre ENVSEC_DB. Os casos de uso incluem bases de dados por projeto, bases de dados partilhadas por equipas em unidades de rede e CI/CD com armazenamento efémero.

Adicionar um segredo

Armazenar um segredo no armazenamento de credenciais do SO.

• <key> — Nome da chave do segredo (por exemplo, api.key, db.password)
• --value, -v — Valor a armazenar (omitir para prompt interativo mascarado)
• --expires, -e — Duração de expiração (por exemplo, 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

Obter um segredo

Recupera um valor de segredo do armazenamento de credenciais do SO.

• <key> — Nome da chave do segredo a recuperar
• --quiet, -q — Imprime apenas o valor bruto (sem avisos ou saída extra)
• --json — Saída em formato JSON (inclui contexto, chave, valor, 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

Excluir um segredo

Remova um segredo do armazenamento de credenciais do SO.

• <key> — Nome da chave do segredo a excluir (opcional se --all for usado)
• --yes, -y — Pular o prompt de confirmação
• --all — Excluir todos os segredos no contexto

envsec -c myapp.dev delete api.key

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

Renomear um segredo

Renomeia uma chave de segredo dentro do mesmo contexto. O valor e os metadados de expiração são preservados.

• <old-key> — Nome atual da chave do segredo
• <new-key> — Novo nome da chave do segredo
• --force, -f — Sobrescrever o destino se ele já existir

# 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

Listar todos os segredos em um contexto

Listar todas as chaves de segredos e metadados em um contexto.

• --json — Saída em formato JSON

envsec -c myapp.dev list

Listar todos os contextos

Liste todos os contextos disponíveis com contagens de segredos.

• --json — Saída em formato JSON

# Without --context, lists all available contexts with secret counts
envsec list

Pesquisar segredos

Pesquise segredos ou contextos usando padrões glob.