@dotenvx/dotenvx 1.65.3 → 1.67.0

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 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.67.0...main)
+
+## [1.67.0](https://github.com/dotenvx/dotenvx/compare/v1.66.0...v1.67.0) (2026-05-21)
+
+### Added
+
+* Add prompt for local storage vs armored storage ([#819](https://github.com/dotenvx/dotenvx/pull/819))
+
+## [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.67.0",
   "name": "@dotenvx/dotenvx",
   "description": "secrets for agents–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -46,6 +46,7 @@
     "commander": "^11.1.0",
     "dotenv": "^17.2.1",
     "eciesjs": "^0.4.10",
+    "enquirer": "^2.4.1",
     "execa": "^5.1.1",
     "fdir": "^6.2.0",
     "ignore": "^5.3.0",

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/actions/encrypt.js

@@ -6,8 +6,63 @@ const Encrypt = require('./../../lib/services/encrypt')
 const catchAndLog = require('../../lib/helpers/catchAndLog')
 const localDisplayPath = require('../../lib/helpers/localDisplayPath')
 const createSpinner = require('../../lib/helpers/createSpinner')
+const prompts = require('../../lib/helpers/prompts')
 const Session = require('../../db/session')
 
+function keypairSpinnerHooks (spinner) {
+  let stoppedForOps = false
+
+  return {
+    onStderr: () => {
+      if (spinner && !stoppedForOps) {
+        spinner.stop()
+        stoppedForOps = true
+      }
+    },
+    after: () => {
+      if (spinner && stoppedForOps) {
+        spinner.start('encrypting')
+        stoppedForOps = false
+      }
+    }
+  }
+}
+
+function keyStorageSelector (spinner) {
+  let selected
+
+  return async function selectKeyStorage () {
+    if (selected) return selected
+
+    if (spinner) spinner.stop()
+    selected = await prompts.select({
+      message: 'Select key storage',
+      choices: [
+        { name: 'Local (.env.keys)', value: 'local' },
+        { name: 'Armored ⛨', value: 'armored' }
+      ]
+    }, {
+      input: process.stdin,
+      output: process.stderr
+    })
+    if (spinner) spinner.start('encrypting')
+
+    return selected
+  }
+}
+
+function encryptOptions (spinner, noOps) {
+  const options = {
+    keypairHooks: keypairSpinnerHooks(spinner)
+  }
+
+  if (!noOps) {
+    options.selectKeyStorage = keyStorageSelector(spinner)
+  }
+
+  return options
+}
+
 async function encrypt () {
   const options = this.opts()
   const spinner = await createSpinner({ ...options, text: 'encrypting' })
@@ -16,14 +71,14 @@ async function encrypt () {
 
   const sesh = new Session()
   const envs = this.envs
-  const noOps = options.ops === false || (await sesh.noOps())
+  const noOps = options.ops === false || (!options.token && (await sesh.noOps()))
   const noCreate = options.create === false
 
   // stdout - should not have a try so that exit codes can surface to stdout
   if (options.stdout) {
     const {
       processedEnvs
-    } = await new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, noOps, noCreate).run()
+    } = await new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, noOps, noCreate, options.token, encryptOptions(spinner, noOps)).run()
     if (spinner) spinner.stop()
     for (const processedEnv of processedEnvs) {
       console.log(processedEnv.envSrc)
@@ -35,7 +90,7 @@ async function encrypt () {
         processedEnvs,
         changedFilepaths,
         unchangedFilepaths
-      } = await new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, noOps, noCreate).run()
+      } = await new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, noOps, noCreate, options.token, encryptOptions(spinner, noOps)).run()
 
       for (const processedEnv of processedEnvs) {
         logger.verbose(`encrypting ${processedEnv.envFilepath} (${processedEnv.filepath})`)

package/src/cli/actions/run.js

@@ -54,11 +54,13 @@ async function run () {
       readableFilepaths,
       uniqueInjectedKeys
     } = await new Run(envs, options.overload, process.env, options.envKeysFile, noOps, {
-      beforeOpsKeypair: () => {
-        if (spinner) spinner.start('retrieving')
-      },
-      afterOpsKeypair: () => {
-        if (spinner) spinner.start('injecting')
+      keypairHooks: {
+        before: () => {
+          if (spinner) spinner.start('retrieving')
+        },
+        after: () => {
+          if (spinner) spinner.start('injecting')
+        }
       }
     }).run()
 

package/src/cli/dotenvx.js

@@ -126,6 +126,7 @@ program.command('encrypt')
   .option('-k, --key <keys...>', 'keys(s) to encrypt (default: all keys in file)')
   .option('-ek, --exclude-key <excludeKeys...>', 'keys(s) to exclude from encryption (default: none)')
   .option('--stdout', 'send to stdout')
+  .option('--token <token>', 'set Ops token')
   .option('--no-create', 'do not create .env file(s) when missing')
   .option('--no-ops', 'disable dotenvx-ops features')
   .action(function (...args) {
@@ -186,6 +187,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/extensions/ops.js

@@ -40,10 +40,13 @@ class Ops {
 
     const args = ['keypair']
     if (options.noSpinner) args.push('--no-spinner')
+    if (options.token) args.push('--token', options.token)
     if (publicKey) args.push(publicKey)
 
     try {
-      return JSON.parse(await this._execInteractive(binary, args))
+      return JSON.parse(await this._execInteractive(binary, args, {
+        onStderr: options.onStderr
+      }))
     } catch (_e) {
       return {}
     }
@@ -57,6 +60,7 @@ class Ops {
 
     const args = ['keypair']
     if (options.noSpinner) args.push('--no-spinner')
+    if (options.token) args.push('--token', options.token)
     if (publicKey) args.push(publicKey)
 
     try {
@@ -106,17 +110,26 @@ class Ops {
     return childProcess.execFileSync(binary, args).toString().trim()
   }
 
-  _execInteractive (binary, args) {
+  _execInteractive (binary, args, options = {}) {
     return new Promise((resolve, reject) => {
       const spawnOptions = {
-        stdio: ['inherit', 'pipe', 'inherit']
+        stdio: ['inherit', 'pipe', 'pipe']
       }
       const subprocess = childProcess.spawn(binary, args, spawnOptions)
       let stdout = ''
+      let sawStderr = false
 
       subprocess.stdout.on('data', (data) => {
         stdout += data.toString()
       })
+      subprocess.stderr.on('data', (data) => {
+        if (!sawStderr) {
+          sawStderr = true
+          if (options.onStderr) options.onStderr()
+        }
+
+        process.stderr.write(data)
+      })
       subprocess.on('error', reject)
       subprocess.on('close', (code) => {
         if (code !== 0) {

package/src/lib/helpers/cryptography/opsKeypair.js

@@ -1,17 +1,23 @@
 const Ops = require('../../extensions/ops')
 
 async function opsKeypair (existingPublicKey, options = {}) {
-  if (options.beforeOpsKeypair) await options.beforeOpsKeypair()
+  const hooks = options.hooks || {}
+  if (hooks.before) await hooks.before()
+
+  const keypairOptions = {}
+  if (options.token) keypairOptions.token = options.token
+  if (hooks.onStderr) keypairOptions.onStderr = hooks.onStderr
+  if (hooks.before || hooks.onStderr || hooks.after) keypairOptions.noSpinner = true
 
   let kp
   try {
-    if (options.beforeOpsKeypair || options.afterOpsKeypair) {
-      kp = await new Ops().keypair(existingPublicKey, { noSpinner: true })
+    if (Object.keys(keypairOptions).length > 0) {
+      kp = await new Ops().keypair(existingPublicKey, keypairOptions)
     } else {
       kp = await new Ops().keypair(existingPublicKey)
     }
   } finally {
-    if (options.afterOpsKeypair) await options.afterOpsKeypair()
+    if (hooks.after) await hooks.after()
   }
 
   const publicKey = kp.public_key

package/src/lib/helpers/cryptography/provision.js

@@ -4,8 +4,12 @@ const opsKeypair = require('./opsKeypair')
 const localKeypair = require('./localKeypair')
 const { keyNames } = require('../keyResolution')
 
-async function provision ({ envSrc, envFilepath, keysFilepath, noOps }) {
+async function provision ({ envSrc, envFilepath, keysFilepath, noOps, token, keypairHooks, selectKeyStorage }) {
   noOps = noOps !== false
+  if (!noOps && selectKeyStorage) {
+    noOps = await selectKeyStorage() !== 'armored'
+  }
+
   const { publicKeyName, privateKeyName } = keyNames(envFilepath)
 
   let publicKey
@@ -20,7 +24,10 @@ async function provision ({ envSrc, envFilepath, keysFilepath, noOps }) {
     publicKey = kp.publicKey
     privateKey = kp.privateKey
   } else {
-    const kp = await opsKeypair()
+    const keypairOptions = {}
+    if (token) keypairOptions.token = token
+    if (keypairHooks) keypairOptions.hooks = keypairHooks
+    const kp = await opsKeypair(undefined, keypairOptions)
     publicKey = kp.publicKey
     privateKey = kp.privateKey
   }

package/src/lib/helpers/keyResolution/keyValues.js

@@ -73,8 +73,7 @@ async function keyValues (filepath, opts = {}) {
   // ops
   if (!noOps && !privateKey && publicKey && publicKey.length > 0) {
     const kp = await opsKeypair(publicKey, {
-      beforeOpsKeypair: opts.beforeOpsKeypair,
-      afterOpsKeypair: opts.afterOpsKeypair
+      hooks: opts.keypairHooks
     })
     privateKey = kp.privateKey
   }

package/src/lib/helpers/prompts.js

@@ -0,0 +1,43 @@
+const Enquirer = require('enquirer')
+
+const enquirer = new Enquirer()
+
+function choicesForSelect (choices) {
+  return choices.map(choice => {
+    if (typeof choice === 'string') return choice
+
+    return {
+      name: choice.value,
+      message: choice.name || choice.value
+    }
+  })
+}
+
+function enquirerOptions (context = {}) {
+  const options = {
+    // Enquirer names the render stream stdout; use stderr so stdout stays machine-readable.
+    stdout: context.output || process.stderr
+  }
+
+  if (context.input) {
+    options.stdin = context.input
+  }
+
+  return options
+}
+
+async function select ({ message, choices }, context) {
+  const answer = await enquirer.prompt({
+    type: 'select',
+    name: 'value',
+    message,
+    choices: choicesForSelect(choices),
+    ...enquirerOptions(context)
+  })
+
+  return answer.value
+}
+
+module.exports = {
+  select
+}

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

package/src/lib/services/encrypt.js

@@ -29,13 +29,16 @@ const detectEncoding = require('./../helpers/detectEncoding')
 const SAMPLE_ENV_KIT = require('./../helpers/kits/sample')
 
 class Encrypt {
-  constructor (envs = [], key = [], excludeKey = [], envKeysFilepath = null, noOps = false, noCreate = false) {
+  constructor (envs = [], key = [], excludeKey = [], envKeysFilepath = null, noOps = false, noCreate = false, token = undefined, options = {}) {
     this.envs = determine(envs, process.env)
     this.key = key
     this.excludeKey = excludeKey
     this.envKeysFilepath = envKeysFilepath
     this.noOps = noOps
     this.noCreate = noCreate
+    this.token = token
+    this.keypairHooks = options.keypairHooks
+    this.selectKeyStorage = options.selectKeyStorage
 
     this.processedEnvs = []
     this.changedFilepaths = new Set()
@@ -78,14 +81,17 @@ class Encrypt {
     row.envFilepath = envFilepath
 
     try {
-      // if noCreate is on then detectEncoding will throw and we'll halt the calls
-      // but if noCreate is false then create the file if it doesn't exist
-      if (!(await fsx.exists(filepath)) && !this.noCreate) {
-        await fsx.writeFileX(filepath, SAMPLE_ENV_KIT)
+      const fileExists = await fsx.exists(filepath)
+      let envSrc
+      if (!fileExists && !this.noCreate) {
+        envSrc = SAMPLE_ENV_KIT
         fileCreated = true
+        row.kitCreated = 'sample'
+        row.changed = true
+      } else {
+        const encoding = await detectEncoding(filepath)
+        envSrc = await fsx.readFileX(filepath, { encoding })
       }
-      const encoding = await detectEncoding(filepath)
-      let envSrc = await fsx.readFileX(filepath, { encoding })
       if (envSrc.trim().length === 0) {
         envSrc = SAMPLE_ENV_KIT
         row.kitCreated = 'sample'
@@ -97,11 +103,23 @@ class Encrypt {
       let privateKey
 
       const { publicKeyName, privateKeyName } = keyNames(envFilepath)
-      const { publicKeyValue, privateKeyValue } = await keyValues(envFilepath, { keysFilepath: this.envKeysFilepath, noOps: this.noOps })
+      const { publicKeyValue, privateKeyValue } = await keyValues(envFilepath, {
+        keysFilepath: this.envKeysFilepath,
+        noOps: this.noOps,
+        keypairHooks: this.keypairHooks
+      })
 
       // first pass - provision
       if (!privateKeyValue && !publicKeyValue) {
-        const prov = await provision({ envSrc, envFilepath, keysFilepath: this.envKeysFilepath, noOps: this.noOps })
+        const prov = await provision({
+          envSrc,
+          envFilepath,
+          keysFilepath: this.envKeysFilepath,
+          noOps: this.noOps,
+          token: this.token,
+          keypairHooks: this.keypairHooks,
+          selectKeyStorage: this.selectKeyStorage
+        })
         envSrc = prov.envSrc
         publicKey = prov.publicKey
         privateKey = prov.privateKey

package/src/lib/services/run.js

@@ -24,8 +24,7 @@ class Run {
     this.envKeysFilepath = envKeysFilepath
     this.noOps = noOps
     this.noSpinner = options.noSpinner
-    this.beforeOpsKeypair = options.beforeOpsKeypair
-    this.afterOpsKeypair = options.afterOpsKeypair
+    this.keypairHooks = options.keypairHooks
 
     this.processedEnvs = []
     this.readableFilepaths = new Set()
@@ -189,8 +188,7 @@ class Run {
       const { privateKeyValue } = await keyValues(filepath, {
         keysFilepath: this.envKeysFilepath,
         noOps: this.noOps,
-        beforeOpsKeypair: this.beforeOpsKeypair,
-        afterOpsKeypair: this.afterOpsKeypair
+        keypairHooks: this.keypairHooks
       })
 
       const {