@dotenvx/dotenvx 1.65.3 → 1.66.0

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.65.3...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.66.0...main)
+
+## [1.66.0](https://github.com/dotenvx/dotenvx/compare/v1.65.3...v1.66.0) (2026-05-13)
+
+### Added
+
+* Add `dotenvx doctor` ([#815](https://github.com/dotenvx/dotenvx/pull/815))
 
 ## [1.65.3](https://github.com/dotenvx/dotenvx/compare/v1.65.2...v1.65.3) (2026-05-13)
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.65.3",
+  "version": "1.66.0",
   "name": "@dotenvx/dotenvx",
   "description": "secrets for agents–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/cli/actions/doctor.js

@@ -0,0 +1,22 @@
+const { logger } = require('./../../shared/logger')
+const main = require('./../../lib/main')
+
+function doctor (directory = '.') {
+  logger.debug(`directory: ${directory}`)
+
+  const findings = main.doctor(directory)
+  logger.debug(`findings: ${JSON.stringify(findings)}`)
+
+  if (findings.length === 0) {
+    logger.info('no dotenv loaders found')
+    return
+  }
+
+  logger.warn(`found ${findings.length} possible dotenv loader${findings.length === 1 ? '' : 's'}`)
+
+  for (const finding of findings) {
+    logger.info(`│ ${finding.filepath}:${finding.line}: ${finding.code}`)
+  }
+}
+
+module.exports = doctor

package/src/cli/dotenvx.js

@@ -186,6 +186,14 @@ program.command('ls')
     return require('./actions/ls').apply(this, args)
   })
 
+// dotenvx doctor
+program.command('doctor', { hidden: true })
+  .description('scan for dotenv loaders')
+  .argument('[directory]', 'directory to scan', '.')
+  .action(function (...args) {
+    return require('./actions/doctor').apply(this, args)
+  })
+
 // dotenvx login
 program.command('login')
   .description('log in to unlock ⛨ ARMORED KEYS ✦ BETA')

package/src/lib/main.d.ts

@@ -363,6 +363,23 @@ export function ls(
   excludeEnvFile: string | string[]
 ): string[];
 
+export type DoctorFinding = {
+  lang: string;
+  filepath: string;
+  line: number;
+  code: string;
+  msg: string;
+};
+
+/**
+ * Scan code for dotenv loaders that can conflict with dotenvx.
+ *
+ * @param directory - directory to scan
+ */
+export function doctor(
+  directory: string
+): DoctorFinding[];
+
 export type GenExampleOutput = {
   envExampleFile: string;
   envFile: string | string[];

package/src/lib/main.js

@@ -7,6 +7,7 @@ const { getColor, bold } = require('./../shared/colors')
 
 // services
 const Ls = require('./services/ls')
+const Doctor = require('./services/doctor')
 const Run = require('./services/run')
 const Sets = require('./services/sets')
 const Get = require('./services/get')
@@ -298,6 +299,10 @@ const ls = function (directory, envFile, excludeEnvFile) {
   return new Ls(directory, envFile, excludeEnvFile).run()
 }
 
+const doctor = function (directory) {
+  return new Doctor(directory).run()
+}
+
 /** @type {import('./main').genexample} */
 const genexample = function (directory, envFile) {
   return new Genexample(directory, envFile).run()
@@ -326,6 +331,7 @@ module.exports = {
   set,
   get,
   ls,
+  doctor,
   keypair,
   genexample,
   // expose for libs depending on @dotenvx/dotenvx - like dotenvx-ops

package/src/lib/services/doctor.js

@@ -0,0 +1,93 @@
+const { fdir: Fdir } = require('fdir')
+const path = require('path')
+const picomatch = require('picomatch')
+const fsx = require('./../helpers/fsx')
+
+const patterns = [
+  { lang: 'Python', file: /\.py$/, match: /load_dotenv\s*\([^)]*\)/, msg: 'found python-dotenv load call' },
+  { lang: 'Python', file: /\.py$/, match: /dotenv_values\s*\([^)]*\)/, msg: 'found python-dotenv values call' },
+
+  { lang: 'Node', file: /\.(js|cjs|mjs|ts)$/, match: /require\(['"]dotenv['"]\)\.config\s*\([^)]*\)/, msg: 'found dotenv config require call' },
+  { lang: 'Node', file: /\.(js|cjs|mjs|ts)$/, match: /import\s+['"]dotenv\/config['"]/, msg: 'found dotenv/config import' },
+  { lang: 'Node', file: /\.(js|cjs|mjs|ts)$/, match: /dotenv\.config\s*\([^)]*\)/, msg: 'found dotenv config call' },
+
+  { lang: 'Ruby', file: /\.rb$/, match: /Dotenv\.(load|overload)\s*\([^)]*\)/, msg: 'found ruby dotenv load call' },
+  { lang: 'Go', file: /\.go$/, match: /godotenv\.(Load|Overload)\s*\([^)]*\)/, msg: 'found godotenv load call' },
+  { lang: 'PHP', file: /\.php$/, match: /Dotenv\\Dotenv::create\w*\s*\([^)]*\)/, msg: 'found vlucas/phpdotenv loader' },
+
+  { lang: 'Rust', file: /\.rs$/, match: /dotenvy?::dotenv\s*\([^)]*\)/, msg: 'found Rust dotenv load call' },
+  { lang: 'Java', file: /\.java$/, match: /Dotenv\.(load|configure)\s*\([^)]*\)/, msg: 'found java-dotenv load call' },
+  { lang: 'Kotlin', file: /\.kt$/, match: /Dotenv\.(load|configure)\s*\([^)]*\)/, msg: 'found java-dotenv load call' },
+  { lang: '.NET', file: /\.(cs|fs|vb)$/, match: /(?:DotNetEnv\.)?Env\.Load\s*\([^)]*\)/, msg: 'found DotNetEnv load call' }
+]
+
+class Doctor {
+  constructor (directory = './') {
+    this.cwd = path.resolve(directory)
+    this.ignore = [
+      '**/node_modules/**',
+      '**/.git/**',
+      '**/vendor/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/coverage/**',
+      '**/.next/**'
+    ]
+    this.exclude = picomatch(this.ignore)
+  }
+
+  run () {
+    const findings = []
+
+    for (const filepath of this._filepaths()) {
+      findings.push(...this._scanFile(filepath))
+    }
+
+    return findings
+  }
+
+  _filepaths () {
+    return new Fdir()
+      .withRelativePaths()
+      .exclude((dir, filepath) => this._ignored(filepath))
+      .filter((filepath) => this._patternsFor(filepath).length > 0)
+      .crawl(this.cwd)
+      .sync()
+      .sort()
+  }
+
+  _scanFile (relativeFilepath) {
+    const src = fsx.readFileXSync(path.join(this.cwd, relativeFilepath))
+    const lines = src.split(/\r?\n/)
+    const findings = []
+
+    lines.forEach((line, index) => {
+      for (const pattern of this._patternsFor(relativeFilepath)) {
+        if (pattern.match.test(line)) {
+          const match = line.match(pattern.match)
+          findings.push({
+            lang: pattern.lang,
+            filepath: relativeFilepath,
+            line: index + 1,
+            code: match[0].trim(),
+            msg: pattern.msg
+          })
+        }
+      }
+    })
+
+    return findings
+  }
+
+  _patternsFor (filepath) {
+    return patterns.filter(pattern => pattern.file.test(filepath))
+  }
+
+  _ignored (filepath) {
+    return this.exclude(filepath)
+  }
+}
+
+Doctor.patterns = patterns
+
+module.exports = Doctor