@dotenvx/dotenvx 2.12.0 → 2.14.0

package/CHANGELOG.md

@@ -2,7 +2,24 @@
 
 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/v2.12.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.14.0...main)
+
+## [2.14.0](https://github.com/dotenvx/dotenvx/compare/v2.13.0...v2.14.0) (2026-07-16)
+
+### Added
+
+* Add `dotenvx run --validate` for simple env validation against your `.env.example` ([#906](https://github.com/dotenvx/dotenvx/pull/906))
+* Add `dotenvx validate` for a pre-check of validation against your `.env.example` file ([#906](https://github.com/dotenvx/dotenvx/pull/906))
+
+## [2.13.0](https://github.com/dotenvx/dotenvx/compare/v2.12.0...v2.13.0) (2026-07-16)
+
+### Added
+
+* Add `get --eval-export` flag ([#904](https://github.com/dotenvx/dotenvx/pull/904))
+
+### Changed
+
+* Make `get --eval` posix safe ([#904](https://github.com/dotenvx/dotenvx/pull/904))
 
 ## [2.12.0](https://github.com/dotenvx/dotenvx/compare/v2.11.3...v2.12.0) (2026-07-16)
 

package/README.md

@@ -1453,6 +1453,54 @@ Hello production
 
 Available log levels are `error, warn, info, verbose, debug, silly` ([source](https://docs.npmjs.com/cli/v8/using-npm/logging#setting-log-levels))
 
+</details>
+<details><summary>`run --validate`</summary><br>
+
+Validate your environment against `.env.example`.
+
+```ini
+# .env.example
+DATABASE_URL=
+API_KEY=
+SENTRY_DSN= # optional
+```
+
+```sh
+$ dotenvx run --validate -- node index.js
+[VALIDATION_FAILED] missing required (DATABASE_URL, API_KEY). fix: [https://github.com/dotenvx/dotenvx/issues/907]
+```
+
+Validation errors are reported without stopping your command. Combine `--validate` with `--strict` to exit with code `1` before the command runs.
+
+```sh
+$ dotenvx run --validate --strict -- node index.js
+```
+
+Any inline comment containing the word `optional` marks that key as optional. If `.env.example` is missing, dotenvx reports `MISSING_ENV_EXAMPLE`. An empty `.env.example` is valid and declares no required variables.
+
+</details>
+<details><summary>`validate`</summary><br>
+
+Validate `.env` file(s) against `.env.example` without running a command.
+
+```ini
+# .env.example
+DATABASE_URL=
+API_KEY=
+SENTRY_DSN= # optional
+```
+
+```sh
+$ dotenvx validate
+[VALIDATION_FAILED] missing required (DATABASE_URL, API_KEY). fix: [https://github.com/dotenvx/dotenvx/issues/907]
+```
+
+Use `-f` and `-fk` to validate a specific env file and keys file. The command exits with code `1` when validation fails and prints errors to stderr. On success, it exits with code `0`.
+
+```sh
+$ dotenvx validate -f .env.production -fk .env.keys
+```
+
 </details>
 <details><summary>`run --strict`</summary><br>
 
@@ -2825,9 +2873,10 @@ Commands:
   decrypt            decrypt .env file(s)
   keypair [KEY]      print public/private keys for .env file(s)
   ls [directory]     print all .env files in a tree structure
+  gitignore          append to .gitignore
   genexample [directory]
                      generate .env.example
-  gitignore          append to .gitignore
+  validate           validate .env file(s) against .env.example
   precommit [directory]
                      prevent committing .env files to code
   prebuild [directory]

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.12.0",
+  "version": "2.14.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -43,7 +43,7 @@
   },
   "funding": "https://dotenvx.com",
   "dependencies": {
-    "@dotenvx/primitives": "^2.0.0",
+    "@dotenvx/primitives": "^2.1.0",
     "@dotenvx/tooling": "^1.0.2",
     "yocto-spinner": "^1.2.1"
   },

package/src/cli/actions/get.js

@@ -76,10 +76,11 @@ async function get (key) {
         console.log(single)
       }
     } else {
-      if (options.format === 'eval') {
+      if (options.format === 'eval' || options.format === 'eval-export') {
+        const prefix = options.format === 'eval-export' ? 'export ' : ''
         let inline = ''
         for (const [key, value] of Object.entries(parsed)) {
-          inline += `${key}=${escape(value)}\n`
+          inline += `${prefix}${key}=${escape(value)}\n`
         }
         inline = inline.trim()
 

package/src/cli/actions/run.js

@@ -15,6 +15,7 @@ const maskEnvSrc = require('../../lib/helpers/maskEnvSrc')
 const maskProcessedEnvs = require('../../lib/helpers/maskProcessedEnvs')
 const redactedValues = require('../../lib/helpers/redactedValues')
 const { redactOutput } = require('../../lib/helpers/redactOutput')
+const validateEnvExample = require('../../lib/helpers/validateEnvExample')
 
 const { determine } = require('./../../lib/helpers/envResolution')
 
@@ -135,6 +136,20 @@ async function run () {
       maskProcessedEnvs(processedEnvs, commandEnv, showChar)
     }
 
+    if (options.validate) {
+      const error = validateEnvExample(process.env)
+
+      if (error) {
+        if (ignore.includes(error.code)) {
+          logger.verbose(`ignored: ${error.message}`)
+        } else if (options.strict) {
+          throw error
+        } else {
+          logger.error(error.messageWithHelp || error.message)
+        }
+      }
+    }
+
     for (const processedEnv of processedEnvs) {
       if (processedEnv.type === 'envFile') {
         logger.verbose(`loading env from ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)

package/src/cli/actions/validate.js

@@ -0,0 +1,84 @@
+const { logger } = require('./../../shared/logger')
+
+const envsResolver = require('./../../lib/resolvers/envs')
+const catchAndLog = require('./../../lib/helpers/catchAndLog')
+const createSpinner = require('../../lib/helpers/createSpinner')
+const Session = require('../../db/session')
+const normalizeDotenvConfigQuiet = require('../../lib/helpers/normalizeDotenvConfigQuiet')
+const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
+const buildCommandEnvs = require('../../lib/helpers/buildCommandEnvs')
+const resolveEnvKeysFile = require('../../lib/helpers/resolveEnvKeysFile')
+const validateEnvExample = require('../../lib/helpers/validateEnvExample')
+
+const { determine } = require('./../../lib/helpers/envResolution')
+
+async function validate () {
+  const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts()))
+  const spinnerOptions = typeof this.optsWithGlobals === 'function' ? this.optsWithGlobals() : options
+  const spinner = await createSpinner({ ...spinnerOptions, ...options, text: 'validating' })
+  const ignore = options.ignore || []
+  const validateEnv = { ...process.env }
+  let errorCount = 0
+
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    let envs = buildCommandEnvs(this.envs, options.convention)
+    envs = determine(envs, process.env)
+
+    const sesh = new Session()
+    const noArmor = options.armor === false || (!options.token && (await sesh.noArmor()))
+    const noKeychain = options.native === false || options.noNative === true
+
+    const { processedEnvs } = await envsResolver({
+      envs,
+      overload: options.overload,
+      processEnv: validateEnv,
+      envKeysFile: resolveEnvKeysFile(options.envKeysFile),
+      noArmor,
+      noKeychain,
+      token: options.token,
+      onStatus: (text) => {
+        if (spinner && text) {
+          spinner.text = text
+        }
+      }
+    })
+
+    for (const processedEnv of processedEnvs) {
+      for (const error of processedEnv.errors || []) {
+        if (ignore.includes(error.code)) {
+          logger.verbose(`ignored: ${error.message}`)
+          continue
+        }
+
+        errorCount += 1
+        logger.error(error.messageWithHelp || error.message)
+      }
+    }
+
+    const validationError = validateEnvExample(validateEnv)
+    if (validationError) {
+      if (ignore.includes(validationError.code)) {
+        logger.verbose(`ignored: ${validationError.message}`)
+      } else {
+        errorCount += 1
+        logger.error(validationError.messageWithHelp || validationError.message)
+      }
+    }
+
+    if (spinner) spinner.stop()
+
+    if (errorCount > 0) {
+      process.exit(1)
+    } else {
+      logger.success('▣ validated')
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    catchAndLog(error)
+    process.exit(1)
+  }
+}
+
+module.exports = validate

package/src/cli/dotenvx.js

@@ -66,6 +66,7 @@ program.command('run')
   .option('-fk, --env-keys-file <path>', 'path(s) to your .env.keys file(s) (default: same path as your env file)', collectEnvKeys)
   .option('--redact', 'redact injected values except keys ending in _PLAIN', false)
   .option('-o, --overload', 'override existing env variables (by default, existing env vars take precedence over .env files)')
+  .option('--validate', 'validate against .env.example', false)
   .option('--strict', 'process.exit(1) on any errors', false)
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
   .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
@@ -94,7 +95,7 @@ program.command('get')
   .option('--mask [characters]', 'mask values, optionally setting visible characters')
   .option('-pp, --pretty-print', 'pretty print output')
   .option('--pp', 'pretty print output (alias)')
-  .option('--format <type>', 'format of the output (json, shell, colon, eval)', 'json')
+  .option('--format <type>', 'format of the output (json, shell, colon, eval, eval-export)', 'json')
   .option('--no-armor', 'disable Dotenvx Armor features')
   .option('--no-native', 'disable OS secret store features')
   .action(function (...args) {
@@ -182,6 +183,15 @@ program.command('ls')
     return require('./actions/ls').apply(this, args)
   })
 
+// dotenvx gitignore
+program.command('gitignore')
+  .description('append to .gitignore')
+  .addHelpText('after', examples.gitignore)
+  .option('--pattern <patterns...>', 'pattern(s) to gitignore', ['.env*'])
+  .action(function (...args) {
+    return require('./actions/ext/gitignore').apply(this, args)
+  })
+
 // dotenvx genexample
 program.command('genexample')
   .description('generate .env.example')
@@ -191,13 +201,21 @@ program.command('genexample')
     return require('./actions/ext/genexample').apply(this, args)
   })
 
-// dotenvx gitignore
-program.command('gitignore')
-  .description('append to .gitignore')
-  .addHelpText('after', examples.gitignore)
-  .option('--pattern <patterns...>', 'pattern(s) to gitignore', ['.env*'])
+// dotenvx validate
+program.command('validate')
+  .description('validate .env file(s) against .env.example')
+  .option('-e, --env <strings...>', 'environment variable(s) set as string (example: "HELLO=World")', collectEnvs('env'), [])
+  .option('-f, --env-file <path>', 'path(s) to your env file(s)', collectEnvs('envFile'), [])
+  .option('-fk, --env-keys-file <path>', 'path(s) to your .env.keys file(s) (default: same path as your env file)', collectEnvKeys)
+  .option('-o, --overload', 'override existing env variables (by default, existing env vars take precedence over .env files)')
+  .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
+  .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
+  .option('--token <token>', 'set Armor ⛨ token')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-native', 'disable OS secret store features')
   .action(function (...args) {
-    return require('./actions/ext/gitignore').apply(this, args)
+    this.envs = envs
+    return require('./actions/validate').apply(this, args)
   })
 
 // dotenvx precommit

package/src/lib/helpers/errors.js

@@ -12,6 +12,7 @@ const ISSUE_BY_CODE = {
   MALFORMED_ENCRYPTED_DATA: 'https://github.com/dotenvx/dotenvx/issues/467',
   MISPAIRED_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/752',
   MISSING_DIRECTORY: 'https://github.com/dotenvx/dotenvx/issues/758',
+  MISSING_ENV_EXAMPLE: 'https://github.com/dotenvx/dotenvx/issues/905',
   MISSING_ENV_FILE: 'https://github.com/dotenvx/dotenvx/issues/484',
   MISSING_ENV_KEYS_FILE: 'https://github.com/dotenvx/dotenvx/issues/775',
   MISSING_ENV_FILES: 'https://github.com/dotenvx/dotenvx/issues/760',
@@ -22,6 +23,7 @@ const ISSUE_BY_CODE = {
   MISSING_VALUE: 'https://github.com/dotenvx/dotenvx/issues/864',
   FILE_NOT_WRITABLE: 'https://github.com/dotenvx/dotenvx/issues/890',
   PRECOMMIT_HOOK_MODIFY_FAILED: 'try again or report error',
+  VALIDATION_FAILED: 'https://github.com/dotenvx/dotenvx/issues/907',
   WRONG_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/466'
 }
 
@@ -207,6 +209,18 @@ class Errors {
     return e
   }
 
+  missingEnvExample () {
+    const code = 'MISSING_ENV_EXAMPLE'
+    const message = `[${code}] missing .env.example file`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
   missingEnvKeysFile () {
     const code = 'MISSING_ENV_KEYS_FILE'
     const envKeysFilepath = this.envKeysFilepath || '.env.keys'
@@ -305,6 +319,18 @@ class Errors {
     return e
   }
 
+  validationFailed () {
+    const code = 'VALIDATION_FAILED'
+    const message = `[${code}] ${this.message}`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
   precommitHookModifyFailed () {
     const code = 'PRECOMMIT_HOOK_MODIFY_FAILED'
     const message = `[${code}] failed to modify pre-commit hook: ${this.error.message}`

package/src/lib/helpers/escape.js

@@ -1,5 +1,6 @@
 function escape (value) {
-  return JSON.stringify(value)
+  const quote = String.fromCharCode(39)
+  return quote + value.replaceAll(quote, quote + '\\' + quote + quote) + quote
 }
 
 module.exports = escape

package/src/lib/helpers/validate.js

@@ -0,0 +1,40 @@
+function optionalKeys (comments) {
+  const keys = new Set()
+
+  for (const [key, values] of Object.entries(comments)) {
+    if (values.some(comment => comment && /\boptional\b/i.test(comment))) {
+      keys.add(key)
+    }
+  }
+
+  return keys
+}
+
+function validate (example = {}, env = {}, options = {}) {
+  const errors = []
+  const missingRequired = []
+  const optional = optionalKeys(options.comments || {})
+
+  for (const key of Object.keys(example)) {
+    const value = env[key]
+    const missing = !Object.prototype.hasOwnProperty.call(env, key) || value.trim() === ''
+    if (!optional.has(key) && missing) {
+      missingRequired.push(key)
+    }
+  }
+
+  if (missingRequired.length > 0) {
+    errors.push({
+      code: 'MISSING_REQUIRED',
+      keys: missingRequired,
+      message: `missing required (${missingRequired.join(', ')})`
+    })
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  }
+}
+
+module.exports = validate

package/src/lib/helpers/validateEnvExample.js

@@ -0,0 +1,24 @@
+const fs = require('fs')
+const { scan } = require('@dotenvx/primitives')
+
+const Errors = require('./errors')
+const validate = require('./validate')
+
+function validateEnvExample (env = process.env, options = {}) {
+  const filepath = options.filepath || '.env.example'
+
+  if (!fs.existsSync(filepath)) {
+    return new Errors().missingEnvExample()
+  }
+
+  const exampleSrc = fs.readFileSync(filepath, 'utf8')
+  const { parsed: example, comments } = scan(exampleSrc)
+  const validation = validate(example, env, { comments })
+
+  if (!validation.valid) {
+    const message = validation.errors.map(error => error.message).join('; ')
+    return new Errors({ message }).validationFailed()
+  }
+}
+
+module.exports = validateEnvExample

package/src/lib/main.js

@@ -20,6 +20,7 @@ const setTransform = require('./transforms/set')
 const buildEnvs = require('./helpers/buildEnvs')
 const buildConfigEnvs = require('./helpers/buildConfigEnvs')
 const { determine } = require('./helpers/envResolution')
+const escape = require('./helpers/escape')
 const fsx = require('./helpers/fsx')
 const decryptKeyValue = require('./helpers/cryptography/decryptKeyValue')
 const Errors = require('./helpers/errors')
@@ -358,10 +359,11 @@ const get = async function (key, options = {}) {
       return single
     }
   } else {
-    if (options.format === 'eval') {
+    if (options.format === 'eval' || options.format === 'eval-export') {
+      const prefix = options.format === 'eval-export' ? 'export ' : ''
       let inline = ''
       for (const [key, value] of Object.entries(parsed)) {
-        inline += `${key}=${escape(value)}\n`
+        inline += `${prefix}${key}=${escape(value)}\n`
       }
       inline = inline.trim()