dotenv-diff 2.1.3 → 2.1.5

package/README.md

@@ -50,11 +50,11 @@ Use the `--ci` flag for automated environments. This enables strict mode where t
 
 And the `--example` option allows you to specify which `.env.example` file to compare against.
 
-### Use it in Github Actions:
+### Use it in Github Actions for at turborepo, Example:
 
 ```yaml
 - name: Check environment variables
-  run: dotenv-diff --scan-usage --example .env.example --ci
+  run: dotenv-diff --ci --scan-usage --show-unused --example .env.example --include-files \"./src/**/*,../../packages/**/*\" --ignore VITE_MODE,NODE_ENV
 ```
 
 You can also change the comparison file by using the `--example` flag to point to a different `.env.example` file. 
@@ -83,6 +83,42 @@ This will:
 - Also scan files in `../../packages`(like `packages/components/src/..`)
 - Ignore variables like VITE_MODE that you only use in special cases.
 
+## Automatic fixes with `--fix`
+
+Use the `--fix` flag to automatically fix missing keys in your `.env` and remove duplicate keys. 
+
+```bash
+dotenv-diff --fix
+```
+
+This will:
+- Add any missing keys from `.env.example` to your `.env` file with empty values
+- Remove duplicate keys in your `.env` file (keeping the last occurrence)
+
+## Use --fix with scan-usage
+
+You can also combine `--fix` with `--scan-usage` to automatically add any missing keys that are used in your code but not defined in your `.env` file:
+
+```bash
+dotenv-diff --scan-usage --fix
+```
+
+Using `--fix`with `--scan-usage` will not detect duplicate keys, it will only add missing keys.
+
+### Example workflow
+
+1. You add `process.env.NEW_API_KEY` in your code.
+2. You run `dotenv-diff --scan-usage --fix`.
+3. The tool automatically adds `NEW_API_KEY=` to your `.env` file.
+
+## Scan your codebase for environment variables and add it directly to .env.example?
+
+```bash
+dotenv-diff --scan-usage --example .env.example --fix
+```
+
+This scans your codebase for environment variable usage and adds any missing keys directly to your `.env.example` file with empty values.
+
 ## Show unused variables
 
 Use `--show-unused` together with `--scan-usage` to list variables that are defined in `.env` but never used in your codebase:
