DEV Community

Adeyemi
Adeyemi

Posted on

Introducing EnvGuard: Catch .env Mistakes Before They Break Your App

#cli #go #webdev #opensource

EnvGuard is an open-source .env validator that catches missing keys, type mismatches, stale variables, and potential secret leaks before they break your app or CI pipeline.

If you work with .env files, this is the guardrail that prevents avoidable config bugs.

TL;DR

  • Validate .env against .env.example
  • Validate values with .env.schema types
  • Detect likely hardcoded secrets
  • Find likely unused env variables
  • Run in watch mode for instant feedback while coding
  • Enforce stricter checks in CI

Why Teams Need a .env Validator

Most configuration failures are not hard problems. They are visibility problems.

You pull a branch and the app fails because one variable is missing.
You fix that and hit a runtime bug because a boolean is "yes" instead of true.
You deploy and discover stale env keys nobody remembers adding.

These issues are easy to fix once identified, but expensive when discovered late.

EnvGuard shifts that feedback earlier.

What EnvGuard Checks

Missing required keys

Compares .env against .env.example and reports missing keys.

Extra/stale keys

Warns on env keys that exist in .env but not in .env.example.

Type validation

With .env.schema, validates types like:

  • string
  • int
  • float
  • bool
  • url
  • email
  • json

Secret detection

Flags suspicious high-entropy values and known token patterns.

Unused variable detection

Scans for env keys that appear unused in the codebase.

.env.example vs .env.schema

Use both, but for different contracts:

  • .env.example defines which keys should exist (key contract)
  • .env.schema defines what each key should look like (type contract)

If you only pick one, start with .env.example.
Best coverage comes from using both.

The Most Practical Feature: watch

One-time validation is good.
Continuous validation while coding is better.

envguard watch
Enter fullscreen mode Exit fullscreen mode

Watch mode automatically re-runs validation when env files change.

By default, it watches:

  • .env
  • .env.example

Optionally, include schema watching:

envguard watch --schema .env.schema
Enter fullscreen mode Exit fullscreen mode

This gives immediate feedback after every save and helps prevent late discovery of config breakage.

Quick Start 

# 1) Basic key validation
envguard validate

# 2) Add type validation
envguard validate --schema .env.schema

# 3) CI-friendly strict mode
envguard validate --strict

# 4) JSON output for tooling
envguard validate --json

# 5) Continuous checks while coding
envguard watch --schema .env.schema
Enter fullscreen mode Exit fullscreen mode

Suggested Team Workflow

  1. Maintain required keys in .env.example.
  2. Add .env.schema for type validation.
  3. Keep envguard watch running during development.
  4. Run envguard validate --strict in CI.

What EnvGuard Is Not

EnvGuard is not a secret manager.
It does not replace Vault or cloud secret stores.

It is a focused validation layer for env correctness.

Closing

Configuration bugs are boring and expensive.

EnvGuard helps you catch them early, keep local setups stable, and reduce avoidable CI/deploy failures.

Install:

go install github.com/atoyegbe/envguard@latest
Enter fullscreen mode Exit fullscreen mode

Repo: envguard

If you already use another .env checker, what does it catch well and where does it fall short?

Top comments (1)

Collapse
 
theoephraim profile image
Theo Ephraim •

You might like varlock.dev - it’s a fairly mature open source tool that handles all of this stuff.