Gere um .env.example seguro a partir do seu .env, automaticamente.

📖 Documentação completa · Changelog

EnvStencil

Sempre quando estamos desenvolvendo, é comum a gente criar um arquivo .env com as variáveis de ambiente necessárias e depois ter de gerar um arquivo .env.example para que outros desenvolvedores possam criar o seu próprio .env a partir dele.

O problema é que essa é uma tarefa muito chata e repetitiva, então o envstencil foi criado para automatizar esse processo.

Caso o arquivo .env contenha variáveis que não precisam ser sobrescritas no .env.example, você pode adicionar o comentário # envstencil:keep na linha da variável que deseja manter ou na linha anterior.

Instalação

pip — do PyPI ou direto do git:

pip install envstencil
pip install git+https://github.com/kylefelipe/env-stencil.git

Poetry — adiciona envstencil como dependência do seu projeto:

poetry add envstencil
poetry add git+https://github.com/kylefelipe/env-stencil.git

Com o repositório já clonado: pip install . (ou poetry install).

Uso

# Gera .env.example a partir de .env no diretório atual (ou dos arquivos da config)
envstencil generate

# Um argumento: FILE1 e FILE1 + ".example"
envstencil generate .env.production

# Dois argumentos: exatamente esses caminhos
envstencil generate .env.production .env.production.example

# -o / --output continua como alternativa para o segundo arquivo (não com FILE2)
envstencil generate .env.production -o custom.example

# Placeholder customizado
envstencil generate --placeholder "CHANGE_ME"

# Sobrescrever arquivo existente
envstencil generate --force

# Adiciona apenas variáveis ausentes ao .env.example existente
envstencil generate --append

# Verifica se .env e .env.example declaram as mesmas variáveis
envstencil check

# Compara dois arquivos dotenv quaisquer
envstencil check .env.production .env.production.example

# Lista as variáveis divergentes
envstencil check .env.production .env.production.example --diff

Configuração

Origem, destino, o comportamento do generate diante de um destino existente (behaviour) e o padrão de --diff podem vir de um arquivo TOML, então não é preciso repetir as flags a cada uso. As fontes, da menor para a maior precedência: defaults internos → config global do usuário (~/.config/envstencil/config.toml) → [tool.envstencil] do pyproject.toml → .envstencil.toml → arquivo de --config → argumentos e flags da linha de comando (que sempre vencem).

O pyproject.toml e o .envstencil.toml são procurados a partir do diretório atual e depois nos diretórios pais até a raiz, de forma independente — rodar o envstencil num subdiretório do projeto ainda encontra os arquivos da raiz. Só a ocorrência mais próxima de cada nome é usada; arquivos ancestrais não são empilhados.

# .envstencil.toml
[global]
file1 = ".env.local"
file2 = ".env.local.example"

[generate]
behaviour = "force"   # "fail" (padrão) | "force" | "append"

[check]
diff = true

Na linha de comando, --force e --append são overrides explícitos do behaviour (vencem a configuração), e --diff / --no-diff fazem o mesmo com [check].diff. Não existe --behaviour nem --fail: por enquanto não há flag para voltar a fail quando a configuração pede force/append. Detalhes e exemplos: Modo de uso → Configuração.

Exemplo

Entrada (.env):

# Banco de dados
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
STRIPE_SECRET_KEY=sk_live_abc123

Saída (.env.example):

# Banco de dados
DATABASE_URL=your_value_here
STRIPE_SECRET_KEY=your_value_here

Desenvolvimento

Requer Poetry 2.0+. Os grupos dev e doc são opcionais — poetry install sozinho instala só o runtime:

poetry install --with dev,doc

Tarefas, convenções e fluxo de PR: Contribuindo.