I built a CLI to prevent .env bugs — here’s why

Akshay Kumar Das — Thu, 11 Dec 2025 13:04:49 +0000

If you’ve ever shipped a feature, deployed confidently… and then watched the app crash instantly because of a missing or wrong environment variable — this is for you.

Almost every developer has fought .env issues. They’re silent, annoying, and often only show up after you deploy.

That’s exactly why I built envspec — a schema-driven CLI that validates, generates, and protects environment variables before they break your app.

The problem: .env bugs are invisible until too late

Environment variables seem simple, but they cause real-world failures every day:

A missing DATABASE_URL takes down production
Someone mistypes PORT=abc → app boots but behaves weird
A teammate forgets to add a new variable to their .env
Staging works, production crashes
.env accidentally gets committed
New developers ask: “Which variables do I need?” There is no structure, no validation, and no safety net.

A real failure scenario (we’ve all seen something like this)

A teammate adds:

ENABLE_CACHE=true
CACHE_TTL=900

But your local .env looks like:

ENABLE_CACHE=true

No CACHE_TTL.
Your app deploys fine… until the code tries:

setTimeout(cacheFn, Number(process.env.CACHE_TTL) * 1000)

Number(undefined) → NaN
Now your caching layer behaves unpredictably.

Production bug. Hard to trace. Caused by missing .env values. This shouldn’t happen in 2025.

The insight: .env needs a schema, just like your API does

We validate API bodies, DB schemas, and types —
but .env is still the wild west.

So I built:

envspec

A CLI that turns your .env into a typed, validated, documented source of truth.

👉 npm: https://www.npmjs.com/package/@devakio/envspec
👉 GitHub: https://github.com/akshayxemo/envspec

How envspec solves the problem
✔ 1. Validate your .env

envspec validate

Catches:

Missing variables
Wrong types
Wrong enum values
Unknown vars
Broken JSON (for arrays/objects) Before your app even runs.

✔ 2. Generate .env files safely

envspec create

Works with:

Placeholders
Example values
Backup creation
Merging existing values

This makes onboarding new developers instant.

✔ 3. Infer schema from existing .env

envspec init --from-env

It scans your .env and creates:

{
  "$schemaVersion": 1,
  "vars": {
    "PORT": { "type": "number", "required": false, "desc": "your_port" }
  }
}

✔ 4. Protect env files from accidental commits

envspec git-protect

Automatically adds:

.env
.env.local
.env.*.backup

to .gitignore.

Why this matters for teams

Onboarding becomes 30 seconds, not 30 minutes
CI pipelines can fail fast
Production incidents drop dramatically
Schemas document your env configuration clearly
Secrets remain local — no cloud dependencies envspec is deliberately simple. It doesn’t replace dotenv, vaults, or secrets managers.

It just prevents .env mistakes — everywhere.

Quick Start

npm install -g @devakio/envspec

envspec init
envspec create
envspec validate

Done.

Why I built it
I got tired of:

silent failures
inconsistent .env files
guessing environment variables
onboarding pains
production crashes caused by trivial env typos envspec is my attempt to bring clarity, types, and safety to one of the most overlooked parts of modern development.

Want to try it?
👉 Install

npm install -g @devakio/envspec

👉 GitHub Repo
https://github.com/akshayxemo/envspec

👉 npm Package
https://www.npmjs.com/package/@devakio/envspec

If you like this project, leaving a ⭐ on GitHub means a lot.
And yes — TypeScript support, VSCode plugin, and CI integrations are coming soon.

Forem: Akshay Kumar Das

I built a CLI to prevent .env bugs — here’s why

The problem: .env bugs are invisible until too late

A real failure scenario (we’ve all seen something like this)

The insight: .env needs a schema, just like your API does

envspec