envoy-cli

The envoy between your code and environment variable config - Never miss an environment variable again

---

📖 Table of Contents

• Why envoy-cli ?
• Features
• Installation
• Windows Users
• Quick Start
• Commands
  • init
  • check
  • sync
• Configuration
• Supported Patterns
• Examples
• CI/CD Integration
• Development
• Project Structure
• Contributing
• License

---

Why envoy-cli ?

Have you ever :

• Forgotten to add an environment variable to .env.example ?
• Left unused variables in your .env.example causing confusion ?
• Struggled to keep environment files in sync across your team ?
• Wanted to automate environment variable management in CI/CD ?

envoy-cli solves all of these problems by automatically scanning your codebase and keeping your environment files perfectly synchronized.

---

Features

• Automatic Detection : Scans your entire codebase for environment variable usage
• Smart Analysis : Identifies missing, unused, and properly synced variables
• Auto-Sync : Automatically synchronize .env.example with your actual code
• Multiple Patterns : Supports process.env, import.meta.env, Deno, PowerShell, and more...
• Type-Safe : Built with TypeScript for maximum reliability
• Fast : Efficient file scanning with configurable ignore patterns
• CI/CD Ready : Built-in support for continuous integration pipelines
• Smart Comments : Optionally add helpful comments showing where variables are used
• Beautiful Output : Color-coded, clear console output with Chalk

---

Installation

Global Installation (Recommended)

Install envoy-cli globally to use it in any project :

npm install -g envoy-cli

Local Installation (Project-Specific)

Install as a dev dependency in your project :

npm install --save-dev envoy-cli

Or with pnpm :

pnpm add -D envoy-cli

Or with yarn :

yarn add -D envoy-cli

---

Windows Users

Git Bash Compatibility

If you're using Git Bash on Windows and encounter issues running envoy-cli, this is due to a known compatibility issue between Git Bash (MinTTY) and Node.js CLI applications.

Quick Fix for Git Bash

Add this alias to your .bashrc:

# Open your .bashrc
nano ~/.bashrc

# Add this line at the end
alias envoy-cli='winpty envoy-cli.cmd'

# Save and reload
source ~/.bashrc

Now envoy-cli will work correctly in Git Bash!

Alternative: Use Native Windows Terminals

If you prefer not to use the alias, envoy-cli works perfectly in:

• ✅ PowerShell (Recommended)
• ✅ Windows Terminal
• ✅ Command Prompt (CMD)
• ✅ WSL (Windows Subsystem for Linux)

# PowerShell - No configuration needed
envoy-cli --version

Why Does This Happen?

Git Bash uses MinTTY, which doesn't natively handle Windows console applications. The winpty wrapper bridges this gap by properly routing stdin/stdout/stderr between MinTTY and Node.js.

Known Terminal Limitations

Git Bash Display Issues :

• Variable names with underscores may display as asterisks (_VAR shows as *VAR)
• Exit codes may differ from other terminals
• Solution : Use PowerShell, CMD, or Windows Terminal for accurate display

These are Git Bash (MinTTY) rendering quirks, not bugs in envoy-cli. All functionality works correctly across all terminals.

---

Quick Start

Get started in 3 simple steps :

# 1. Initialize envoy-cli in your project
envoy-cli init

# 2. Check your current environment variable status
envoy-cli check

# 3. Auto-fix any issues
envoy-cli sync --auto

---

Commands

init - Initialize Configuration

Initialize envoy-cli in your current project.

envoy-cli init

What it does :

• ✅ Validates that you're in a Node.js project (checks for package.json)
• ✅ Creates .env.example if it doesn't exist
• ✅ Generates .envoyrc.json configuration file with default settings
• ✅ Provides helpful next steps

Example Output :

Initializing envoy-cli configuration...

✓ Created .env.example
✓ .envoyrc.json file created successfully.
✓ envoy-cli has been successfully initialized in your project !

Next steps:
  • First step
  • Second step
  • Third step

---

check - Verify Environment Variables

Scan your codebase and check the status of all environment variables.

envoy-cli check

Options:

• --ci - Exit with code 1 if issues are found (perfect for CI/CD pipelines)

What it shows :

1. MISSING: Variables used in your code but not in .env.example

   • Shows the variable name
   • Shows first file and line where it's used
   • Shows total number of occurrences

2. UNUSED: Variables in .env.example but not used in your code

   • Helps identify outdated or unnecessary variables

3. SYNCED: Variables that are properly configured

   • Shows how many places each variable is used

Example Output :

Envoy - Check Environment Variables

Found 15 environment variables in code

