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

Source: Dev.to

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 hard‑coded 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

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

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

Suggested Team Workflow

• Maintain required keys in .env.example.
• Add .env.schema for type validation.
• Keep envguard watch running during development.
• 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

Repo: