@pidchashyi/vercel-env

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

📖 What is this?

@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:

🎯 The Problem It Solves:

• Manual sync headaches: Copying environment variables between local .env files and Vercel dashboard
• Deployment mismatches: Local and production environments getting out of sync
• Time-consuming setup: Setting up new team members or environments
• Human errors: Typos, missing variables, or incorrect values during manual copying
• No version control: Environment variables aren't tracked or easily managed

💡 The Solution:

• Bidirectional sync: Automatically sync between local files (.env.local, .env.prod) and Vercel environments
• Modern interactive interface: Beautiful CLI powered by @clack/prompts with individual action selection
• Safety first: Multiple confirmation prompts, smart exclusion lists, and system variable filtering
• Developer-friendly: Both CLI commands and TypeScript library for automation
• Smart detection: Automatically detects differences and suggests specific actions
• Flexible workflows: Choose individual actions per variable or batch operations

🔧 How It Works:

1. Connects to your Vercel project using the official Vercel CLI
2. Compares your local environment files with Vercel's environment variables
3. Shows differences in an easy-to-understand format
4. Lets you choose what to sync, add, update, or delete
5. Applies changes safely with confirmation prompts
6. Reports results so you know exactly what happened

👥 Perfect For:

• Developers who work with Vercel deployments
• Teams that need consistent environment setups
• DevOps automation and CI/CD pipelines
• Projects with multiple environments (dev, staging, prod)
• Anyone tired of manually managing environment variables

🚀 Features

• Two-way sync between local .env files and Vercel environments
• Individual action selection - choose specific actions per variable (add, update, pull, delete)
• Interactive deletion with local file cleanup options and safety checks
• Modern CLI interface powered by @clack/prompts with beautiful, intuitive prompts
• Smart system variable filtering - automatically excludes Vercel system variables
• Library modules for programmatic usage with full TypeScript support
• Environment-specific operations (development/production)
• Multiple confirmation levels with retry options and graceful cancellation
• Flexible sync modes - interactive (per-variable) or auto (batch) modes

📋 Prerequisites

Before using this library, you need to set up Vercel CLI and authenticate:

1. Install Vercel CLI

npm i -g vercel

2. Login to Vercel

vercel login

3. Link your project

Navigate to your project directory and link it to your Vercel project:

vercel link

This will create a .vercel folder in your project with the necessary configuration.

4. Verify setup

Test that everything is working:

vercel env ls development
vercel env ls production

🛠️ Installation

As a CLI tool (global):

npm install -g @pidchashyi/vercel-env

✨ Global installation gives you easier commands: After global installation, you can use the shorter vercel-env command directly:

# Easy commands (after global install)
vercel-env --sync           # Instead of npx @pidchashyi/vercel-env --sync
vercel-env --delete         # Instead of npx @pidchashyi/vercel-env --delete
vercel-env --sync --dev     # Instead of npx @pidchashyi/vercel-env --sync --dev
vercel-env --delete --prod  # Instead of npx @pidchashyi/vercel-env --delete --prod

As a library (local):

npm install @pidchashyi/vercel-env
# or
yarn add @pidchashyi/vercel-env
# or
bun add @pidchashyi/vercel-env

Note: The library now uses @clack/prompts instead of inquirer for a modern, beautiful CLI experience.

🏃‍♂️ CLI Usage

Sync environments

# If installed globally (easier):
vercel-env --sync                    # Interactive mode - choose everything
vercel-env --sync --dev              # Sync development only (interactive)
vercel-env --sync --prod             # Sync production only (interactive)
vercel-env --sync --dev --auto       # Auto sync development (with confirmation)
vercel-env --sync --auto             # Auto sync both environments

# If installed locally (using npx):
npx @pidchashyi/vercel-env --sync         # Interactive mode - choose everything
npx @pidchashyi/vercel-env --sync --dev   # Sync development only (interactive)
npx @pidchashyi/vercel-env --sync --prod  # Sync production only (interactive)
npx @pidchashyi/vercel-env --sync --dev --auto  # Auto sync development
npx @pidchashyi/vercel-env --sync --auto  # Auto sync both environments

Delete environment variables

# If installed globally (easier):
vercel-env --delete                  # Interactive deletion (recommended)
vercel-env --delete --dev            # Delete from development
vercel-env --delete --prod           # Delete from production

# If installed locally (using npx):
npx @pidchashyi/vercel-env --delete       # Interactive deletion (recommended)
npx @pidchashyi/vercel-env --delete --dev # Delete from development
npx @pidchashyi/vercel-env --delete --prod # Delete from production

💡 New Features:

• Exit option: "❌ Exit - Cancel deletion and exit" option for safe cancellation
• Local cleanup: Option to also delete variables from local files (.env.local, .env.prod)
• Retry on "No": If you decline a deletion, you can go back and choose different actions
• System variable filtering: Automatically excludes Vercel system variables from deletion

📚 Library Usage

You can use this library in two ways:

1. Import as Library Modules

import { syncEnvs, deleteEnvs } from '@pidchashyi/vercel-env';

// Interactive sync (default)
await syncEnvs();

// Auto sync specific environments
await syncEnvs({
  environments: ['development'],
  mode: 'auto'
});

// Delete environment variables
await deleteEnvs({
  environments: ['development']
});

2. Run Modules Directly with Bun

You can also run the individual module files directly:

# Run sync module directly
bun node_modules/@pidchashyi/vercel-env/src/actions/sync.ts

