DEV Community

Cover image for I built a CLI to prevent .env bugs — here’s why
Akshay Kumar Das
Akshay Kumar Das

Posted on

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

#cli #devops #tooling #envspec

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
Enter fullscreen mode Exit fullscreen mode

But your local .env looks like:

ENABLE_CACHE=true
Enter fullscreen mode Exit fullscreen mode

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

setTimeout(cacheFn, Number(process.env.CACHE_TTL) * 1000)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

It scans your .env and creates:

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

✔ 4. Protect env files from accidental commits

envspec git-protect
Enter fullscreen mode Exit fullscreen mode

Automatically adds:

.env
.env.local
.env.*.backup
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
envspec init
envspec create
envspec validate
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

👉 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.

Top comments (0)