@dotenvx/dotenvx 1.24.5 → 1.25.0

package/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 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.24.5...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.25.0...main)
+
+## [1.25.0](https://github.com/dotenvx/dotenvx/compare/v1.24.5...v1.25.0)
+
+### Added
+
+* add `run --strict` flag to exit with code `1` if any errors are encountered - like a missing `.env` file or decryption failure ([#460](https://github.com/dotenvx/dotenvx/pull/460))
+* add `get --strict` flag to exit with code `1` if any errors are encountered - like a missing `.env` file or decryption failure ([#461](https://github.com/dotenvx/dotenvx/pull/461))
+* add `strict` option to `config()` to throw for any errors ([#459](https://github.com/dotenvx/dotenvx/pull/459))
+
+### Changed
+
+* log `MISSING_ENV_FILE` and `DECRYPTION_FAILED` errors to stderr (prior was stdout as a warning) ([#459](https://github.com/dotenvx/dotenvx/pull/459))
+
+### Removed
+
+* remove `dotenvx.get()` function from `lib/main.js`. (`parse` already historically exists for this purpose) ([#461](https://github.com/dotenvx/dotenvx/pull/461))
 
 ## [1.24.5](https://github.com/dotenvx/dotenvx/compare/v1.24.4...v1.24.5)
 

package/README.md

@@ -968,6 +968,21 @@ More examples
 
   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 --strict`</summary><br>
+
+  Exit with code `1` if any errors are encountered - like a missing .env file or decryption failure.
+
+  ```sh
+  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
+
+  $ dotenvx run -f .env.missing --strict -- node index.js
+  [MISSING_ENV_FILE] missing .env.missing file (/path/to/.env.missing)
+  [MISSING_ENV_FILE] ? add one with [echo "HELLO=World" > .env.missing]
+  ```
+
+  This can be useful in `ci` scripts where you want to fail the ci if your `.env` file could not be decrypted at runtime.
+
   </details>
 * <details><summary>`run --convention=nextjs`</summary><br>
 
@@ -1036,6 +1051,16 @@ More examples
   World
   ```
 
+  </details>
+* <details><summary>`get KEY --strict`</summary><br>
+
+  Exit with code `1` if any errors are encountered - like a missing key, missing .env file, or decryption failure.
+
+  ```sh
+  $ dotenvx get DOES_NOT_EXIST --strict
+  [MISSING_KEY] missing DOES_NOT_EXIST key
+  ```
+
   </details>
 * <details><summary>`get KEY --convention=nextjs`</summary><br>
 
@@ -1607,6 +1632,110 @@ More examples
 
   </details>
 
+### config() 📦
+
+* <details><summary>`config()`</summary><br>
+
+  Use directly in node.js code.
+
+  ```ini
+  # .env
+  HELLO="World"
+  ```
+
+  ```js
+  // index.js
+  require('@dotenvx/dotenvx').config()
+
+  console.log(`Hello ${process.env.HELLO}`)
+  ```
+
+  ```sh
+  $ node index.js
+  [dotenvx@1.24.5] injecting env (1) from .env
+  Hello World
+  ```
+
+  </details>
+* <details><summary>`config(path: ['.env.local', '.env'])` - multiple files</summary><br>
+
+  Specify path(s) to multiple .env files.
+
+  ```ini
+  # .env.local
+  HELLO="Me"
+  ```
+
+  ```ini
+  # .env
+  HELLO="World"
+  ```
+
+  ```js
+  // index.js
+  require('@dotenvx/dotenvx').config({path: ['.env.local', '.env']})
+
+  console.log(`Hello ${process.env.HELLO}`)
+  ```
+
+  ```sh
+  $ node index.js
+  [dotenvx@1.24.5] injecting env (1) from .env.local, .env
+  Hello Me
+  ```
+
+  </details>
+* <details><summary>`config(overload: true)` - overload</summary><br>
+
+  User `overload` to overwrite the prior set value.
+
+  ```ini
+  # .env.local
+  HELLO="Me"
+  ```
+
+  ```ini
+  # .env
+  HELLO="World"
+  ```
+
+  ```js
+  // index.js
+  require('@dotenvx/dotenvx').config({path: ['.env.local', '.env'], overload: true})
+
+  console.log(`Hello ${process.env.HELLO}`)
+  ```
+
+  ```sh
+  $ node index.js
+  [dotenvx@1.24.5] injecting env (1) from .env.local, .env
+  Hello World
+  ```
+
+  </details>
+* <details><summary>`config(strict: true)` - strict</summary><br>
+
+  Use `strict` to throw if an error is encountered - like a missing .env file.
+
+  ```ini
+  # .env
+  HELLO="World"
+  ```
+
+  ```js
+  // index.js
+  require('@dotenvx/dotenvx').config({path: ['.env.missing', '.env'], strict: true})
+
+  console.log(`Hello ${process.env.HELLO}`)
+  ```
+
+  ```sh
+  $ node index.js
+  Error: [MISSING_ENV_FILE] missing .env.missing file (/path/to/.env.missing)
+  ```
+
+  </details>
+
 ### Extensions 🔌
 
 * <details><summary>`ext genexample`</summary><br>

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.24.5",
+  "version": "1.25.0",
   "name": "@dotenvx/dotenvx",
   "description": "a better dotenv–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/cli/actions/decrypt.js

@@ -48,10 +48,10 @@ function decrypt () {
           errorCount += 1
 
           if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-            logger.error(processedEnv.error.message)
+            console.error(processedEnv.error.message)
             logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.envFilepath}] and re-run [dotenvx decrypt]`)
           } else {
-            logger.error(processedEnv.error.message)
+            console.error(processedEnv.error.message)
           }
         } else if (processedEnv.changed) {
           fsx.writeFileX(processedEnv.filepath, processedEnv.envSrc)

package/src/cli/actions/ext/genexample.js

@@ -26,7 +26,7 @@ function genexample (directory) {
       logger.blank('no changes (.env.example)')
     }
   } catch (error) {
-    logger.error(error.message)
+    console.error(error.message)
     if (error.help) {
       logger.help(error.help)
     }

package/src/cli/actions/ext/scan.js

@@ -10,7 +10,7 @@ function scan () {
     // redirect stderr to stdout to capture and ignore it
     childProcess.execSync('gitleaks version', { stdio: ['ignore', 'pipe', 'ignore'] })
   } catch (error) {
-    logger.error('gitleaks: command not found')
+    console.error('gitleaks: command not found')
     logger.help('? install gitleaks:      [brew install gitleaks]')
     logger.help2('? other install options: [https://github.com/gitleaks/gitleaks]')
     process.exit(1)
@@ -21,7 +21,7 @@ function scan () {
     const output = childProcess.execSync('gitleaks detect -v 2>&1', { stdio: 'pipe' }).toString() // gitleaks sends output as stderr for strange reason
     logger.blank(output)
   } catch (error) {
-    logger.error(error.message)
+    console.error(error.message)
 
     process.exit(1)
   }

package/src/cli/actions/get.js

@@ -3,7 +3,7 @@ const { logger } = require('./../../shared/logger')
 const conventions = require('./../../lib/helpers/conventions')
 const escape = require('./../../lib/helpers/escape')
 
-const main = require('./../../lib/main')
+const Get = require('./../../lib/services/get')
 
 function get (key) {
   if (key) {
@@ -21,40 +21,57 @@ function get (key) {
     envs = this.envs
   }
 
-  const results = main.get(key, envs, options.overload, process.env.DOTENV_KEY, options.all)
+  try {
+    const { parsed, errors } = new Get(key, envs, options.overload, process.env.DOTENV_KEY, options.all).run()
 
-  if (typeof results === 'object' && results !== null) {
-    if (options.format === 'eval') {
-      let inline = ''
-      for (const [key, value] of Object.entries(results)) {
-        inline += `${key}=${escape(value)}\n`
-      }
-      inline = inline.trim()
+    for (const error of errors || []) {
+      if (options.strict) throw error // throw immediately if strict
 
-      console.log(inline)
-    } else if (options.format === 'shell') {
-      let inline = ''
-      for (const [key, value] of Object.entries(results)) {
-        inline += `${key}=${value} `
+      console.error(error.message)
+      if (error.help) {
+        console.error(error.help)
       }
-      inline = inline.trim()
+    }
 
-      console.log(inline)
-    } else {
-      let space = 0
-      if (options.prettyPrint) {
-        space = 2
+    if (key) {
+      const single = parsed[key]
+      if (single === undefined) {
+        console.log('')
+      } else {
+        console.log(single)
       }
+    } else {
+      if (options.format === 'eval') {
+        let inline = ''
+        for (const [key, value] of Object.entries(parsed)) {
+          inline += `${key}=${escape(value)}\n`
+        }
+        inline = inline.trim()
+
+        console.log(inline)
+      } else if (options.format === 'shell') {
+        let inline = ''
+        for (const [key, value] of Object.entries(parsed)) {
+          inline += `${key}=${value} `
+        }
+        inline = inline.trim()
 
-      console.log(JSON.stringify(results, null, space))
+        console.log(inline)
+      } else {
+        let space = 0
+        if (options.prettyPrint) {
+          space = 2
+        }
+
+        console.log(JSON.stringify(parsed, null, space))
+      }
     }
-  } else {
-    if (results === undefined) {
-      console.log('')
-      process.exit(1)
-    } else {
-      console.log(results)
+  } catch (error) {
+    console.error(error.message)
+    if (error.help) {
+      console.error(error.help)
     }
+    process.exit(1)
   }
 }
 

package/src/cli/actions/run.js

@@ -5,6 +5,7 @@ const executeCommand = require('./../../lib/helpers/executeCommand')
 const Run = require('./../../lib/services/run')
 
 const conventions = require('./../../lib/helpers/conventions')
+const DeprecationNotice = require('./../../lib/helpers/deprecationNotice')
 
 async function run () {
   const commandArgs = this.args
@@ -35,11 +36,7 @@ async function run () {
       envs = this.envs
     }
 
-    if (process.env.DOTENV_KEY) {
-      logger.warn('DEPRECATION NOTICE: Setting DOTENV_KEY with .env.vault is deprecated.')
-      logger.warn('DEPRECATION NOTICE: Run [dotenvx ext vault migrate] for instructions on converting your .env.vault file to encrypted .env files (using public key encryption algorithm secp256k1)')
-      logger.warn('DEPRECATION NOTICE: Read more at [https://github.com/dotenvx/dotenvx/blob/main/CHANGELOG.md#0380]')
-    }
+    new DeprecationNotice().dotenvKey() // DEPRECATION NOTICE
 
     const {
       processedEnvs,
@@ -62,43 +59,37 @@ async function run () {
         logger.verbose(`loading env from string (${processedEnv.string})`)
       }
 
-      if (processedEnv.error) {
-        if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-          // do not warn for conventions (too noisy)
-          if (!options.convention) {
-            logger.warnv(processedEnv.error.message)
-            logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.filepath}] and re-run [dotenvx run -- ${commandArgs.join(' ')}]`)
+      for (const error of processedEnv.errors || []) {
+        if (options.strict) throw error // throw immediately if strict
+
+        if (error.code === 'MISSING_ENV_FILE') {
+          if (!options.convention) { // do not output error for conventions (too noisy)
+            console.error(error.message)
+            if (error.help) {
+              console.error(`${error.help} and re-run [dotenvx run -- ${commandArgs.join(' ')}]`)
+            }
           }
         } else {
-          logger.warnv(processedEnv.error.message)
-        }
-      } else {
-        if (processedEnv.warnings) {
-          for (const warning of processedEnv.warnings) {
-            logger.warn(warning.message)
-            if (warning.help) {
-              logger.help(warning.help)
-            }
+          console.error(error.message)
+          if (error.help) {
+            console.error(error.help)
           }
         }
+      }
 
-        // debug parsed
-        const parsed = processedEnv.parsed
-        logger.debug(parsed)
+      // debug parsed
+      logger.debug(processedEnv.parsed)
 
-        // verbose/debug injected key/value
-        const injected = processedEnv.injected
-        for (const [key, value] of Object.entries(injected)) {
-          logger.verbose(`${key} set`)
-          logger.debug(`${key} set to ${value}`)
-        }
+      // verbose/debug injected key/value
+      for (const [key, value] of Object.entries(processedEnv.injected || {})) {
+        logger.verbose(`${key} set`)
+        logger.debug(`${key} set to ${value}`)
+      }
 
-        // verbose/debug preExisted key/value
-        const preExisted = processedEnv.preExisted
-        for (const [key, value] of Object.entries(preExisted)) {
-          logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
-          logger.debug(`${key} pre-exists as ${value} (protip: use --overload to override)`)
-        }
+      // verbose/debug preExisted key/value
+      for (const [key, value] of Object.entries(processedEnv.preExisted || {})) {
+        logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
+        logger.debug(`${key} pre-exists as ${value} (protip: use --overload to override)`)
       }
     }
 
@@ -113,10 +104,11 @@ async function run () {
 
     logger.successv(msg)
   } catch (error) {
-    logger.error(error.message)
+    console.error(error.message)
     if (error.help) {
-      logger.help(error.help)
+      console.error(error.help)
     }
+    process.exit(1)
   }
 
   await executeCommand(commandArgs, process.env)

package/src/cli/dotenvx.js

@@ -58,6 +58,7 @@ program.command('run')
   .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', collectEnvs('envFile'), [])
   .option('-fv, --env-vault-file <paths...>', 'path(s) to your .env.vault file(s)', collectEnvs('envVaultFile'), [])
   .option('-o, --overload', 'override existing env variables')
+  .option('--strict', 'process.exit(1) on any errors (default: false)', false)
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\'])')
   .action(function (...args) {
     this.envs = envs
@@ -74,6 +75,7 @@ program.command('get')
   .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', collectEnvs('envFile'), [])
   .option('-fv, --env-vault-file <paths...>', 'path(s) to your .env.vault file(s)', collectEnvs('envVaultFile'), [])
   .option('-o, --overload', 'override existing env variables')
+  .option('--strict', 'process.exit(1) on any errors (default: false)', false)
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\'])')
   .option('-a, --all', 'include all machine envs as well')
   .option('-pp, --pretty-print', 'pretty print output')

package/src/lib/helpers/catchAndLog.js

@@ -1,7 +1,7 @@
 const { logger } = require('./../../shared/logger')
 
 function catchAndLog (error) {
-  logger.error(error.message)
+  console.error(error.message)
   if (error.help) {
     logger.help(error.help)
   }

package/src/lib/helpers/deprecationNotice.js

@@ -0,0 +1,17 @@
+const { logger } = require('./../../shared/logger')
+
+class DeprecationNotice {
+  constructor (options = {}) {
+    this.DOTENV_KEY = options.DOTENV_KEY || process.env.DOTENV_KEY
+  }
+
+  dotenvKey () {
+    if (this.DOTENV_KEY) {
+      logger.warn('[DEPRECATION NOTICE] Setting DOTENV_KEY with .env.vault is deprecated.')
+      logger.warn('[DEPRECATION NOTICE] Run [dotenvx ext vault migrate] for instructions on converting your .env.vault file to encrypted .env files (using public key encryption algorithm secp256k1)')
+      logger.warn('[DEPRECATION NOTICE] Read more at [https://github.com/dotenvx/dotenvx/blob/main/CHANGELOG.md#0380]')
+    }
+  }
+}
+
+module.exports = DeprecationNotice

package/src/lib/helpers/errors.js

@@ -0,0 +1,30 @@
+class Errors {
+  constructor (options = {}) {
+    this.filepath = options.filepath
+    this.envFilepath = options.envFilepath
+
+    this.key = options.key
+  }
+
+  missingEnvFile () {
+    const code = 'MISSING_ENV_FILE'
+    const message = `[${code}] missing ${this.envFilepath} file (${this.filepath})`
+    const help = `[${code}] ? add one with [echo "HELLO=World" > ${this.envFilepath}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    return e
+  }
+
+  missingKey () {
+    const code = 'MISSING_KEY'
+    const message = `[${code}] missing ${this.key} key`
+
+    const e = new Error(message)
+    e.code = code
+    return e
+  }
+}
+
+module.exports = Errors

package/src/lib/helpers/parse.js

@@ -16,7 +16,7 @@ class Parse {
     this.parsed = {}
     this.preExisted = {}
     this.injected = {}
-    this.warnings = []
+    this.errors = []
 
     // for use with progressive expansion
     this.runningParsed = {}
@@ -42,7 +42,7 @@ class Parse {
       try {
         this.parsed[key] = this.decrypt(this.parsed[key])
       } catch (e) {
-        this.warnings.push(this.warning(e, key))
+        this.errors.push(this.error(e, key))
       }
 
       // eval empty, double, or backticks
@@ -78,8 +78,8 @@ class Parse {
       parsed: this.parsed,
       processEnv: this.processEnv,
       injected: this.injected,
-      warnings: this.warnings,
-      preExisted: this.preExisted
+      preExisted: this.preExisted,
+      errors: this.errors
     }
   }
 
@@ -208,12 +208,12 @@ class Parse {
     return (this.src || '').toString().replace(/\r\n?/mg, '\n') // Convert buffer to string and Convert line breaks to same format
   }
 
-  warning (e, key) {
-    const warning = new Error(`[${e.code}] could not decrypt ${key} using private key '${truncate(this.privateKey)}'`)
-    warning.code = e.code
-    warning.help = `[${e.code}] ? ${e.message}`
+  error (e, key) {
+    const error = new Error(`[${e.code}] could not decrypt ${key} using private key '${truncate(this.privateKey)}'`)
+    error.code = e.code
+    error.help = `[${e.code}] ? ${e.message}`
 
-    return warning
+    return error
   }
 }
 

package/src/lib/main.js

@@ -7,7 +7,6 @@ const { getColor, bold } = require('./../shared/colors')
 
 // services
 const Ls = require('./services/ls')
-const Get = require('./services/get')
 const Run = require('./services/run')
 const Keypair = require('./services/keypair')
 const Genexample = require('./services/genexample')
@@ -16,6 +15,7 @@ const Genexample = require('./services/genexample')
 const conventions = require('./helpers/conventions')
 const dotenvOptionPaths = require('./helpers/dotenvOptionPaths')
 const Parse = require('./helpers/parse')
+const DeprecationNotice = require('./helpers/deprecationNotice')
 
 /** @type {import('./main').config} */
 const config = function (options = {}) {
@@ -28,7 +28,10 @@ const config = function (options = {}) {
   // overload
   const overload = options.overload || options.override
 
-  // DOTENV_KEY
+  // strict
+  const strict = options.strict
+
+  // DOTENV_KEY (DEPRECATED)
   let DOTENV_KEY = process.env.DOTENV_KEY
   if (options && options.DOTENV_KEY) {
     DOTENV_KEY = options.DOTENV_KEY
@@ -46,11 +49,7 @@ const config = function (options = {}) {
       envs = conventions(options.convention).concat(envs)
     }
 
-    if (process.env.DOTENV_KEY) {
-      logger.warn('DEPRECATION NOTICE: Setting DOTENV_KEY with .env.vault is deprecated.')
-      logger.warn('DEPRECATION NOTICE: Run [dotenvx ext vault migrate] for instructions on converting your .env.vault file to encrypted .env files (using public key encryption algorithm secp256k1)')
-      logger.warn('DEPRECATION NOTICE: Read more at [https://github.com/dotenvx/dotenvx/blob/main/CHANGELOG.md#0380]')
-    }
+    new DeprecationNotice({ DOTENV_KEY }).dotenvKey() // DEPRECATION NOTICE
 
     for (const optionPath of optionPaths) {
       // if DOTENV_KEY is set then assume we are checking envVaultFile
@@ -64,12 +63,11 @@ const config = function (options = {}) {
       }
     }
 
-    const { processedEnvs, readableFilepaths, uniqueInjectedKeys } = new Run(
-      envs,
-      overload,
-      DOTENV_KEY,
-      processEnv
-    ).run()
+    const {
+      processedEnvs,
+      readableFilepaths,
+      uniqueInjectedKeys
+    } = new Run(envs, overload, DOTENV_KEY, processEnv).run()
 
     let lastError
     /** @type {Record<string, string>} */
@@ -77,65 +75,50 @@ const config = function (options = {}) {
 
     for (const processedEnv of processedEnvs) {
       if (processedEnv.type === 'envVaultFile') {
-        logger.verbose(
-          `loading env from encrypted ${processedEnv.filepath} (${path.resolve(
-            processedEnv.filepath
-          )})`
-        )
-        logger.debug(
-          `decrypting encrypted env from ${
-            processedEnv.filepath
-          } (${path.resolve(processedEnv.filepath)})`
-        )
+        logger.verbose(`loading env from encrypted ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
+        logger.debug(`decrypting encrypted env from ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
       }
 
       if (processedEnv.type === 'envFile') {
-        logger.verbose(
-          `loading env from ${processedEnv.filepath} (${path.resolve(
-            processedEnv.filepath
-          )})`
-        )
+        logger.verbose(`loading env from ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
       }
 
-      if (processedEnv.error) {
-        lastError = processedEnv.error
+      for (const error of processedEnv.errors || []) {
+        if (strict) throw error // throw immediately if strict
 
-        if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-          // do not warn for conventions (too noisy)
-          if (!options.convention) {
-            logger.warnv(processedEnv.error.message)
-            logger.help(
-              `? add one with [echo "HELLO=World" > ${processedEnv.filepath}] and re-run [dotenvx run -- yourcommand]`
-            )
+        lastError = error // surface later in { error }
+
+        if (error.code === 'MISSING_ENV_FILE') {
+          if (!options.convention) { // do not output error for conventions (too noisy)
+            console.error(error.message)
+            if (error.help) {
+              logger.help(error.help)
+            }
           }
         } else {
-          logger.warnv(processedEnv.error.message)
-        }
-      } else {
-        Object.assign(parsedAll, processedEnv.injected)
-        Object.assign(parsedAll, processedEnv.preExisted) // preExisted 'wins'
-
-        // debug parsed
-        const parsed = processedEnv.parsed
-        logger.debug(parsed)
-
-        // verbose/debug injected key/value
-        const injected = processedEnv.injected
-        for (const [key, value] of Object.entries(injected)) {
-          logger.verbose(`${key} set`)
-          logger.debug(`${key} set to ${value}`)
+          console.error(error.message)
+          if (error.help) {
+            logger.help(error.help)
+          }
         }
+      }
 
-        // verbose/debug preExisted key/value
-        const preExisted = processedEnv.preExisted
-        for (const [key, value] of Object.entries(preExisted)) {
-          logger.verbose(
-            `${key} pre-exists (protip: use --overload to override)`
-          )
-          logger.debug(
-            `${key} pre-exists as ${value} (protip: use --overload to override)`
-          )
-        }
+      Object.assign(parsedAll, processedEnv.injected || {})
+      Object.assign(parsedAll, processedEnv.preExisted || {}) // preExisted 'wins'
+
+      // debug parsed
+      logger.debug(processedEnv.parsed)
+
+      // verbose/debug injected key/value
+      for (const [key, value] of Object.entries(processedEnv.injected || {})) {
+        logger.verbose(`${key} set`)
+        logger.debug(`${key} set to ${value}`)
+      }
+
+      // verbose/debug preExisted key/value
+      for (const [key, value] of Object.entries(processedEnv.preExisted || {})) {
+        logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
+        logger.debug(`${key} pre-exists as ${value} (protip: use --overload to override)`)
       }
     }
 
@@ -151,6 +134,8 @@ const config = function (options = {}) {
       return { parsed: parsedAll }
     }
   } catch (error) {
+    if (strict) throw error // throw immediately if strict
+
     logger.error(error.message)
     if (error.help) {
       logger.help(error.help)
@@ -189,17 +174,6 @@ const genexample = function (directory, envFile) {
   return new Genexample(directory, envFile).run()
 }
 
-/** @type {import('./main').get} */
-const get = function (
-  key,
-  envs = [],
-  overload = false,
-  DOTENV_KEY = '',
-  all = false
-) {
-  return new Get(key, envs, overload, DOTENV_KEY, all).run()
-}
-
 /** @type {import('./main').keypair} */
 const keypair = function (envFile, key) {
   return new Keypair(envFile, key).run()
@@ -211,7 +185,6 @@ module.exports = {
   parse,
   // actions related
   ls,
-  get,
   keypair,
   genexample,
   // expose for libs depending on @dotenvx/dotenvx - like dotenvx-pro

package/src/lib/services/decrypt.js

@@ -5,6 +5,7 @@ const picomatch = require('picomatch')
 
 const TYPE_ENV_FILE = 'envFile'
 
+const Errors = require('./../helpers/errors')
 const guessPrivateKeyName = require('./../helpers/guessPrivateKeyName')
 const findPrivateKey = require('./../helpers/findPrivateKey')
 const decryptValue = require('./../helpers/decryptValue')
@@ -101,10 +102,7 @@ class Decrypt {
       }
     } catch (e) {
       if (e.code === 'ENOENT') {
-        const error = new Error(`missing ${envFilepath} file (${filepath})`)
-        error.code = 'MISSING_ENV_FILE'
-
-        row.error = error
+        row.error = new Errors({ envFilepath, filepath }).missingEnvFile()
       } else {
         row.error = e
       }

package/src/lib/services/encrypt.js

@@ -5,6 +5,7 @@ const picomatch = require('picomatch')
 
 const TYPE_ENV_FILE = 'envFile'
 
+const Errors = require('./../helpers/errors')
 const guessPrivateKeyName = require('./../helpers/guessPrivateKeyName')
 const guessPublicKeyName = require('./../helpers/guessPublicKeyName')
 const encryptValue = require('./../helpers/encryptValue')
@@ -181,10 +182,7 @@ class Encrypt {
       }
     } catch (e) {
       if (e.code === 'ENOENT') {
-        const error = new Error(`missing ${envFilepath} file (${filepath})`)
-        error.code = 'MISSING_ENV_FILE'
-
-        row.error = error
+        row.error = new Errors({ envFilepath, filepath }).missingEnvFile()
       } else {
         row.error = e
       }

package/src/lib/services/genexample.js

@@ -2,6 +2,7 @@ const fsx = require('./../helpers/fsx')
 const path = require('path')
 const dotenv = require('dotenv')
 
+const Errors = require('../helpers/errors')
 const findEnvFiles = require('../helpers/findEnvFiles')
 const replace = require('../helpers/replace')
 
@@ -39,13 +40,8 @@ class Genexample {
     for (const envFilepath of envFilepaths) {
       const filepath = path.resolve(this.directory, envFilepath)
       if (!fsx.existsSync(filepath)) {
-        const code = 'MISSING_ENV_FILE'
-        const message = `file does not exist at [${filepath}]`
-        const help = `? add it with [echo "HELLO=World" > ${envFilepath}] and then run [dotenvx genexample]`
-
-        const error = new Error(message)
-        error.code = code
-        error.help = help
+        const error = new Errors({ envFilepath, filepath }).missingEnvFile()
+        error.help = `? add it with [echo "HELLO=World" > ${envFilepath}] and then run [dotenvx genexample]`
         throw error
       }
 

package/src/lib/services/get.js

@@ -1,41 +1,58 @@
 const Run = require('./run')
+const Errors = require('./../helpers/errors')
 
 class Get {
-  constructor (key, envs = [], overload = false, DOTENV_KEY = '', all = false) {
+  constructor (key, envs = [], overload = false, DOTENV_KEY = '', all = false, strict = false) {
     this.key = key
     this.envs = envs
     this.overload = overload
     this.DOTENV_KEY = DOTENV_KEY
     this.all = all
+    this.strict = strict
   }
 
   run () {
     const processEnv = { ...process.env }
     const { processedEnvs } = new Run(this.envs, this.overload, this.DOTENV_KEY, processEnv).run()
 
-    if (!this.key) {
+    const errors = []
+    for (const processedEnv of processedEnvs) {
+      for (const error of processedEnv.errors) {
+        errors.push(error)
+      }
+    }
+
+    if (this.key) {
+      const parsed = {}
+      const value = processEnv[this.key]
+      parsed[this.key] = value
+
+      if (value === undefined) {
+        errors.push(new Errors({ key: this.key }).missingKey())
+      }
+
+      return { parsed, errors }
+    } else {
       // if user wants to return ALL envs (even prior set on machine)
       if (this.all) {
-        return processEnv
+        return { parsed: processEnv, errors }
       }
 
       // typical scenario - return only envs that were identified in the .env file
       // iterate over all processedEnvs.parsed and grab from processEnv
       /** @type {Record<string, string>} */
-      const result = {}
+      const parsed = {}
       for (const processedEnv of processedEnvs) {
         // parsed means we saw the key in a file or --env flag. this effectively filters out any preset machine envs - while still respecting complex evaluating, expansion, and overload. in other words, the value might be the machine value because the key was displayed in a .env file
         if (processedEnv.parsed) {
           for (const key of Object.keys(processedEnv.parsed)) {
-            result[key] = processEnv[key]
+            parsed[key] = processEnv[key]
           }
         }
       }
 
-      return result
+      return { parsed, errors }
     }
-
-    return processEnv[this.key]
   }
 }
 

package/src/lib/services/run.js

@@ -8,6 +8,7 @@ const TYPE_ENV_VAULT_FILE = 'envVaultFile'
 
 const decrypt = require('./../helpers/decrypt')
 const Parse = require('./../helpers/parse')
+const Errors = require('./../helpers/errors')
 const parseEnvironmentFromDotenvKey = require('./../helpers/parseEnvironmentFromDotenvKey')
 const detectEncoding = require('./../helpers/detectEncoding')
 const findPrivateKey = require('./../helpers/findPrivateKey')
@@ -59,9 +60,9 @@ class Run {
     row.string = env
 
     try {
-      const { parsed, warnings, injected, preExisted } = new Parse(env, null, this.processEnv, this.overload).run()
+      const { parsed, errors, injected, preExisted } = new Parse(env, null, this.processEnv, this.overload).run()
       row.parsed = parsed
-      row.warnings = warnings
+      row.errors = errors
       row.injected = injected
       row.preExisted = preExisted
 
@@ -73,7 +74,7 @@ class Run {
         this.uniqueInjectedKeys.add(key) // track uniqueInjectedKeys across multiple files
       }
     } catch (e) {
-      row.error = e
+      row.errors = [e]
     }
 
     this.processedEnvs.push(row)
@@ -91,10 +92,10 @@ class Run {
       this.readableFilepaths.add(envFilepath)
 
       const privateKey = findPrivateKey(envFilepath)
-      const { parsed, warnings, injected, preExisted } = new Parse(src, privateKey, this.processEnv, this.overload).run()
+      const { parsed, errors, injected, preExisted } = new Parse(src, privateKey, this.processEnv, this.overload).run()
 
       row.parsed = parsed
-      row.warnings = warnings
+      row.errors = errors
       row.injected = injected
       row.preExisted = preExisted
 
@@ -104,13 +105,10 @@ class Run {
         this.uniqueInjectedKeys.add(key) // track uniqueInjectedKeys across multiple files
       }
     } catch (e) {
-      if (e.code === 'ENOENT') {
-        const error = new Error(`missing ${envFilepath} file (${filepath})`)
-        error.code = 'MISSING_ENV_FILE'
-
-        row.error = error
+      if (e.code === 'ENOENT' || e.code === 'EISDIR') {
+        row.errors = [new Errors({ envFilepath, filepath }).missingEnvFile()]
       } else {
-        row.error = e
+        row.errors = [e]
       }
     }
 
@@ -162,9 +160,9 @@ class Run {
 
     try {
       // parse this. it's the equivalent of the .env file
-      const { parsed, warnings, injected, preExisted } = new Parse(decrypted, null, this.processEnv, this.overload).run()
+      const { parsed, errors, injected, preExisted } = new Parse(decrypted, null, this.processEnv, this.overload).run()
       row.parsed = parsed
-      row.warnings = warnings
+      row.errors = errors
       row.injected = injected
       row.preExisted = preExisted
 
@@ -174,7 +172,7 @@ class Run {
         this.uniqueInjectedKeys.add(key) // track uniqueInjectedKeys across multiple files
       }
     } catch (e) {
-      row.error = e
+      row.errors = [e]
     }
 
     this.processedEnvs.push(row)

package/src/lib/services/sets.js

@@ -4,6 +4,7 @@ const dotenv = require('dotenv')
 
 const TYPE_ENV_FILE = 'envFile'
 
+const Errors = require('./../helpers/errors')
 const guessPrivateKeyName = require('./../helpers/guessPrivateKeyName')
 const guessPublicKeyName = require('./../helpers/guessPublicKeyName')
 const encryptValue = require('./../helpers/encryptValue')
@@ -169,10 +170,7 @@ class Sets {
       }
     } catch (e) {
       if (e.code === 'ENOENT') {
-        const error = new Error(`missing ${envFilepath} file (${filepath})`)
-        error.code = 'MISSING_ENV_FILE'
-
-        row.error = error
+        row.error = new Errors({ envFilepath, filepath }).missingEnvFile()
       } else {
         row.error = e
       }