@@ -158,6 +194,16 @@ You can output the results in JSON format using the `--json` option:
 dotenv-diff --json
 ```
 
+## Disable colored output
+
+By default, `dotenv-diff` uses colored output to enhance readability.
+
+If you prefer plain text output, you can disable colored output using the `--no-color` option:
+
+```bash
+dotenv-diff --no-color
+```
+
 ## Compare specific files
 
 Override the autoscan and compare exactly two files:

package/dist/src/cli/program.js

@@ -11,7 +11,9 @@ export function createProgram() {
         .option('--allow-duplicates', 'Do not warn about duplicate keys in .env* files')
         .option('--ignore <keys>', 'Comma-separated list of keys to ignore')
         .option('--ignore-regex <pattern>', 'Regex pattern to ignore matching keys')
+        .option('--fix', 'Automatically fix common issues: remove duplicates, add missing keys')
         .option('--json', 'Output results in JSON format')
+        .option('--no-color', 'Disable colored output')
         .option('--only <list>', 'Comma-separated categories to only run (missing,extra,empty,mismatch,duplicate,gitignore)')
         .option('--scan-usage', 'Scan codebase for environment variable usage')
         .option('--include-files <patterns>', '[requires --scan-usage] Comma-separated file patterns to ADD to default scan patterns (extends default)')

package/dist/src/cli/run.js

@@ -11,6 +11,9 @@ export async function run(program) {
     program.parse(process.argv);
     const raw = program.opts();
     const opts = normalizeOptions(raw);
+    if (opts.noColor) {
+        chalk.level = 0; // disable colors globally
+    }
     if (opts.scanUsage) {
         const envPath = opts.envFlag || (fs.existsSync('.env') ? '.env' : undefined);
         const { exitWithError } = await scanUsage({
@@ -21,6 +24,7 @@ export async function run(program) {
             ignoreRegex: opts.ignoreRegex,
             examplePath: opts.exampleFlag || undefined,
             envPath,
+            fix: opts.fix,
             json: opts.json,
             showUnused: opts.showUnused,
             showStats: opts.showStats,
@@ -93,6 +97,7 @@ export async function run(program) {
         checkValues: opts.checkValues,
         cwd: opts.cwd,
         allowDuplicates: opts.allowDuplicates,
+        fix: opts.fix,
         json: opts.json,
         ignore: opts.ignore,
         ignoreRegex: opts.ignoreRegex,

package/dist/src/commands/compare.d.ts

@@ -7,6 +7,7 @@ export declare function compareMany(pairs: Array<{
     checkValues: boolean;
     cwd: string;
     allowDuplicates?: boolean;
+    fix?: boolean;
     json?: boolean;
     ignore: string[];
     ignoreRegex: RegExp[];

package/dist/src/commands/compare.js

@@ -6,6 +6,7 @@ import { diffEnv } from '../lib/diffEnv.js';
 import { warnIfEnvNotIgnored } from '../services/git.js';
 import { findDuplicateKeys } from '../services/duplicates.js';
 import { filterIgnoredKeys } from '../core/filterIgnoredKeys.js';
+import { applyFixes } from '../core/fixEnv.js';
 export async function compareMany(pairs, opts) {
     let exitWithError = false;
     const onlySet = opts.only?.length
@@ -162,7 +163,7 @@ export async function compareMany(pairs, opts) {
             exitWithError = true;
         }
         if (!opts.json) {
-            if (filtered.missing.length) {
+            if (filtered.missing.length && !opts.fix) {
                 console.log(chalk.red('  ❌ Missing keys:'));
                 filtered.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
             }
@@ -180,6 +181,40 @@ export async function compareMany(pairs, opts) {
             }
             console.log();
         }
+        if (!opts.json && !opts.fix) {
+            if (filtered.missing.length ||
+                filtered.duplicatesEnv.length ||
+                filtered.duplicatesEx.length) {
+                console.log(chalk.gray('💡 Tip: Run with `--fix` to automatically add missing keys and remove duplicates.'));
+                console.log();
+            }
+        }
+        if (opts.fix) {
+            const { changed, result } = applyFixes({
+                envPath,
+                examplePath,
+                missingKeys: filtered.missing,
+                duplicateKeys: dupsEnv.map((d) => d.key),
+            });
+            if (!opts.json) {
+                if (changed) {
+                    console.log(chalk.green('  ✅ Auto-fix applied:'));
+                    if (result.removedDuplicates.length) {
+                        console.log(chalk.green(`      - Removed ${result.removedDuplicates.length} duplicate keys from ${envName}: ${result.removedDuplicates.join(', ')}`));
+                    }
+                    if (result.addedEnv.length) {
+                        console.log(chalk.green(`      - Added ${result.addedEnv.length} missing keys to ${envName}: ${result.addedEnv.join(', ')}`));
+                    }
+                    if (result.addedExample.length) {
+                        console.log(chalk.green(`      - Synced ${result.addedExample.length} keys to ${exampleName}: ${result.addedExample.join(', ')}`));
+                    }
+                }
+                else {
+                    console.log(chalk.green('  ✅ Auto-fix applied: no changes needed.'));
+                }
+                console.log();
+            }
+        }
         opts.collect?.(entry);
     }
     return { exitWithError };

package/dist/src/commands/scanUsage.d.ts

@@ -2,6 +2,7 @@ import { type ScanOptions } from '../services/codeBaseScanner.js';
 export interface ScanUsageOptions extends ScanOptions {
     envPath?: string;
     examplePath?: string;
+    fix?: boolean;
     json: boolean;
     showUnused: boolean;
     showStats: boolean;

package/dist/src/commands/scanUsage.js

@@ -64,6 +64,44 @@ export async function scanUsage(opts) {
             }
         }
     }
+    // Store fix information for later display
+    let fixApplied = false;
+    let fixedKeys = [];
+    if (opts.fix && compareFile) {
+        const missingKeys = scanResult.missing;
+        if (missingKeys.length > 0) {
+            const envFilePath = compareFile.path;
+            const exampleFilePath = opts.examplePath
+                ? resolveFromCwd(opts.cwd, opts.examplePath)
+                : null;
+            // Append missing keys to .env
+            const content = fs.readFileSync(envFilePath, 'utf-8');
+            const newContent = content +
+                (content.endsWith('\n') ? '' : '\n') +
+                missingKeys.map((k) => `${k}=`).join('\n') +
+                '\n';
+            fs.writeFileSync(envFilePath, newContent);
+            // Append to .env.example if it exists
+            if (exampleFilePath && fs.existsSync(exampleFilePath)) {
+                const exContent = fs.readFileSync(exampleFilePath, 'utf-8');
+                const existingExKeys = new Set(exContent
+                    .split('\n')
+                    .map((l) => l.trim().split('=')[0])
+                    .filter(Boolean));
+                const newKeys = missingKeys.filter((k) => !existingExKeys.has(k));
+                if (newKeys.length) {
+                    const newExContent = exContent +
+                        (exContent.endsWith('\n') ? '' : '\n') +
+                        newKeys.join('\n') +
+                        '\n';
+                    fs.writeFileSync(exampleFilePath, newExContent);
+                }
+            }
+            fixApplied = true;
+            fixedKeys = missingKeys;
+            scanResult.missing = [];
+        }
+    }
     // Prepare JSON output
     if (opts.json) {
         const jsonOutput = createJsonOutput(scanResult, opts, comparedAgainst, Object.keys(envVariables).length);
@@ -71,7 +109,23 @@ export async function scanUsage(opts) {
         return { exitWithError: scanResult.missing.length > 0 };
     }
     // Console output
-    return outputToConsole(scanResult, opts, comparedAgainst);
+    const result = outputToConsole(scanResult, opts, comparedAgainst);
+    // Show fix message at the bottom (after all other output)
+    if (fixApplied && !opts.json) {
+        console.log(chalk.green('✅ Auto-fix applied (scan mode):'));
+        if (compareFile) {
+            console.log(chalk.green(`   - Added ${fixedKeys.length} missing keys to ${compareFile.name}: ${fixedKeys.join(', ')}`));
+        }
+        if (opts.examplePath) {
+            console.log(chalk.green(`   - Synced ${fixedKeys.length} keys to ${path.basename(opts.examplePath)}`));
+        }
+        console.log();
+    }
+    else if (opts.fix && !fixApplied && !opts.json) {
+        console.log(chalk.green('✅ Auto-fix applied: no changes needed.'));
+        console.log();
+    }
+    return result;
 }
 /**
  * Determines which file to use for comparison based on provided options
@@ -227,5 +281,9 @@ function outputToConsole(scanResult, opts, comparedAgainst) {
         }
         console.log();
     }
+    if (scanResult.missing.length > 0 && !opts.json && !opts.fix) {
+        console.log(chalk.gray('💡 Tip: Run with `--fix` to add these missing keys to your .env file automatically.'));
+        console.log();
+    }
     return { exitWithError };
 }

package/dist/src/config/options.js

@@ -22,6 +22,7 @@ export function normalizeOptions(raw) {
     const isCiMode = Boolean(raw.ci);
     const isYesMode = Boolean(raw.yes);
     const allowDuplicates = Boolean(raw.allowDuplicates);
+    const fix = Boolean(raw.fix);
     const json = Boolean(raw.json);
     const onlyParsed = parseCategories(raw.only, '--only');
     const only = onlyParsed.length ? onlyParsed : undefined;
@@ -53,6 +54,7 @@ export function normalizeOptions(raw) {
         isCiMode,
         isYesMode,
         allowDuplicates,
+        fix,
         json,
         envFlag,
         exampleFlag,

package/dist/src/config/types.d.ts

@@ -5,6 +5,7 @@ export type Options = {
     isCiMode: boolean;
     isYesMode: boolean;
     allowDuplicates: boolean;
+    fix: boolean;
     json: boolean;
     envFlag: string | null;
     exampleFlag: string | null;
@@ -18,12 +19,14 @@ export type Options = {
     showUnused: boolean;
     showStats: boolean;
     files?: string[];
+    noColor?: boolean;
 };
 export type RawOptions = {
     checkValues?: boolean;
     ci?: boolean;
     yes?: boolean;
     allowDuplicates?: boolean;
+    fix?: boolean;
     json?: boolean;
     env?: string;
     example?: string;

package/dist/src/core/fixEnv.d.ts

@@ -0,0 +1,13 @@
+export declare function applyFixes({ envPath, examplePath, missingKeys, duplicateKeys, }: {
+    envPath: string;
+    examplePath: string;
+    missingKeys: string[];
+    duplicateKeys: string[];
+}): {
+    changed: boolean;
+    result: {
+        removedDuplicates: string[];
+        addedEnv: string[];
+        addedExample: string[];
+    };
+};

package/dist/src/core/fixEnv.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+export function applyFixes({ envPath, examplePath, missingKeys, duplicateKeys, }) {
+    const result = {
+        removedDuplicates: [],
+        addedEnv: [],
+        addedExample: [],
+    };
+    // --- Remove duplicates ---
+    if (duplicateKeys.length) {
+        const lines = fs.readFileSync(envPath, 'utf-8').split('\n');
+        const seen = new Set();
+        const newLines = [];
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            const match = line.match(/^\s*([\w.-]+)\s*=/);
+            if (match) {
+                const key = match[1];
+                if (duplicateKeys.includes(key)) {
+                    if (seen.has(key))
+                        continue; // skip duplicate
+                    seen.add(key);
+                }
+            }
+            newLines.unshift(line);
+        }
+        fs.writeFileSync(envPath, newLines.join('\n'));
+        result.removedDuplicates = duplicateKeys; // save all dupe keys
+    }
+    // --- Add missing keys to .env ---
+    if (missingKeys.length) {
+        const content = fs.readFileSync(envPath, 'utf-8');
+        const newContent = content +
+            (content.endsWith('\n') ? '' : '\n') +
+            missingKeys.map((k) => `${k}=`).join('\n') +
+            '\n';
+        fs.writeFileSync(envPath, newContent);
+        result.addedEnv = missingKeys; // save all missing keys
+    }
+    // --- Add missing keys to .env.example ---
+    if (examplePath && missingKeys.length) {
+        const exContent = fs.readFileSync(examplePath, 'utf-8');
+        const existingExKeys = new Set(exContent
+            .split('\n')
+            .map((l) => l.trim().split('=')[0])
+            .filter(Boolean));
+        const newExampleKeys = missingKeys.filter((k) => !existingExKeys.has(k));
+        if (newExampleKeys.length) {
+            const newExContent = exContent +
+                (exContent.endsWith('\n') ? '' : '\n') +
+                newExampleKeys.join('\n') +
+                '\n';
+            fs.writeFileSync(examplePath, newExContent);
+            result.addedExample = newExampleKeys; // save all keys actually added
+        }
+    }
+    const changed = result.removedDuplicates.length > 0 ||
+        result.addedEnv.length > 0 ||
+        result.addedExample.length > 0;
+    return { changed, result };
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dotenv-diff",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "type": "module",
-  "description": "A CLI tool to find differences between .env and .env.example / .env.* files. And optionally scan your codebase to find out which environment variables are actually used in your code.",
+  "description": "Find differences between .env and .env.example / .env.* files. And optionally scan your codebase to find environment variables in use.",
   "bin": {
     "dotenv-diff": "dist/bin/dotenv-diff.js"
   },