env-doctor

Diagnose .env drift and detect committed secrets. Free standalone tool.

A small Node.js CLI that checks your project's environment configuration for the common ways it breaks in production:

• .env files tracked in git
• .env files not in .gitignore
• Env vars used in code but not documented in .env.example
• Env vars documented in .env.example but not actually read by code
• Likely-committed secrets (AWS keys, Stripe keys, GitHub tokens, OpenAI/Anthropic keys, PEM private keys, JWTs)
• Whitespace / quoting smells in .env values that some parsers don't tolerate

Runs in ~1 second on a typical repo. No telemetry. No signups. No dependencies.

Install

# global
npm install -g @yixi/env-doctor

# or just run without install
npx @yixi/env-doctor

Use

# Audit the current directory
env-doctor

# Audit a specific path
env-doctor ~/code/my-app

# Machine-readable output for CI
env-doctor --json

# Exit code only, no output (for CI gates)
env-doctor --quiet

Exit codes

| Code | Meaning | |---|---| | 0 | No issues, or only LOW findings | | 1 | MEDIUM findings present | | 2 | CRITICAL or HIGH findings present |

Use in CI as a soft gate:

# .github/workflows/ci.yml
- name: Check env config
  run: npx -y @yixi/env-doctor --quiet
  continue-on-error: true  # warn but don't block

Or as a hard gate by removing continue-on-error.

What it checks (severities)

| Severity | Check | |---|---| | CRITICAL | .env file tracked in git | | CRITICAL | Pattern matching a known secret format (AWS, Stripe, GitHub, OpenAI, Anthropic, Slack, PEM, JWT) in a tracked file | | HIGH | .env exists but isn't .gitignored | | HIGH | Env var read in code but not documented in any .env.example / .env.sample / .env.template | | MEDIUM | No .env.example exists at all | | MEDIUM | Env var documented in .env.example but never read by code (likely dead) | | LOW | Surrounding whitespace in a .env value | | LOW | Literal quote characters likely included in a .env value |

What it doesn't check

• Whether your env vars have the right values — only their presence and shape
• Cross-env-file consistency in detail (e.g., .env.test vs .env.development) — only against the canonical example file
• Vars set by deployment-time secret stores (AWS Secrets Manager, Vault, Doppler) that don't appear in any local file
• Vars read via dynamic property access (process.env[someVar]) — pure string access is required to match

Privacy

This tool runs entirely locally. It never makes a network request. It never reads files outside the directory you point it at. It never sends your env values anywhere — values are only used internally for whitespace/quote diagnostics and are never printed to stdout (only variable names and filenames appear in reports).

Origin

This is a free standalone version of one skill from Claude Operator — a production-grade CLAUDE.md and skill pack for senior engineering teams using Claude Code.

The full pack includes 17 more skills like this one, 3 subagents (verifier, context-keeper, safety-officer), 3 slash commands (/ship, /review, /cost), and a hooks/permissions config — all focused on stopping common agent failure modes before they ship.

Pricing: $27 / $69 / $174 for solo / team / lifetime. Lifetime updates within version line.

Paid CLAUDE.md skill pack with deeper LLM-aware tooling — coming soon.

License

MIT.

Contributing

This is a small, focused tool. PRs for the following are welcome:

• Additional secret patterns (high precision only — please include a unit test showing it doesn't false-positive on normal code)
• Support for .envrc (direnv) format
• Additional language env-read patterns (PHP, Elixir, etc.)

PRs for the following will probably be closed:

• Auto-fix mode (intentional design: report, don't modify)
• A web UI (out of scope)
• Sending findings to an external service (privacy is a feature)

Project status

v0.1.0 — initial release. Tested on Node 18, 20, 22, 24.

Sister tools

Part of a small family of zero-dependency static-analysis CLIs:

• @yixi/env-doctor — this tool
• @yixi/dockerfile-doctor — Dockerfile production-safety linter
• @yixi/token-doctor — local Claude Code spend analyzer

See also

• git-secrets — broader secret scanning
• gitleaks — full-history secret scanning
• dotenv-linter — .env syntax linting only