MISSING in .env.example (3):
  ✗ API_KEY
    → First used in src/config.ts:12
    → Also used in 2 other locations
  ✗ DATABASE_URL
    → First used in src/db/connection.ts:5
  ✗ REDIS_URL
    → First used in src/cache/redis.ts:8

UNUSED in .env.example (1):
  ⚠ OLD_API_TOKEN
    → Not found in codebase

SYNCED (11):
  ✓ PORT
    → Used in 3 locations
  ✓ NODE_ENV
    → Used in 5 locations
  ...

💡 Run "envoy-cli sync --auto" to fix automatically

CI/CD Mode:

envoy-cli check --ci

Exits with code 1 if any missing or unused variables are found, failing your pipeline.

---

sync - Synchronize Variables

Synchronize your .env.example file with the variables actually used in your code.

envoy-cli sync [options]

Options:

• --auto - Automatically add missing variables to .env.example
• --remove - Automatically remove unused variables from .env.example
• --comments - Add helpful comments showing where variables are used

Examples :

# Add missing variables only
envoy-cli sync --auto

# Remove unused variables only
envoy-cli sync --remove

# Add missing and remove unused
envoy-cli sync --auto --remove

# Add missing with location comments
envoy-cli sync --auto --comments

With --comments enabled :

# Environment Variables

# Used in src/config.ts:12
# Also used in 2 other location(s)
API_KEY=

# Used in src/db/connection.ts:5
DATABASE_URL=

Example Output :

Starting synchronization process...

✓ Added API_KEY to .env.example
✓ Added DATABASE_URL to .env.example
✓ Added REDIS_URL to .env.example
⚠ Removed OLD_API_TOKEN from .env.example

✨ Synchronization complete !

---

Configuration

envoy-cli uses a .envoyrc.json file for configuration (created automatically by init).

Default Configuration

{
  "exclude": [
    "dist/**",
    "build/**",
    "coverage/**"
  ]
}

Available Options

Option	Type	Description	Default
exclude	string[]	Glob patterns to ignore during scanning	["dist/**", "build/**", "coverage/**"]

Custom Configuration Example

{
  "exclude": [
    "dist/**",
    "build/**",
    "coverage/**",
    "node_modules/**",
    ".git/**",
    "temp/**",
    "*.test.ts",
    "**/__tests__/**"
  ]
}

---

Supported Patterns

envoy-cli automatically detects environment variables in multiple formats :

Node.js - Traditional Access

// Direct access
const apiKey = process.env.API_KEY;

// Bracket notation
const dbUrl = process.env['DATABASE_URL'];
const token = process.env["API_TOKEN"];

Node.js - Modern Destructuring

// Simple destructuring
const { API_KEY } = process.env;

// Multiple variables
const { API_KEY, DATABASE_URL, PORT } = process.env;

// With renaming
const { API_KEY: apiKey, DATABASE_URL: dbUrl } = process.env;

// With default values
const { PORT = '3000', NODE_ENV = 'development' } = process.env;

// Mixed patterns
const {
    API_KEY: apiKey = 'default_key',
    DATABASE_URL,
    PORT = '3000',
    ...otherVars  // rest operator is ignored
} = process.env;

// With let/var (works too !)
let { REDIS_URL } = process.env;
var { CACHE_TTL } = process.env;

Template Literals

// In URLs
const apiUrl = `http://localhost:${process.env.PORT}/api`;

// In connection strings
const dbUrl = `postgresql://user:pass@${process.env.DB_HOST}:${process.env.DB_PORT}/mydb`;

// Multiple variables in one string
const url = `${process.env.PROTOCOL}://${process.env.HOST}:${process.env.PORT}`;

Vite / Frontend Frameworks

// Traditional Vite access
const apiUrl = import.meta.env.VITE_API_URL;
const mode = import.meta.env.VITE_MODE;

// Vite destructuring 
const { VITE_API_URL, VITE_MODE } = import.meta.env;

// Vite template literals 
const endpoint = `${import.meta.env.VITE_API_URL}/users`;

Deno

// Deno environment access
const apiKey = Deno.env.get('API_KEY');
const port = Deno.env.get('PORT');

PowerShell

# PowerShell environment variables
$apiKey = $env:API_KEY
$dbUrl = $env:DATABASE_URL

Supported File Extensions

envoy-cli scans these file types by default:

• .ts - TypeScript
• .tsx - TypeScript React
• .js - JavaScript
• .jsx - JavaScript React
• .mjs - ES Modules
• .cjs - CommonJS

---

📚 Examples

Example 1: Basic Project Setup

# Start a new project
mkdir my-app && cd my-app
npm init -y

# Install envoy-cli
npm install -D envoy-cli