# Run delete module directly  
bun node_modules/@pidchashyi/vercel-env/src/actions/delete.ts

# Or if installed globally
bun ~/.bun/install/global/node_modules/@pidchashyi/vercel-env/src/actions/sync.ts
bun ~/.bun/install/global/node_modules/@pidchashyi/vercel-env/src/actions/delete.ts

3. Local Development (if you have the source)

# Clone and run directly from source
git clone <repository-url>
cd vercel-env

# Run sync module
bun src/actions/sync.ts

# Run delete module  
bun src/actions/delete.ts

# With command line arguments
bun src/actions/sync.ts --dev --auto
bun src/actions/delete.ts --interactive

4. Using NPM Scripts (after installation)

The package includes convenient npm scripts:

# Basic operations
npm run sync          # Interactive sync
npm run delete        # Interactive delete

# Environment-specific operations  
npm run sync:dev      # Auto sync development
npm run sync:prod     # Interactive sync production
npm run delete:dev    # Delete from development
npm run delete:prod   # Delete from production

🔧 Configuration

The library works with the following local files:

• Development: .env.local ↔ Vercel development environment
• Production: .env.prod ↔ Vercel production environment

Excluded Variables

System variables are automatically excluded from sync and deletion operations to prevent accidental removal of critical Vercel functionality:

All environments:

• VERCEL_OIDC_TOKEN - System-generated OIDC token
• VERCEL_URL - Vercel system variable
• VERCEL_ENV - Vercel system variable
• VERCEL_REGION - Vercel system variable

Production only:

• NX_DAEMON - NX build system variable
• TURBO_CACHE - Turborepo cache variable
• TURBO_DOWNLOAD_LOCAL_ENABLED - Turborepo download setting
• TURBO_REMOTE_ONLY - Turborepo remote-only setting
• TURBO_RUN_SUMMARY - Turborepo run summary setting
• VERCEL - Vercel system flag
• VERCEL_TARGET_ENV - Vercel target environment

Note: These exclusions apply to both sync operations (preventing pull from Vercel) and deletion operations (preventing accidental system variable removal).

📦 Project Structure

src/
├── actions/
│   ├── delete.ts   # deleteEnvs module with @clack/prompts
│   └── sync.ts     # syncEnvs module with @clack/prompts
├── constants/
│   └── index.ts    # Configuration constants and exclusion lists
├── types/
│   └── index.ts    # TypeScript type definitions
├── cli.ts          # Main CLI interface
└── index.ts        # Library exports

🔄 How it works

Sync Process

1. Fetch environment variables from both local files and Vercel
2. Compare values and identify differences
3. Present individual choices for each variable conflict (add, update, pull, remove, or do nothing)
4. Confirm each action with descriptive prompts (e.g., "Add 'API_KEY' to Vercel development environment?")
5. Retry on decline - if you say "No", you can choose a different action
6. Apply changes and report success/failure for each operation

Delete Process

1. Fetch environment variables from selected Vercel environments (excluding system variables)
2. Display variables with their values and environments
3. Allow selection of variables to delete with "Exit" option at the top
4. Show selected variables in confirmation prompt for review
5. Ask about local cleanup - option to also delete from .env.local/.env.prod files
6. Retry on decline - if you say "No" to deletion, you can go back and select different variables
7. Execute deletions from Vercel and optionally local files, then report results

🎮 Interactive Features

Modern CLI Experience

The tool now uses @clack/prompts for a beautiful, modern CLI experience:

Sync Mode - Individual Action Selection

For each environment variable conflict, you get a dedicated prompt:

🔧 Choose action for variable "DATABASE_URL" (development):
│  ● ➕ Add to Vercel - "postgresql://localhost:5432/mydb"
│  ○ 🗑️ Remove from Local - Will delete from .env.local
│  ○ ⏭️ Do nothing with DATABASE_URL

Then confirmation with clear context:

🔧 ➕ Add "DATABASE_URL" to Vercel development environment?
│  ○ Yes / ● No

If you choose "No": You go back to the action selection - no need to start over!

Delete Mode - Enhanced Safety

Variable Selection with exit option at the top:

🗑️ Select environment variables to DELETE:
│  ◯ ❌ Exit - Cancel deletion and exit
│  ◯ 🔧 API_KEY (development)
│  ◯ 🚀 SECRET_TOKEN (production)
│  ◯ 🔧🚀 DATABASE_URL (development, production)

Confirmation shows exactly what will be deleted:

Are you absolutely sure you want to delete these variables?

1. 🔧 API_KEY (development)
2. 🚀 SECRET_TOKEN (production)

🚨 THIS ACTION CANNOT BE UNDONE! 🚨
│  ○ Yes / ● No

Local Cleanup Option:

Also delete these variables from local environment files (.env.local, .env.prod)?
│  ○ Yes / ● No

Key Benefits

• Individual control: Choose specific actions per variable
• Retry-friendly: Declining an action lets you choose differently
• Clear context: Descriptive prompts show exactly what will happen
• Safe defaults: Destructive actions default to "No"
• System protection: Automatically filters out Vercel system variables
• Graceful cancellation: Multiple exit points with friendly messages

🤝 Contributing

Contributions, issues, and feature requests are welcome!

📄 License

This project is licensed under the MIT License.

👏 Acknowledgments

• Vercel - For providing excellent deployment platform and CLI tools
• @clack/prompts - For beautiful, modern CLI prompts
• TypeScript - For excellent type safety and developer experience