Announcing EnvMage: environment variables, finally under control

Every Node.js project eventually hits the same wall: .env files that drift from their templates, a missing key that only explodes in production, and a README section nobody updates. We fixed that wall for our own projects with a small CLI, and today we're sharing it with everyone.

The problem

Environment configuration is where most projects quietly rot. Values get added to one file but not the template, staging and production diverge, and by the time a CI pipeline fails on a missing variable, someone has to diff files by hand to find out why.

• No single source of truth for what a project requires
• Validation happens at runtime, deep inside your app, not at the door
• Typed access to process.env is manual and easy to get wrong
• Sensitive values end up in logs, commits, and support threads

What EnvMage does

EnvMage treats your .env files like code: tracked, templated, and validated. You annotate your template once, and every command builds on it.

npm install -g env-mage
env-mage init          # scaffold .env.example from your .env
env-mage validate      # check every environment against the template
env-mage typegen       # generate src/env.d.ts with exact types
env-mage scan          # find every variable used in your codebase

A quick tour

Let's walk through a real session. First, create a template from your existing .env:

$ env-mage init
✓ Created .env.example from .env
✓ Marked 12 variables as required

Your .env.example now documents what the project needs — and env-mage reads those annotations to enforce them:

$ env-mage validate
✓ All required variables present
✓ All variables match expected format

Now generate types so every process.env access is checked at compile time:

$ env-mage typegen
✓ TypeScript definitions generated at src/env.d.ts

From that moment on, your editor tells you the moment a key is missing or misspelled — before your app ever boots.

Validation in CI

The real payoff is catching problems before they reach a teammate. Add one step to your pipeline and every pull request validates its environment:

# .github/workflows/ci.yml
- name: Validate environment
  run: npx env-mage validate

Now a missing key fails the PR, not production. The same command that runs locally runs in CI — there's no special setup and no separate config to keep in sync.

Privacy by default

EnvMage runs entirely on your machine. There is no telemetry, no cloud sync, and no hidden network calls — your secrets never leave your project. It's MIT licensed, and the source is public so you can verify that claim yourself.

What's next

The first release covers the workflow we live in every day. On the roadmap: multi-file environments, IDE integrations, and a pre-commit hook that validates before you commit. If there's a command you wish existed, open an issue — the backlog is shaped by the community.

Head over to the EnvMage page to get started, or read the docs for a full command reference.