# Initialize
npx envoy-cli init

# Your code uses some env variables
echo "const key = process.env.API_KEY;" > index.js

# Check status
npx envoy-cli check
# Output: MISSING in .env.example (1): API_KEY

# Auto-fix
npx envoy-cli sync --auto
# Output: ✓ Added API_KEY to .env.example

Example 2: Team Collaboration

# Team member A adds new feature using env variables
git pull
envoy-cli check
# Output: MISSING in .env.example (2): STRIPE_KEY, STRIPE_SECRET

# Sync and commit
envoy-cli sync --auto --comments
git add .env.example
git commit -m "Add Stripe environment variables"

# Team member B pulls changes
git pull
# .env.example is now up to date!

Example 3: Cleaning Up Old Variables

# After refactoring, check for unused variables
envoy-cli check
# Output: UNUSED in .env.example (5): OLD_API_KEY, DEPRECATED_URL, ...

# Remove unused variables
envoy-cli sync --remove
# Output: ⚠ Removed OLD_API_KEY from .env.example
#         ⚠ Removed DEPRECATED_URL from .env.example

Example 4: Adding to Package Scripts

Add envoy-cli checks to your package.json :

{
  "scripts": {
    "env:check": "envoy-cli check",
    "env:sync": "envoy-cli sync --auto --comments",
    "env:clean": "envoy-cli sync --remove",
    "pretest": "envoy-cli check --ci",
    "prepare": "envoy-cli check"
  }
}

Then use :

npm run env:check    # Check status
npm run env:sync     # Auto-fix with comments
npm run env:clean    # Remove unused

---

CI/CD Integration

GitHub Actions

Create .github/workflows/env-check.yml:

name: Environment Variables Check

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  env-check:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Check environment variables
        run: npx envoy-cli check --ci
      
      - name: Comment on PR (if check fails)
        if: failure() && github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'Environment variable check failed! Please run `envoy-cli sync --auto` and commit the changes.'
            })

GitLab CI

Add to .gitlab-ci.yml :

env-check:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx envoy-cli check --ci
  only:
    - merge_requests
    - main
    - develop

CircleCI

Add to .circleci/config.yml:

version: 2.1

jobs:
  env-check:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm ci
      - run: npx envoy-cli check --ci

workflows:
  version: 2
  build-and-test:
    jobs:
      - env-check

Pre-commit Hook (Husky)

Install Husky:

npm install -D husky
npx husky init

Create .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx envoy-cli check --ci

Now every commit will verify environment variables!

---

Development

Prerequisites

• Node.js >= 16.0.0
• npm, pnpm, or yarn

Setup Development Environment

# Clone the repository
git clone https://github.com/LeDevNovice/envoy-cli.git
cd envoy-cli

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Build the project
npm run build

# Run in development mode
npm run dev

Available Scripts

Script	Description
npm run build	Compile TypeScript to JavaScript
npm run dev	Watch mode for development
npm start	Run the compiled CLI
npm test	Run all tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Generate test coverage report

Running Locally

After building, you can test the CLI locally:

# Build first
npm run build

# Link globally
npm link

# Now you can use envoy-cli anywhere
cd /path/to/your/project
envoy-cli init

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

---

FAQ

Why doesn't envoy-cli work in Git Bash on Windows?

Git Bash uses MinTTY which has compatibility issues with Node.js CLI apps. See Windows Users section for the solution.

---

Contributing

Contributions are welcome ! Here's how you can help :

Reporting Bugs

1. Check if the bug has already been reported in Issues
2. If not, create a new issue with :
   • Clear title and description
   • Steps to reproduce
   • Expected vs actual behavior
   • Your environment (OS, Node version, etc...)

Suggesting Features

1. Open an issue with the enhancement label
2. Describe the feature and why it would be useful
3. Provide examples of how it would work

Submitting Pull Requests

1. Fork the repository
2. Create a new branch : git checkout -b feature/amazing-feature
3. Make your changes
4. Write or update tests
5. Ensure all tests pass : npm test
6. Commit your changes : git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Development Guidelines

• Write clear, descriptive commit messages
• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Keep PRs focused on a single feature/fix

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Built with Commander.js - CLI framework
• Styled with Chalk - Terminal string styling
• File globbing with glob - Pattern matching
• Tested with Vitest - Fast unit testing
• Inspired by the need for better environment variable management in team development projects

---

Support & Contact

• Bug Reports : GitHub Issues
• Twitter : @LeDevNovice

---

Star History

If you find this project useful, please consider giving it a star on GitHub !

---

Made with ❤️ by LeDevNovice

Never miss an environment variable again!