Keep your .env files honest.
A lightweight CLI tool that checks missing, undocumented, and empty environment variables, syncs local files from examples, scans YAML and properties config for env placeholders, audits git history for leaked secrets, and encrypts/decrypts env files for safer team sharing.
Every project has a .env.example committed to git and a real .env that's gitignored. This breaks in three ways:
- A new dev clones the repo and has no idea which keys are missing
- Someone adds a new key to
.envbut forgets to update.env.example - A key exists but is empty — and nobody notices until production
envguard catches all of this, and helps you recover when it doesn't.
With Homebrew:
brew tap BLemine/tap
brew install BLemine/tap/envguard
envguard --helpWith Go (Go 1.25 or newer):
go install github.com/BLemine/envguard@v1.0.0Use @latest instead to install the latest release. The executable is installed
in GOBIN, or $(go env GOPATH)/bin when GOBIN is unset; add that directory
to your PATH if envguard is not found.
Pre-built binaries require no Go installation. Download the matching asset from the v1.0.0 release:
| Platform | Asset |
|---|---|
| macOS Apple Silicon | envguard-darwin-arm64 |
| macOS Intel | envguard-darwin-amd64 |
| Linux x86-64 | envguard-linux-amd64 |
| Windows x86-64 | envguard-windows-amd64.exe |
For example, install the Linux x86-64 binary into your user account:
curl -fL https://github.com/BLemine/envguard/releases/download/v1.0.0/envguard-linux-amd64 -o envguard
chmod +x envguard
mkdir -p "$HOME/.local/bin"
mv envguard "$HOME/.local/bin/envguard"
export PATH="$HOME/.local/bin:$PATH"
envguard --helpOn macOS, substitute the matching asset name in the download URL. On Windows,
rename the downloaded file to envguard.exe and put it in a directory on PATH,
or run it directly as .\envguard.exe --help in PowerShell.
Git must be installed and available on PATH to use audit.
From a project directory containing .env.example:
envguard sync
# Fill in the empty values added to .env, then:
envguard checkPaths are relative to the current working directory. check and validate
read .env by default; they do not validate the current process environment.
Use envguard <command> --help to inspect that command's flags.
envguard checkComparing .env.example → .env
✓ DATABASE_URL ok
✓ JWT_SECRET ok
✗ STRIPE_SECRET_KEY missing from .env
✗ REDIS_URL missing from .env
⚠ DEBUG_MODE in .env but not in .env.example
Summary
✓ 2 ok
✗ 2 missing
⚠ 1 undocumented
✗ Check failed — fix missing or empty keys before continuing
check exits with code 1 for missing or empty keys. Undocumented keys produce
warnings only and do not fail the check. Both input files must exist.
Custom paths:
envguard check --example=.env.staging.example --local=.env.stagingAdds missing keys from .env.example into your .env with empty values. Existing keys are never overwritten.
If the target file does not exist yet and keys need adding, envguard creates it for you.
It appends empty assignments, preserving existing values and comments; it does
not copy example values or fill keys that already exist but are empty.
Use --example=.env.staging.example --local=.env.staging for custom paths.
envguard syncSync result
+ STRIPE_SECRET_KEY added (empty value)
+ REDIS_URL added (empty value)
~ DATABASE_URL already exists, skipped
Encrypts your .env into a .env.enc file using AES-256-GCM with a key derived from your passphrase via Argon2id. envguard does not save the passphrase. Existing output files are overwritten without a --force flag; choose a different --out path to keep an earlier encrypted copy.
# Bash: read without echoing or placing the passphrase in shell history.
read -r -s -p "Passphrase: " ENVGUARD_PASSPHRASE
printf '\n'
export ENVGUARD_PASSPHRASE
envguard encrypt
unset ENVGUARD_PASSPHRASEAvoid passing secrets directly on the command line if you can, since shell history and process inspection may expose them. Prefer CI secret injection or a shell prompt that exports ENVGUARD_PASSPHRASE only for the current session.
✓ .env encrypted → .env.enc (share this with your team)
Custom paths:
envguard encrypt --local=.env.staging --out=.env.staging.enc --passphrase=mysecretIn CI, inject a stored secret as ENVGUARD_PASSPHRASE rather than writing its
value into the workflow. A non-empty --passphrase takes precedence over the
environment variable. Encryption and decryption fail if neither supplies a passphrase.
Decrypts a .env.enc back into .env. Fails loudly if the passphrase is wrong. Will not overwrite an existing .env unless --force is passed. On Unix, decrypted output is restricted to owner read/write (0600), including when overwriting an existing file.
envguard decrypt --passphrase=mysecret✓ .env.enc decrypted → .env
Custom paths or force overwrite:
envguard decrypt --local=.env.staging.enc --out=.env.staging --passphrase=mysecret
envguard decrypt --passphrase=mysecret --forceNote: This repository ignores
*.enc. Installing envguard does not change another project's.gitignore; configure that project explicitly. Share the passphrase separately from the encrypted file. Decryption also rejects corrupted ciphertext before writing output.
Perfect for CI pipelines. Exits with code 1 if any required key is missing or empty.
envguard validate --required=DATABASE_URL,API_KEY,JWT_SECRET ✓ DATABASE_URL set
✓ JWT_SECRET set
✗ API_KEY missing or empty
✗ Validation failed — 1 required key(s) missing or empty
Use --local=.env.staging to validate another file. Validation checks for
missing keys or the empty string; it does not validate formats, credentials,
or whitespace-only values. Setting a key through GitHub Actions env: alone
does not put it into the file. See GitHub Actions for CI setup.
Walks history reachable from all local refs, including merge commits, and flags committed .env files plus lines matching common secret patterns such as API keys, tokens, passwords, private keys, Slack tokens, GitHub tokens, and Stripe keys.
envguard auditCustom repository path:
envguard audit --repo /path/to/other/repoExample output:
Audit: scanning git history for secrets and .env files
.env Files Committed to History
⚠ e92d843 .env
Secret Patterns Detected
✗ e92d843 .env Generic API Key
API_KEY=[REDACTED]
Summary
⚠ 1 .env file(s) found in history
✗ 1 secret pattern(s) detected
✗ Audit failed — sensitive data may be exposed in git history
Tip: use `git filter-repo` or BFG Repo Cleaner to scrub history
audit exits with code 1 when it finds leaked env files or matching secret patterns, which makes it suitable for CI or pre-release checks without dumping the secret value into logs.
The audit uses a finite set of patterns and can produce false positives or miss
secrets. It scans committed additions, including merge diffs, in history
reachable from local refs; it does not fetch remote refs or inspect uncommitted
files. Shallow clones limit the history available to it. Template filenames
ending in .example, .sample, or .template are excluded from the env-file
check, but their contents still undergo pattern matching. A clean audit is not
a guarantee that the repository contains no secrets. Rotate exposed credentials;
removing them from history does not revoke them.
Extracts ${VAR} and ${VAR:default} placeholders from YAML and .properties config files.
Required variables (no default) and optional variables (with default) are reported separately.
All YAML documents (including sections separated by ---) are scanned. Properties
accept =, :, or whitespace separators. Nested fallback expressions are supported, including deeper chains:
database.url=${DATABASE_URL:${FALLBACK_DATABASE_URL}}
server.port=${SERVER_PORT:${DEFAULT_PORT:8080}}For the first expression, --strict accepts either key; it fails if both are
absent. The second expression always has a literal fallback. When a fallback
contains several references, all must resolve unless the primary key is present.
Each supplied env file is checked independently. As with simple placeholders,
empty values count as defined; use check or validate to reject empty values.
Human output preserves the full default expression. JSON adds a recursive
fallback array to placeholders with nested references, and --quiet includes
nested variable names. Missing conditional requirements are reported as their
full ${...} expression in missing_local / missing_example.
envguard scan-config --files=application.ymlScanned: application.yml
Required variables:
- DATABASE_URL (spring.datasource.url)
- DATABASE_PASSWORD (spring.datasource.password)
Variables with defaults (nested fallbacks are conditional):
- SERVER_PORT=8080 (server.port)
Use --strict with --local / --example to verify all required variables are defined:
envguard scan-config --files=application.yml --local=.env --example=.env.example --strictRequired variables found in config: 2
Optional variables found in config: 1
Required variables:
- DATABASE_URL (spring.datasource.url)
- DATABASE_PASSWORD (spring.datasource.password)
Variables with defaults (nested fallbacks are conditional):
- SERVER_PORT=8080 (server.port)
Missing in .env:
- DATABASE_PASSWORD
Missing in .env.example:
- DATABASE_URL
Exits with code 1 when --strict is set and a required variable or fallback
expression cannot be satisfied by a provided env file. Without --strict,
missing requirements are reported but do not cause failure. --strict alone
performs no comparison: supply --local, --example, or both. Read and parse
errors fail regardless of strict mode.
The scanner recognizes uppercase env names matching [A-Z_][A-Z0-9_]*.
It is a placeholder scanner, not a complete Spring Boot or Quarkus configuration
resolver: it does not select active profiles, resolve property-name references,
expand YAML aliases, or join properties continuation lines. All YAML documents
are scanned regardless of profile. Malformed or unsupported placeholder syntax
may be skipped, so a successful scan does not validate the configuration syntax
of the target framework.
Spring Boot application.yml
spring:
datasource:
url: ${DATABASE_URL}
password: ${DATABASE_PASSWORD}
server:
port: ${SERVER_PORT:8080}Quarkus application.properties
quarkus.datasource.jdbc.url=${DATABASE_URL}
quarkus.datasource.password=${DATABASE_PASSWORD}
quarkus.http.port=${SERVER_PORT:8080}Flags:
| Flag | Description |
|---|---|
--files |
Comma-separated list of config files to scan (required) |
--format |
Force format: auto | yaml | props (default: auto, detected from extension) |
--local |
Path to local .env file for comparison |
--example |
Path to .env.example file for comparison |
--strict |
Fail for unresolved requirements in supplied --local / --example files |
--json |
Output results as JSON (for CI integrations) |
--quiet |
Output only variable names, one per line |
The CLI can run in GitHub Actions. v1.0.0 does not provide an action.yml, so
uses: BLemine/envguard@v1.0.0 is not supported yet.
Save the following as .github/workflows/envguard.yml in the repository you
want to audit. It installs the pinned CLI release and fails when the audit finds
committed env files or matching secret patterns:
name: Envguard
on: [push, pull_request]
permissions:
contents: read
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: actions/setup-go@v6
with:
go-version: '1.25.x'
cache: false
- name: Install envguard
run: go install github.com/BLemine/envguard@v1.0.0
- name: Audit Git history
run: envguard auditfetch-depth: 0 fetches history for all
branches and tags. setup-go provides the
Go toolchain. This example does not require a local .env or production secrets.
For repositories with application config and a committed .env.example, add
this step after installation, adjusting the filenames to your project:
- name: Check documented config requirements
run: |
envguard scan-config \
--files=application.yml \
--example=.env.example \
--strictTo run check or validate instead, first provision a .env file in the job,
or point --local at an existing test env file. These commands do not read
GitHub Actions env: entries as the input being validated. Do not commit
production secrets just to make a CI check pass.
| Command | Success (0) |
Failure (1) |
|---|---|---|
check |
Every example key has a non-empty local value; undocumented keys may remain | An example key is missing or empty in the local file |
validate |
Every requested key exists and is non-empty | Missing/empty requested keys |
scan-config |
Scan completes; comparisons pass, or strict mode is off | Unresolved requirements with --strict and a comparison file |
audit |
No matching findings in scanned history | Committed env files or matching patterns found |
sync, encrypt, decrypt |
Operation completes | Operation fails |
Invalid flags, missing required arguments, and input/output errors also exit
with code 1. scan-config --json and --quiet affect output only; --json
takes precedence when both are supplied.
envguard/
├── cmd/
│ ├── root.go # Cobra root command
│ ├── check.go # envguard check
│ ├── sync.go # envguard sync
│ ├── validate.go # envguard validate
│ ├── audit.go # envguard audit
│ ├── encrypt.go # envguard encrypt
│ ├── decrypt.go # envguard decrypt
│ ├── scan_config.go # envguard scan-config
│ └── passphrase.go # shared passphrase resolution
├── internal/
│ ├── parser/ # .env file parsing
│ ├── differ/ # diff logic
│ ├── reporter/ # colored terminal output
│ ├── auditor/ # git history scanning
│ ├── configscan/ # YAML / .properties placeholder extraction
│ └── crypto/ # AES-256-GCM + Argon2id
└── main.go
-
audit— scan git history for accidentally committed secrets -
encrypt/decrypt— encrypted.envfor safe team sharing -
scan-config— extract env placeholders from Spring Boot / Quarkus config files - Batch processing of multiple
.envpairs in one command (custom paths already work;scan-config --filesalready accepts multiple config files) - GitHub Actions marketplace action
PRs welcome. Open an issue first for anything beyond small fixes.
MIT