{"id":47291833,"url":"https://github.com/shashi089/env-drift-check","last_synced_at":"2026-05-11T10:01:45.459Z","repository":{"id":334851548,"uuid":"1139797680","full_name":"shashi089/env-drift-check","owner":"shashi089","description":"Smart environment drift checker for .env files — detects missing, extra, or mismatched variables, enforces type validation, and helps maintain consistent configs across environments.","archived":false,"fork":false,"pushed_at":"2026-05-11T08:13:55.000Z","size":133,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T09:36:56.126Z","etag":null,"topics":["drift-detection","env","env-checker","env-drift-check","environment--development","environment-production","environment-variables","environmental-monitoring","open-source"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/env-drift-check","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shashi089.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T12:35:00.000Z","updated_at":"2026-05-11T08:13:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shashi089/env-drift-check","commit_stats":null,"previous_names":["shashi089/env-drift-check"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/shashi089/env-drift-check","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashi089%2Fenv-drift-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashi089%2Fenv-drift-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashi089%2Fenv-drift-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashi089%2Fenv-drift-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shashi089","download_url":"https://codeload.github.com/shashi089/env-drift-check/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashi089%2Fenv-drift-check/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32889972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drift-detection","env","env-checker","env-drift-check","environment--development","environment-production","environment-variables","environmental-monitoring","open-source"],"created_at":"2026-03-16T09:05:39.098Z","updated_at":"2026-05-11T10:01:45.453Z","avatar_url":"https://github.com/shashi089.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# env-drift-check\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n**Detect, validate, and fix environment variable drift --- without breaking your `.env` file.**\r\n\r\n[![npm version](https://img.shields.io/npm/v/env-drift-check.svg?style=flat-square)](https://npmjs.org/package/env-drift-check)\r\n[![npm downloads](https://img.shields.io/npm/dm/env-drift-check.svg?style=flat-square)](https://npm-stat.com/charts.html?package=env-drift-check)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\r\n\r\n*Eliminate \"It works on my machine\" errors with automated drift detection and interactive environment synchronization.*\r\n\r\n[Installation](#installation) • [Features](#features) • [Quick Start](#quick-start) • [Configuration](#configuration) • [Library Usage](#programmatic-usage) • [Roadmap](#roadmap)\r\n\r\n\u003c/div\u003e\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n  \u003cimg src=\"https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check.png\" alt=\"env-drift-check: Interactive .env synchronizer and validator\" width=\"800\" /\u003e\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n## ⚡ See It In Action\r\n\r\n```bash\r\nnpx env-drift-check\r\n\r\n✔ Loaded: .env\r\n✔ Base: .env.example\r\n\r\n✖ Missing keys:\r\n  - DATABASE_URL\r\n  - STRIPE_SECRET_KEY\r\n\r\n⚠ Unused keys:\r\n  - OLD_API_KEY\r\n\r\n❌ Validation failed: PORT must be a number\r\n```\r\n\r\n👉 **Fix instantly with interactive mode:**\r\n\r\n```bash\r\nnpx env-drift-check -i\r\n```\r\n\r\n---\r\n\r\n## 💡 The Problem It Solves\r\n\r\nManaging `.env` files across a team of developers or multiple deployment environments (development, staging, production) is notoriously error-prone. \r\n\r\n- **Missing variables** lead to unexpected runtime crashes.\r\n- **Incorrect data types** (e.g., passing a string `\"false\"` instead of a proper boolean) cause silent logical bugs.\r\n- **Onboarding new developers** often involves insecurely sharing `.env` files over Slack, or fighting with an outdated `.env.example`.\r\n\r\n**env-drift-check** bridges this gap. It provides real-time drift detection to ensure your local environments match the blueprint, an interactive CLI to fix missing variables instantly, and a robust schema validator to enforce types and formats.\r\n\r\n---\r\n\r\n## 🏗 Architecture \u0026 Flow\r\n\r\n```mermaid\r\ngraph TD\r\n    A[Developers / CI] --\u003e|Run env-drift-check| B(Engine)\r\n    \r\n    subgraph Validation Process\r\n    B --\u003e|1. Parse| C{.env.example}\r\n    B --\u003e|2. Parse| D[Target .env]\r\n    B --\u003e|3. Load Rules| E[envwise.config.json]\r\n    \r\n    C --\u003e F{Drift Detector}\r\n    D --\u003e F\r\n    \r\n    F --\u003e|Detect Mismatches| G{Compare Keys \u0026 Values}\r\n    E --\u003e|Schema Validation| G\r\n    end\r\n\r\n    G --\u003e|Interactive Mode| H[Prompt UI: Auto-fix]\r\n    H --\u003e|Update| D\r\n    \r\n    G --\u003e|Strict Mode| I[CI/CD Exit Code 1]\r\n    G --\u003e|Report| J[Terminal Output]\r\n```\r\n\r\n---\r\n\r\n## 🚀 Features\r\n\r\n- 🔍 **Environment Drift Detection**: Automatically compares your local `.env` against the base `.env.example`. Detects both **missing keys** and **extra/ghost keys**.\r\n- 🛡️ **Extensive Schema Validation**: Enforce `string`, `number`, `boolean`, `enum`, `email`, `url`, and custom `regex` validations via `envwise.config.json`.\r\n- 🪄 **Interactive Auto-fix Wizard**: A beautiful CLI experience that prompts you for missing variables.\r\n- 🔐 **Security Conscious**: Automatically masks inputs for keys containing `SECRET` or `PASSWORD` during interactive setup.\r\n- 📑 **High-Fidelity Formatting**: Inherently preserves your original inline comments, empty lines, bespoke spacing, and absolute key ordering when patching your `.env` file.\r\n- 🔄 **Multi-Environment Support**: Validate all `.env*` files in your project simultaneously with the `--all` flag.\r\n- 🚦 **CI/CD Ready**: Native `--strict` mode to fail builds on validation errors, ensuring zero-drift deployments.\r\n\r\n### ✨ Interactive Fix (Best Feature)\r\n\r\n```bash\r\n$ npx env-drift-check -i\r\n\r\nMissing: DATABASE_URL\r\nEnter value: postgres://localhost:5432/db\r\n\r\n✔ Added to .env\r\n✔ All variables synced\r\n```\r\n\r\n### How Does It Compare?\r\n\r\n| Feature | `dotenv-safe` | `envalid` | **`env-drift-check`** |\r\n| :--- | :---: | :---: | :---: |\r\n| **Missing Keys Detection** | ✅ | ✅ | ✅ |\r\n| **CLI Interactive Fix** | ❌ | ❌ | ✅ |\r\n| **Schema Validation** | ❌ | ✅ (Code) | ✅ (JSON) |\r\n| **Cross-Env File Check** | ❌ | ❌ | ✅ |\r\n| **No Code Integration Needed**| ❌ | ❌ | ✅ |\r\n| **Preserves Formatting** | ❌ | ❌ | ✅ |\r\n\r\n👉 **env-drift-check works purely as a standalone CLI tool --- no code changes required!**\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\nInstall `env-drift-check` as a development dependency:\r\n\r\n```bash\r\nnpm install --save-dev env-drift-check\r\n```\r\n\r\nOr run it directly using `npx` without installing:\r\n\r\n```bash\r\nnpx env-drift-check init\r\n```\r\n\r\n---\r\n\r\n## ⚡ Quick Start\r\n\r\n### 1. Initialize the Project\r\n\r\nBootstrap your repository with a default configuration and `.env.example`:\r\n\r\n```bash\r\nnpx env-drift-check init\r\n```\r\n\r\n\u003e [!TIP]\r\n\u003e Check out our [Demo Project](https://github.com/shashi089/env-drift-check/tree/main/examples/demo-app) to see how to integrate this into a real application workflow.\r\n\r\n*Output:*\r\n```text\r\n✅ Created envwise.config.json\r\n✅ Created .env.example\r\n\r\nSetup complete! Run 'npx env-drift-check -i' to sync your .env file.\r\n```\r\n\r\n### 2. Run an Interactive Check\r\n\r\nIf you just cloned a repo, check for missing environment variables and fill them in right from the terminal:\r\n\r\n```bash\r\nnpx env-drift-check -i\r\n```\r\n\r\n![Interactive update](https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check-i-update.png)\r\n\r\nOnce completed, your `.env` file is automatically updated!\r\n\r\n![Interactive success](https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check-i-final.png)\r\n\r\n---\r\n\r\n## ⚙️ Configuration (`envwise.config.json`)\r\n\r\nTo unlock the full power of the schema validator, define rules in an `envwise.config.json` file at the root of your project.\r\n\r\n### Sample Configuration\r\n\r\n```json\r\n{\r\n  \"baseEnv\": \".env.example\",\r\n  \"rules\": {\r\n    \"PORT\": { \r\n      \"type\": \"number\", \r\n      \"min\": 1024, \r\n      \"max\": 65535,\r\n      \"description\": \"The port the HTTP server binds to\"\r\n    },\r\n    \"NODE_ENV\": { \r\n      \"type\": \"enum\", \r\n      \"values\": [\"development\", \"production\", \"test\", \"staging\"] \r\n    },\r\n    \"DEBUG_MODE\": { \r\n      \"type\": \"boolean\", \r\n      \"mustBeFalseIn\": \"production\" \r\n    },\r\n    \"DATABASE_URL\": { \r\n      \"type\": \"url\",\r\n      \"required\": true\r\n    },\r\n    \"ADMIN_EMAIL\": {\r\n      \"type\": \"email\"\r\n    },\r\n    \"API_KEY\": {\r\n      \"type\": \"regex\",\r\n      \"regex\": \"^sk_(test|live)_[0-9a-zA-Z]{24}$\",\r\n      \"description\": \"Stripe API Key format\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Supported Validation Types\r\n\r\n| Type | Options | Description |\r\n|---|---|---|\r\n| `string` | `min`, `max` | Enforce string length bounds. |\r\n| `number` | `min`, `max` | Enforce numeric value limits. |\r\n| `boolean` | `mustBeFalseIn` | Ensure value is \"true\" or \"false\". Can conditionally reject \"true\" in specific environments (e.g. production safety). |\r\n| `enum` | `values: []` | Restrict the variable to a specific set of allowed strings. |\r\n| `email` | - | Validates against a standard email regex. |\r\n| `url` | - | Validates standard URI formats. |\r\n| `regex` | `regex` | Custom regular expression validation. |\r\n\r\n---\r\n\r\n## 📦 Programmatic Usage\r\n\r\n`env-drift-check` can also be used as a library in your Node.js applications to enforce environment health at startup.\r\n\r\n```typescript\r\nimport { checkDrift, loadConfig, parseEnv, report } from 'env-drift-check';\r\nimport path from 'path';\r\n\r\nconst config = loadConfig();\r\nconst baseEnv = parseEnv(path.resolve('.env.example'));\r\nconst targetEnv = parseEnv(path.resolve('.env'));\r\n\r\nconst result = checkDrift(baseEnv, targetEnv, config);\r\n\r\nif (result.missing.length || result.errors.length) {\r\n  console.error(\"Environment check failed!\");\r\n  report(result);\r\n  process.exit(1);\r\n}\r\n```\r\n\r\n---\r\n\r\n## 📚 Examples\r\n\r\nExplore our sample projects to see `env-drift-check` in action:\r\n\r\n- [**Basic Usage**](https://github.com/shashi089/env-drift-check/tree/main/examples/basic-usage): A minimal example showing file synchronization.\r\n- [**Real-World Demo App**](https://github.com/shashi089/env-drift-check/tree/main/examples/demo-app): A complete Express-style app with programmatic \"fail-fast\" bootstrap logic and CI/CD integration.\r\n\r\n---\r\n\r\n## 💻 CLI Usage Examples\r\n\r\nCheck defaults:\r\n```bash\r\nnpx env-drift-check\r\n```\r\n\r\nLaunch Interactive fix:\r\n```bash\r\nnpx env-drift-check -i\r\n```\r\n\r\nStrict mode (fails with exit code 1):\r\n```bash\r\nnpx env-drift-check --strict\r\n```\r\n\r\nMulti-Environment check:\r\n```bash\r\nnpx env-drift-check --all\r\n```\r\n\r\n---\r\n\r\n## 📤 Exit Codes\r\n\r\n- `0` → No issues found.\r\n- `1` → Schema validation failed or missing keys detected (in `--strict` mode).\r\n\r\n---\r\n\r\n## 🌟 Best Practices\r\n\r\n1. **Never commit `.env` or `.env.*` files!** Ensure they are in your `.gitignore`.\r\n2. **Always commit `.env.example`** and `envwise.config.json` as the source of truth for your team.\r\n3. **Use the Interactive Mode** (`-i`) locally during development and onboarding.\r\n4. **Use Strict Mode** (`--strict`) in your CI/CD pipeline to catch missing production variables early.\r\n5. **Add it to your `postinstall` or `prepare` script** in `package.json` to auto-prompt new developers:\r\n   ```json\r\n   \"scripts\": {\r\n     \"prepare\": \"env-drift-check -i\"\r\n   }\r\n   ```\r\n\r\n---\r\n\r\n## 🗺 Roadmap\r\n\r\n- [x] Boolean conditional checks (`mustBeFalseIn`)\r\n- [x] Interactive CLI prompts\r\n- [x] Multi-file parsing (`--all`)\r\n- [x] High-fidelity formatting preservation\r\n- [ ] **JSON Output Mode**: Provide `--format json` for reporting to integrate with other tooling pipelines.\r\n- [ ] **Secret Scanning**: Add basic entropy checks to prevent weak local passwords from entering production variables.\r\n- [ ] **Variable Deprecation**: Support marking keys as deprecated to gracefully remove them across teams.\r\n- [ ] **Auto-generate `.env.example`**: Create a base example from an existing `.env`.\r\n- [ ] **Codebase Scanning**: Detect variables used in code (`process.env.X`) that are missing from config.\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are always welcome! \r\n\r\n1. Fork the project\r\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\r\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\r\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\r\n5. Open a Pull Request\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nDistributed under the MIT License. See `LICENSE` for more information.\r\n\r\n---\r\n\r\n\u003e Built with ❤️ for better Developer Experience by [Shashidhar Naik](https://github.com/shashi089)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshashi089%2Fenv-drift-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshashi089%2Fenv-drift-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshashi089%2Fenv-drift-check/lists"}