{"id":31424828,"url":"https://github.com/marian1309/vercel-env","last_synced_at":"2026-05-18T19:02:47.439Z","repository":{"id":317090062,"uuid":"1065861866","full_name":"Marian1309/vercel-env","owner":"Marian1309","description":"Seamlessly sync 🔄 and manage 🛠️ environment variables 🌐 between your local development files 💻 and Vercel deployments 🚀","archived":false,"fork":false,"pushed_at":"2025-09-28T18:17:46.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-28T20:33:28.991Z","etag":null,"topics":["cli","env","vercel"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@pidchashyi/vercel-env","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Marian1309.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-09-28T15:20:42.000Z","updated_at":"2025-09-28T18:17:49.000Z","dependencies_parsed_at":"2025-09-28T20:33:56.588Z","dependency_job_id":"d91e1718-e3e1-4a26-a30e-60b6fdb4fad2","html_url":"https://github.com/Marian1309/vercel-env","commit_stats":null,"previous_names":["marian1309/vercel-env"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Marian1309/vercel-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marian1309%2Fvercel-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marian1309%2Fvercel-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marian1309%2Fvercel-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marian1309%2Fvercel-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Marian1309","download_url":"https://codeload.github.com/Marian1309/vercel-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marian1309%2Fvercel-env/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277627204,"owners_count":25849804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-30T02:00:09.208Z","response_time":75,"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":["cli","env","vercel"],"created_at":"2025-09-30T04:04:22.406Z","updated_at":"2025-10-10T13:36:32.653Z","avatar_url":"https://github.com/Marian1309.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @pidchashyi/vercel-env\n\nA comprehensive library and CLI tool for syncing environment variables between local files and Vercel. This tool provides both programmatic access through named modules (`deleteEnvs` and `syncEnvs`) and a modern, interactive CLI interface powered by @clack/prompts.\n\n\u003cimg src=\"./icon.png\" /\u003e\n\n## 📖 What is this?\n\n**@pidchashyi/vercel-env** solves the common problem of keeping environment variables synchronized between your local development environment and your Vercel deployments. Instead of manually copying variables back and forth, this tool provides:\n\n### 🎯 **The Problem It Solves:**\n- **Manual sync headaches**: Copying environment variables between local `.env` files and Vercel dashboard\n- **Deployment mismatches**: Local and production environments getting out of sync\n- **Time-consuming setup**: Setting up new team members or environments\n- **Human errors**: Typos, missing variables, or incorrect values during manual copying\n- **No version control**: Environment variables aren't tracked or easily managed\n\n### 💡 **The Solution:**\n- **Bidirectional sync**: Automatically sync between local files (`.env.local`, `.env.prod`) and Vercel environments\n- **Modern interactive interface**: Beautiful CLI powered by @clack/prompts with individual action selection\n- **Safety first**: Multiple confirmation prompts, smart exclusion lists, and system variable filtering\n- **Developer-friendly**: Both CLI commands and TypeScript library for automation\n- **Smart detection**: Automatically detects differences and suggests specific actions\n- **Flexible workflows**: Choose individual actions per variable or batch operations\n\n### 🔧 **How It Works:**\n1. **Connects** to your Vercel project using the official Vercel CLI\n2. **Compares** your local environment files with Vercel's environment variables\n3. **Shows differences** in an easy-to-understand format\n4. **Lets you choose** what to sync, add, update, or delete\n5. **Applies changes** safely with confirmation prompts\n6. **Reports results** so you know exactly what happened\n\n### 👥 **Perfect For:**\n- **Developers** who work with Vercel deployments\n- **Teams** that need consistent environment setups\n- **DevOps** automation and CI/CD pipelines\n- **Projects** with multiple environments (dev, staging, prod)\n- **Anyone** tired of manually managing environment variables\n\n## 🚀 Features\n\n- **Two-way sync** between local `.env` files and Vercel environments\n- **Individual action selection** - choose specific actions per variable (add, update, pull, delete)\n- **Interactive deletion** with local file cleanup options and safety checks\n- **Modern CLI interface** powered by @clack/prompts with beautiful, intuitive prompts\n- **Smart system variable filtering** - automatically excludes Vercel system variables\n- **Library modules** for programmatic usage with full TypeScript support\n- **Environment-specific** operations (development/production)\n- **Multiple confirmation levels** with retry options and graceful cancellation\n- **Flexible sync modes** - interactive (per-variable) or auto (batch) modes\n\n## 📋 Prerequisites\n\nBefore using this library, you need to set up Vercel CLI and authenticate:\n\n### 1. Install Vercel CLI\n\n```bash\nnpm i -g vercel\n```\n\n### 2. Login to Vercel\n\n```bash\nvercel login\n```\n\n### 3. Link your project\n\nNavigate to your project directory and link it to your Vercel project:\n\n```bash\nvercel link\n```\n\nThis will create a `.vercel` folder in your project with the necessary configuration.\n\n### 4. Verify setup\n\nTest that everything is working:\n\n```bash\nvercel env ls development\nvercel env ls production\n```\n\n## 🛠️ Installation\n\n### As a CLI tool (global):\n\n```bash\nnpm install -g @pidchashyi/vercel-env\n```\n\n**✨ Global installation gives you easier commands:**\nAfter global installation, you can use the shorter `vercel-env` command directly:\n\n```bash\n# Easy commands (after global install)\nvercel-env --sync           # Instead of npx @pidchashyi/vercel-env --sync\nvercel-env --delete         # Instead of npx @pidchashyi/vercel-env --delete\nvercel-env --sync --dev     # Instead of npx @pidchashyi/vercel-env --sync --dev\nvercel-env --delete --prod  # Instead of npx @pidchashyi/vercel-env --delete --prod\n```\n\n### As a library (local):\n\n```bash\nnpm install @pidchashyi/vercel-env\n# or\nyarn add @pidchashyi/vercel-env\n# or\nbun add @pidchashyi/vercel-env\n```\n\n\u003e **Note**: The library now uses `@clack/prompts` instead of `inquirer` for a modern, beautiful CLI experience.\n\n## 🏃‍♂️ CLI Usage\n\n### Sync environments\n\n```bash\n# If installed globally (easier):\nvercel-env --sync                    # Interactive mode - choose everything\nvercel-env --sync --dev              # Sync development only (interactive)\nvercel-env --sync --prod             # Sync production only (interactive)\nvercel-env --sync --dev --auto       # Auto sync development (with confirmation)\nvercel-env --sync --auto             # Auto sync both environments\n\n# If installed locally (using npx):\nnpx @pidchashyi/vercel-env --sync         # Interactive mode - choose everything\nnpx @pidchashyi/vercel-env --sync --dev   # Sync development only (interactive)\nnpx @pidchashyi/vercel-env --sync --prod  # Sync production only (interactive)\nnpx @pidchashyi/vercel-env --sync --dev --auto  # Auto sync development\nnpx @pidchashyi/vercel-env --sync --auto  # Auto sync both environments\n```\n\n### Delete environment variables\n\n```bash\n# If installed globally (easier):\nvercel-env --delete                  # Interactive deletion (recommended)\nvercel-env --delete --dev            # Delete from development\nvercel-env --delete --prod           # Delete from production\n\n# If installed locally (using npx):\nnpx @pidchashyi/vercel-env --delete       # Interactive deletion (recommended)\nnpx @pidchashyi/vercel-env --delete --dev # Delete from development\nnpx @pidchashyi/vercel-env --delete --prod # Delete from production\n```\n\n\u003e 💡 **New Features**: \n\u003e - **Exit option**: \"❌ Exit - Cancel deletion and exit\" option for safe cancellation\n\u003e - **Local cleanup**: Option to also delete variables from local files (.env.local, .env.prod)\n\u003e - **Retry on \"No\"**: If you decline a deletion, you can go back and choose different actions\n\u003e - **System variable filtering**: Automatically excludes Vercel system variables from deletion\n\n## 📚 Library Usage\n\nYou can use this library in two ways:\n\n### 1. Import as Library Modules\n\n```typescript\nimport { syncEnvs, deleteEnvs } from '@pidchashyi/vercel-env';\n\n// Interactive sync (default)\nawait syncEnvs();\n\n// Auto sync specific environments\nawait syncEnvs({\n  environments: ['development'],\n  mode: 'auto'\n});\n\n// Delete environment variables\nawait deleteEnvs({\n  environments: ['development']\n});\n```\n\n### 2. Run Modules Directly with Bun\n\nYou can also run the individual module files directly:\n\n```bash\n# Run sync module directly\nbun node_modules/@pidchashyi/vercel-env/src/actions/sync.ts\n\n# Run delete module directly  \nbun node_modules/@pidchashyi/vercel-env/src/actions/delete.ts\n\n# Or if installed globally\nbun ~/.bun/install/global/node_modules/@pidchashyi/vercel-env/src/actions/sync.ts\nbun ~/.bun/install/global/node_modules/@pidchashyi/vercel-env/src/actions/delete.ts\n```\n\n### 3. Local Development (if you have the source)\n\n```bash\n# Clone and run directly from source\ngit clone \u003crepository-url\u003e\ncd vercel-env\n\n# Run sync module\nbun src/actions/sync.ts\n\n# Run delete module  \nbun src/actions/delete.ts\n\n# With command line arguments\nbun src/actions/sync.ts --dev --auto\nbun src/actions/delete.ts --interactive\n```\n\n### 4. Using NPM Scripts (after installation)\n\nThe package includes convenient npm scripts:\n\n```bash\n# Basic operations\nnpm run sync          # Interactive sync\nnpm run delete        # Interactive delete\n\n# Environment-specific operations  \nnpm run sync:dev      # Auto sync development\nnpm run sync:prod     # Interactive sync production\nnpm run delete:dev    # Delete from development\nnpm run delete:prod   # Delete from production\n```\n\n## 🔧 Configuration\n\nThe library works with the following local files:\n\n- **Development**: `.env.local` ↔ Vercel development environment\n- **Production**: `.env.prod` ↔ Vercel production environment\n\n### Excluded Variables\n\nSystem variables are automatically excluded from sync and deletion operations to prevent accidental removal of critical Vercel functionality:\n\n**All environments:**\n- `VERCEL_OIDC_TOKEN` - System-generated OIDC token\n- `VERCEL_URL` - Vercel system variable\n- `VERCEL_ENV` - Vercel system variable  \n- `VERCEL_REGION` - Vercel system variable\n\n**Production only:**\n- `NX_DAEMON` - NX build system variable\n- `TURBO_CACHE` - Turborepo cache variable\n- `TURBO_DOWNLOAD_LOCAL_ENABLED` - Turborepo download setting\n- `TURBO_REMOTE_ONLY` - Turborepo remote-only setting\n- `TURBO_RUN_SUMMARY` - Turborepo run summary setting\n- `VERCEL` - Vercel system flag\n- `VERCEL_TARGET_ENV` - Vercel target environment\n\n\u003e **Note**: These exclusions apply to both sync operations (preventing pull from Vercel) and deletion operations (preventing accidental system variable removal).\n\n## 📦 Project Structure\n\n```\nsrc/\n├── actions/\n│   ├── delete.ts   # deleteEnvs module with @clack/prompts\n│   └── sync.ts     # syncEnvs module with @clack/prompts\n├── constants/\n│   └── index.ts    # Configuration constants and exclusion lists\n├── types/\n│   └── index.ts    # TypeScript type definitions\n├── cli.ts          # Main CLI interface\n└── index.ts        # Library exports\n```\n\n## 🔄 How it works\n\n### Sync Process\n\n1. **Fetch** environment variables from both local files and Vercel\n2. **Compare** values and identify differences\n3. **Present individual choices** for each variable conflict (add, update, pull, remove, or do nothing)\n4. **Confirm each action** with descriptive prompts (e.g., \"Add 'API_KEY' to Vercel development environment?\")\n5. **Retry on decline** - if you say \"No\", you can choose a different action\n6. **Apply changes** and report success/failure for each operation\n\n### Delete Process\n\n1. **Fetch** environment variables from selected Vercel environments (excluding system variables)\n2. **Display** variables with their values and environments\n3. **Allow selection** of variables to delete with \"Exit\" option at the top\n4. **Show selected variables** in confirmation prompt for review\n5. **Ask about local cleanup** - option to also delete from .env.local/.env.prod files\n6. **Retry on decline** - if you say \"No\" to deletion, you can go back and select different variables\n7. **Execute** deletions from Vercel and optionally local files, then report results\n\n## 🎮 Interactive Features\n\n### Modern CLI Experience\n\nThe tool now uses **@clack/prompts** for a beautiful, modern CLI experience:\n\n#### Sync Mode - Individual Action Selection\n\nFor each environment variable conflict, you get a dedicated prompt:\n\n```\n🔧 Choose action for variable \"DATABASE_URL\" (development):\n│  ● ➕ Add to Vercel - \"postgresql://localhost:5432/mydb\"\n│  ○ 🗑️ Remove from Local - Will delete from .env.local\n│  ○ ⏭️ Do nothing with DATABASE_URL\n```\n\nThen confirmation with clear context:\n```\n🔧 ➕ Add \"DATABASE_URL\" to Vercel development environment?\n│  ○ Yes / ● No\n```\n\n**If you choose \"No\"**: You go back to the action selection - no need to start over!\n\n#### Delete Mode - Enhanced Safety\n\n**Variable Selection** with exit option at the top:\n```\n🗑️ Select environment variables to DELETE:\n│  ◯ ❌ Exit - Cancel deletion and exit\n│  ◯ 🔧 API_KEY (development)\n│  ◯ 🚀 SECRET_TOKEN (production)\n│  ◯ 🔧🚀 DATABASE_URL (development, production)\n```\n\n**Confirmation** shows exactly what will be deleted:\n```\nAre you absolutely sure you want to delete these variables?\n\n1. 🔧 API_KEY (development)\n2. 🚀 SECRET_TOKEN (production)\n\n🚨 THIS ACTION CANNOT BE UNDONE! 🚨\n│  ○ Yes / ● No\n```\n\n**Local Cleanup Option**:\n```\nAlso delete these variables from local environment files (.env.local, .env.prod)?\n│  ○ Yes / ● No\n```\n\n### Key Benefits\n\n- **Individual control**: Choose specific actions per variable\n- **Retry-friendly**: Declining an action lets you choose differently\n- **Clear context**: Descriptive prompts show exactly what will happen\n- **Safe defaults**: Destructive actions default to \"No\"\n- **System protection**: Automatically filters out Vercel system variables\n- **Graceful cancellation**: Multiple exit points with friendly messages\n\n## 🤝 Contributing\n\nContributions, issues, and feature requests are welcome!\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## 👏 Acknowledgments\n\n- [Vercel](https://vercel.com) - For providing excellent deployment platform and CLI tools\n- [@clack/prompts](https://github.com/natemoo-re/clack) - For beautiful, modern CLI prompts\n- [TypeScript](https://www.typescriptlang.org) - For excellent type safety and developer experience\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarian1309%2Fvercel-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarian1309%2Fvercel-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarian1309%2Fvercel-env/lists"}