@dotenvx/dotenvx 1.57.0 → 1.57.1

package/CHANGELOG.md

@@ -2,7 +2,22 @@
 
 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.57.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.57.1...main)
+
+## [1.57.1](https://github.com/dotenvx/dotenvx/compare/v1.57.0...v1.57.1) (2026-03-21)
+
+### Changes
+
+* improved error logs and compacted most to a single line ([#755](https://github.com/dotenvx/dotenvx/pull/755))
+* introduced leading log glyphs as a visual status language:
+
+  * `◈` success action (encrypted)
+  * `◇` success action (set plain value, decrypted)
+  * `⟳` success action (rotated)
+  * `○` informational no-op (no changes)
+  * `▣` success action for generated/updated support files
+  * `⚠` warning
+  * `☠` error
 
 ## [1.57.0](https://github.com/dotenvx/dotenvx/compare/v1.56.0...v1.57.0) (2026-03-19)
 
@@ -1783,4 +1798,3 @@ prevent committing a `.env*` file to code. append to `.gitignore`, `.dockerignor
 ## 0.3.9 and prior
 
 Please see commit history.
-

package/README.md

@@ -30,7 +30,20 @@ console.log(`Hello ${process.env.HELLO}`)
 
 or install globally - *unlocks dotenv for any language, framework, or platform!*
 
-<details><summary>with curl 🌐 </summary><br>
+<details><summary>with npm 🌍</summary><br>
+
+```sh
+npm i -g @dotenvx/dotenvx
+dotenvx help
+```
+
+[![npm installs](https://img.shields.io/npm/dt/@dotenvx/dotenvx)](https://npmjs.com/@dotenvx/dotenvx)
+
+&nbsp;
+
+</details>
+
+<details><summary>with curl 🌐</summary><br>
 
 ```sh
 curl -sfS https://dotenvx.sh | sh
@@ -936,8 +949,7 @@ For example, when missing a custom .env file:
 
 ```sh
 $ dotenvx run -f .env.missing -- echo $HELLO
-[MISSING_ENV_FILE] missing .env.missing file (/Users/scottmotte/Code/dotenvx/playground/apr-16/.env.missing)
-[MISSING_ENV_FILE] https://github.com/dotenvx/dotenvx/issues/484 and re-run [dotenvx run -- echo]
+[MISSING_ENV_FILE] missing file (/Users/scottmotte/Code/dotenvx/playground/apr-16/.env.missing). fix: [echo "HELLO=World" > .env.missing]
 ```
 
 or when missing a KEY:
@@ -945,7 +957,7 @@ or when missing a KEY:
 ```sh
 $ echo "HELLO=World" > .env
 $ dotenvx get GOODBYE
-[MISSING_KEY] missing GOODBYE key
+[MISSING_KEY] missing key (GOODBYE)
 ```
 
 </details>
@@ -1172,8 +1184,7 @@ Exit with code `1` if any errors are encountered - like a missing .env file or d
 $ 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]
+[MISSING_ENV_FILE] missing file (/path/to/.env.missing). fix: [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.
@@ -1326,7 +1337,7 @@ Exit with code `1` if any errors are encountered - like a missing key, missing .
 
 ```sh
 $ dotenvx get DOES_NOT_EXIST --strict
-[MISSING_KEY] missing DOES_NOT_EXIST key
+[MISSING_KEY] missing key (DOES_NOT_EXIST)
 ```
 
 </details>

package/package.json

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

package/src/cli/actions/decrypt.js

@@ -2,7 +2,6 @@ const fsx = require('./../../lib/helpers/fsx')
 const { logger } = require('./../../shared/logger')
 
 const Decrypt = require('./../../lib/services/decrypt')
-
 const catchAndLog = require('../../lib/helpers/catchAndLog')
 
 function decrypt () {
@@ -23,10 +22,7 @@ function decrypt () {
     for (const processedEnv of processedEnvs) {
       if (processedEnv.error) {
         errorCount += 1
-        logger.error(processedEnv.error.message)
-        if (processedEnv.error.help) {
-          logger.error(processedEnv.error.help)
-        }
+        logger.error(processedEnv.error.messageWithHelp)
       } else {
         console.log(processedEnv.envSrc)
       }
@@ -50,16 +46,7 @@ function decrypt () {
 
         if (processedEnv.error) {
           errorCount += 1
-
-          if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-            logger.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)
-            if (processedEnv.error.help) {
-              logger.error(processedEnv.error.help)
-            }
-          }
+          logger.error(processedEnv.error.messageWithHelp)
         } else if (processedEnv.changed) {
           fsx.writeFileX(processedEnv.filepath, processedEnv.envSrc)
 

package/src/cli/actions/encrypt.js

@@ -34,15 +34,7 @@ function encrypt () {
       for (const processedEnv of processedEnvs) {
         logger.verbose(`encrypting ${processedEnv.envFilepath} (${processedEnv.filepath})`)
         if (processedEnv.error) {
-          if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-            logger.warn(processedEnv.error.message)
-            logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.envFilepath}] and re-run [dotenvx encrypt]`)
-          } else {
-            logger.warn(processedEnv.error.message)
-            if (processedEnv.error.help) {
-              logger.help(processedEnv.error.help)
-            }
-          }
+          logger.warn(processedEnv.error.messageWithHelp)
         } else if (processedEnv.changed) {
           fsx.writeFileX(processedEnv.filepath, processedEnv.envSrc)
 

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

@@ -2,6 +2,7 @@ const fsx = require('./../../../lib/helpers/fsx')
 const path = require('path')
 const main = require('./../../../lib/main')
 const { logger } = require('./../../../shared/logger')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
 
 function genexample (directory) {
   logger.debug(`directory: ${directory}`)
@@ -27,13 +28,7 @@ function genexample (directory) {
       logger.info('○ no changes (.env.example)')
     }
   } catch (error) {
-    logger.error(error.message)
-    if (error.help) {
-      logger.help(error.help)
-    }
-    if (error.code) {
-      logger.debug(`ERROR_CODE: ${error.code}`)
-    }
+    catchAndLog(error)
     process.exit(1)
   }
 }

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

@@ -1,6 +1,7 @@
 const { logger } = require('./../../../shared/logger')
 
 const Prebuild = require('./../../../lib/services/prebuild')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
 
 function prebuild (directory) {
   // debug args
@@ -16,19 +17,12 @@ function prebuild (directory) {
     } = new Prebuild(directory, options).run()
 
     for (const warning of warnings) {
-      logger.warn(warning.message)
-      if (warning.help) {
-        logger.help(warning.help)
-      }
+      logger.warn(warning.messageWithHelp)
     }
 
     logger.success(successMessage)
   } catch (error) {
-    logger.error(error.message)
-    if (error.help) {
-      logger.help(error.help)
-    }
-
+    catchAndLog(error)
     process.exit(1)
   }
 }

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

@@ -1,6 +1,7 @@
 const { logger } = require('./../../../shared/logger')
 
 const Precommit = require('./../../../lib/services/precommit')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
 
 function precommit (directory) {
   // debug args
@@ -16,19 +17,12 @@ function precommit (directory) {
     } = new Precommit(directory, options).run()
 
     for (const warning of warnings) {
-      logger.warn(warning.message)
-      if (warning.help) {
-        logger.help(warning.help)
-      }
+      logger.warn(warning.messageWithHelp)
     }
 
     logger.success(successMessage)
   } catch (error) {
-    logger.error(error.message)
-    if (error.help) {
-      logger.help(error.help)
-    }
-
+    catchAndLog(error)
     process.exit(1)
   }
 }

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

@@ -12,8 +12,8 @@ function scan () {
     childProcess.execSync('gitleaks version', { stdio: ['ignore', 'pipe', 'ignore'] })
   } catch (error) {
     logger.error('gitleaks: command not found')
-    logger.help('? install gitleaks:      [brew install gitleaks]')
-    logger.help('? other install options: [https://github.com/gitleaks/gitleaks]')
+    logger.help('fix: install gitleaks:      [brew install gitleaks]')
+    logger.help('fix: other install options: [https://github.com/gitleaks/gitleaks]')
     process.exit(1)
     return
   }

package/src/cli/actions/get.js

@@ -2,6 +2,7 @@ const { logger } = require('./../../shared/logger')
 
 const conventions = require('./../../lib/helpers/conventions')
 const escape = require('./../../lib/helpers/escape')
+const catchAndLog = require('./../../lib/helpers/catchAndLog')
 
 const Get = require('./../../lib/services/get')
 
@@ -35,10 +36,7 @@ function get (key) {
         continue // ignore error
       }
 
-      logger.error(error.message)
-      if (error.help) {
-        logger.error(error.help)
-      }
+      logger.error(error.messageWithHelp)
     }
 
     if (key) {
@@ -75,10 +73,7 @@ function get (key) {
       }
     }
   } catch (error) {
-    logger.error(error.message)
-    if (error.help) {
-      logger.error(error.help)
-    }
+    catchAndLog(error)
     process.exit(1)
   }
 }

package/src/cli/actions/rotate.js

@@ -38,15 +38,7 @@ function rotate () {
       for (const processedEnv of processedEnvs) {
         logger.verbose(`rotating ${processedEnv.envFilepath} (${processedEnv.filepath})`)
         if (processedEnv.error) {
-          if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-            logger.warn(processedEnv.error.message)
-            logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.envFilepath}] and re-run [dotenvx rotate]`)
-          } else {
-            logger.warn(processedEnv.error.message)
-            if (processedEnv.error.help) {
-              logger.help(processedEnv.error.help)
-            }
-          }
+          logger.warn(processedEnv.error.messageWithHelp)
         } else if (processedEnv.changed) {
           fsx.writeFileX(processedEnv.filepath, processedEnv.envSrc)
           if (processedEnv.privateKeyAdded) {

package/src/cli/actions/run.js

@@ -3,6 +3,7 @@ const { logger } = require('./../../shared/logger')
 
 const executeCommand = require('./../../lib/helpers/executeCommand')
 const Run = require('./../../lib/services/run')
+const catchAndLog = require('./../../lib/helpers/catchAndLog')
 
 const conventions = require('./../../lib/helpers/conventions')
 
@@ -64,18 +65,10 @@ async function run () {
 
         if (options.strict) throw error // throw if strict and not ignored
 
-        if (error.code === 'MISSING_ENV_FILE') {
-          if (!options.convention) { // do not output error for conventions (too noisy)
-            logger.error(error.message)
-            if (error.help) {
-              logger.error(`${error.help} and re-run [dotenvx run -- ${commandArgs.join(' ')}]`)
-            }
-          }
+        if (error.code === 'MISSING_ENV_FILE' && options.convention) { // do not output error for conventions (too noisy)
+          // intentionally quiet
         } else {
-          logger.error(error.message)
-          if (error.help) {
-            logger.error(error.help)
-          }
+          logger.error(error.messageWithHelp)
         }
       }
 
@@ -106,10 +99,7 @@ async function run () {
 
     logger.successv(msg)
   } catch (error) {
-    logger.error(error.message)
-    if (error.help) {
-      logger.error(error.help)
-    }
+    catchAndLog(error)
     process.exit(1)
   }
 

package/src/cli/actions/set.js

@@ -40,15 +40,7 @@ function set (key, value) {
       logger.verbose(`setting for ${processedEnv.envFilepath}`)
 
       if (processedEnv.error) {
-        if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-          logger.warn(processedEnv.error.message)
-          logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.envFilepath}] and re-run [dotenvx set]`)
-        } else {
-          logger.warn(processedEnv.error.message)
-          if (processedEnv.error.help) {
-            logger.help(processedEnv.error.help)
-          }
-        }
+        logger.warn(processedEnv.error.messageWithHelp)
       } else {
         fsx.writeFileX(processedEnv.filepath, processedEnv.envSrc)
 

package/src/cli/dotenvx.js

@@ -30,8 +30,7 @@ const commanderVersion = getCommanderVersion()
 if (commanderVersion && parseInt(commanderVersion.split('.')[0], 10) >= 12) {
   const message = `dotenvx depends on commander@11.x.x but you are attempting to hoist commander@${commanderVersion}`
   const error = new Errors({ message }).dangerousDependencyHoist()
-  logger.error(error.message)
-  if (error.help) logger.error(error.help)
+  logger.error(error.messageWithHelp)
 }
 
 // global log levels

package/src/lib/helpers/catchAndLog.js

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

package/src/lib/helpers/conventions.js

@@ -1,3 +1,5 @@
+const Errors = require('./errors')
+
 function conventions (convention) {
   const env = process.env.DOTENV_ENV || process.env.NODE_ENV || 'development'
 
@@ -19,7 +21,7 @@ function conventions (convention) {
       { type: 'envFile', value: '.env.defaults' }
     ]
   } else {
-    throw new Error(`INVALID_CONVENTION: '${convention}'. permitted conventions: ['nextjs', 'flow']`)
+    throw new Errors({ convention }).invalidConvention()
   }
 }
 

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

@@ -30,7 +30,7 @@ function decryptKeyValue (key, value, privateKeyName, privateKey) {
         if (e.message === 'Invalid private key') {
           decryptionError = new Errors({ key, privateKeyName, privateKey }).invalidPrivateKey()
         } else if (e.message === 'Unsupported state or unable to authenticate data') {
-          decryptionError = new Errors({ key, privateKeyName, privateKey }).looksWrongPrivateKey()
+          decryptionError = new Errors({ key, privateKeyName, privateKey }).wrongPrivateKey()
         } else if (e.message === 'Point of length 65 was invalid. Expected 33 compressed bytes or 65 uncompressed bytes') {
           decryptionError = new Errors({ key, privateKeyName, privateKey }).malformedEncryptedData()
         } else {

package/src/lib/helpers/errors.js

@@ -1,5 +1,26 @@
 const truncate = require('./truncate')
 
+const ISSUE_BY_CODE = {
+  COMMAND_EXITED_WITH_CODE: 'https://github.com/dotenvx/dotenvx/issues/new',
+  COMMAND_SUBSTITUTION_FAILED: 'https://github.com/dotenvx/dotenvx/issues/532',
+  DECRYPTION_FAILED: 'https://github.com/dotenvx/dotenvx/issues/757',
+  DANGEROUS_DEPENDENCY_HOIST: 'https://github.com/dotenvx/dotenvx/issues/622',
+  INVALID_COLOR: 'must be 256 colors',
+  INVALID_CONVENTION: 'https://github.com/dotenvx/dotenvx/issues/761',
+  INVALID_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/465',
+  INVALID_PUBLIC_KEY: 'https://github.com/dotenvx/dotenvx/issues/756',
+  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_FILE: 'https://github.com/dotenvx/dotenvx/issues/484',
+  MISSING_ENV_FILES: 'https://github.com/dotenvx/dotenvx/issues/760',
+  MISSING_KEY: 'https://github.com/dotenvx/dotenvx/issues/759',
+  MISSING_LOG_LEVEL: 'must be valid log level',
+  MISSING_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/464',
+  PRECOMMIT_HOOK_MODIFY_FAILED: 'try again or report error',
+  WRONG_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/466'
+}
+
 class Errors {
   constructor (options = {}) {
     this.filepath = options.filepath
@@ -8,118 +29,252 @@ class Errors {
     this.key = options.key
     this.privateKey = options.privateKey
     this.privateKeyName = options.privateKeyName
+    this.publicKeyName = options.publicKeyName
     this.publicKey = options.publicKey
     this.publicKeyExisting = options.publicKeyExisting
     this.command = options.command
 
     this.message = options.message
+    this.code = options.code
+    this.help = options.help
+    this.debug = options.debug
+
+    this.convention = options.convention
+    this.directory = options.directory
+    this.exitCode = options.exitCode
+    this.level = options.level
+    this.color = options.color
+    this.error = options.error
   }
 
-  missingEnvFile () {
-    const code = 'MISSING_ENV_FILE'
-    const message = `[${code}] missing ${this.envFilepath} file (${this.filepath})`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/484`
+  custom () {
+    const e = new Error(this.message)
+    if (this.code) e.code = this.code
+    if (this.help) e.help = this.help
+    if (this.code && !e.help) e.help = `fix: [${ISSUE_BY_CODE[this.code]}]`
+    e.messageWithHelp = `${e.message}. ${e.help}`
+    if (this.debug) e.debug = this.debug
+    return e
+  }
+
+  commandExitedWithCode () {
+    const code = 'COMMAND_EXITED_WITH_CODE'
+    const message = `[${code}] Command exited with exit code ${this.exitCode}`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
-  missingKey () {
-    const code = 'MISSING_KEY'
-    const message = `[${code}] missing ${this.key} key`
+  commandSubstitutionFailed () {
+    const code = 'COMMAND_SUBSTITUTION_FAILED'
+    const message = `[${code}] could not eval ${this.key} containing command '${this.command}': ${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
   }
 
-  missingPrivateKey () {
-    const code = 'MISSING_PRIVATE_KEY'
-    const message = `[${code}] could not decrypt ${this.key} using private key '${this.privateKeyName}=${truncate(this.privateKey)}'`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/464`
+  decryptionFailed () {
+    const code = 'DECRYPTION_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
+  }
+
+  dangerousDependencyHoist () {
+    const code = 'DANGEROUS_DEPENDENCY_HOIST'
+    const message = `[${code}] your environment has hoisted an incompatible version of a dotenvx dependency: ${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
+  }
+
+  invalidColor () {
+    const code = 'INVALID_COLOR'
+    const message = `[${code}] Invalid color ${this.color}`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
+  invalidConvention () {
+    const code = 'INVALID_CONVENTION'
+    const message = `[${code}] invalid convention (${this.convention})`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
   invalidPrivateKey () {
     const code = 'INVALID_PRIVATE_KEY'
     const message = `[${code}] could not decrypt ${this.key} using private key '${this.privateKeyName}=${truncate(this.privateKey)}'`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/465`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
+  invalidPublicKey () {
+    const code = 'INVALID_PUBLIC_KEY'
+    const message = `[${code}] could not encrypt using public key '${this.publicKeyName}=${truncate(this.publicKey)}'`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
+  malformedEncryptedData () {
+    const code = 'MALFORMED_ENCRYPTED_DATA'
+    const message = `[${code}] could not decrypt ${this.key} because encrypted data appears malformed`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
   mispairedPrivateKey () {
     const code = 'MISPAIRED_PRIVATE_KEY'
     const message = `[${code}] private key's derived public key (${truncate(this.publicKey)}) does not match the existing public key (${truncate(this.publicKeyExisting)})`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/752`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
-  looksWrongPrivateKey () {
-    const code = 'WRONG_PRIVATE_KEY'
-    const message = `[${code}] could not decrypt ${this.key} using private key '${this.privateKeyName}=${truncate(this.privateKey)}'`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/466`
+  missingDirectory () {
+    const code = 'MISSING_DIRECTORY'
+    const message = `[${code}] missing directory (${this.directory})`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
-  malformedEncryptedData () {
-    const code = 'MALFORMED_ENCRYPTED_DATA'
-    const message = `[${code}] could not decrypt ${this.key} because encrypted data appears malformed`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/467`
+  missingEnvFile () {
+    const code = 'MISSING_ENV_FILE'
+    const envFilepath = this.envFilepath || '.env'
+    const message = `[${code}] missing file (${envFilepath})`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
-  decryptionFailed () {
-    const code = 'DECRYPTION_FAILED'
-    const message = this.message
+  missingEnvFiles () {
+    const code = 'MISSING_ENV_FILES'
+    const message = `[${code}] no .env* files found`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
-  commandSubstitutionFailed () {
-    const code = 'COMMAND_SUBSTITUTION_FAILED'
-    const message = `[${code}] could not eval ${this.key} containing command '${this.command}': ${this.message}`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/532`
+  missingKey () {
+    const code = 'MISSING_KEY'
+    const message = `[${code}] missing key (${this.key})`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 
-  dangerousDependencyHoist () {
-    const code = 'DANGEROUS_DEPENDENCY_HOIST'
-    const message = `[${code}] your environment has hoisted an incompatible version of a dotenvx dependency: ${this.message}`
-    const help = `[${code}] https://github.com/dotenvx/dotenvx/issues/622`
+  missingLogLevel () {
+    const code = 'MISSING_LOG_LEVEL'
+    const message = `[${code}] missing log level '${this.level}'. implement in logger`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
+  missingPrivateKey () {
+    const code = 'MISSING_PRIVATE_KEY'
+    const message = `[${code}] could not decrypt ${this.key} using private key '${this.privateKeyName}=${truncate(this.privateKey)}'`
+    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}`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
 
     const e = new Error(message)
     e.code = code
     e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
+  wrongPrivateKey () {
+    const code = 'WRONG_PRIVATE_KEY'
+    const message = `[${code}] could not decrypt ${this.key} using private key '${this.privateKeyName}=${truncate(this.privateKey)}'`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
     return e
   }
 }
 
+Errors.ISSUE_BY_CODE = ISSUE_BY_CODE
+
 module.exports = Errors

package/src/lib/helpers/executeCommand.js

@@ -2,6 +2,7 @@ const path = require('path')
 const which = require('which')
 const execute = require('./../../lib/helpers/execute')
 const { logger } = require('./../../shared/logger')
+const Errors = require('./errors')
 
 async function executeCommand (commandArgs, env) {
   const signals = [
@@ -91,7 +92,7 @@ async function executeCommand (commandArgs, env) {
 
     if (exitCode !== 0) {
       logger.debug(`received exitCode ${exitCode}`)
-      throw new Error(`Command exited with exit code ${exitCode}`)
+      throw new Errors({ exitCode }).commandExitedWithCode()
     }
   } catch (error) {
     // no color on these errors as they can be standard errors for things like jest exiting with exitCode 1 for a single failed test.

package/src/lib/helpers/executeDynamic.js

@@ -1,7 +1,50 @@
 const path = require('path')
+const fs = require('fs')
 const childProcess = require('child_process')
 const { logger } = require('../../shared/logger')
 
+function installCommandForOps () {
+  const userAgent = process.env.npm_config_user_agent || ''
+  if (userAgent.startsWith('pnpm/')) return 'pnpm add -g @dotenvx/dotenvx-ops'
+  if (userAgent.startsWith('yarn/')) return 'yarn global add @dotenvx/dotenvx-ops'
+  if (userAgent.startsWith('npm/')) return 'npm i -g @dotenvx/dotenvx-ops'
+
+  const cwd = process.cwd()
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm add -g @dotenvx/dotenvx-ops'
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn global add @dotenvx/dotenvx-ops'
+  if (
+    fs.existsSync(path.join(cwd, 'package-lock.json')) ||
+    fs.existsSync(path.join(cwd, 'npm-shrinkwrap.json'))
+  ) return 'npm i -g @dotenvx/dotenvx-ops'
+
+  if (fs.existsSync(path.join(cwd, 'package.json'))) return 'npm i -g @dotenvx/dotenvx-ops'
+
+  return 'curl -sfS https://dotenvx.sh/ops | sh'
+}
+
+function opsBanner (installCommand) {
+  const lines = [
+    '',
+    '   ██████╗ ██████╗ ███████╗',
+    '  ██╔═══██╗██╔══██╗██╔════╝',
+    '  ██║   ██║██████╔╝███████╗',
+    '  ██║   ██║██╔═══╝ ╚════██║',
+    '  ╚██████╔╝██║     ███████║',
+    '   ╚═════╝ ╚═╝     ╚══════╝',
+    '',
+    '  KEYS OFF COMPUTER: Add hardened key protection with dotenvx-ops.',
+    `  Install now: [${installCommand}]`,
+    '  Learn more: [https://dotenvx.com/ops]'
+  ]
+
+  const innerWidth = Math.max(67, ...lines.map((line) => line.length))
+  const top = ` ${'_'.repeat(innerWidth)}`
+  const middle = lines.map((line) => `|${line.padEnd(innerWidth)}|`).join('\n')
+  const bottom = `|${'_'.repeat(innerWidth)}|`
+
+  return `${top}\n${middle}\n${bottom}`
+}
+
 function executeDynamic (program, command, rawArgs) {
   if (!command) {
     program.outputHelp()
@@ -23,23 +66,8 @@ function executeDynamic (program, command, rawArgs) {
   const result = childProcess.spawnSync(`dotenvx-${command}`, forwardedArgs, { stdio: 'inherit', env })
   if (result.error) {
     if (command === 'ops') {
-      const ops = ` ___________________________________________________________________
-|                                                                   |
-|   ██████╗ ██████╗ ███████╗                                        |
-|  ██╔═══██╗██╔══██╗██╔════╝                                        |
-|  ██║   ██║██████╔╝███████╗                                        |
-|  ██║   ██║██╔═══╝ ╚════██║                                        |
-|  ╚██████╔╝██║     ███████║                                        |
-|   ╚═════╝ ╚═╝     ╚══════╝                                        |
-|                                                                   |
-|  Learn more at [https://dotenvx.com/ops]                          |
-|___________________________________________________________________|`
-
-      console.log(ops)
-      console.log('')
-      logger.warn(`[INSTALLATION_NEEDED] install dotenvx-${command} to use [dotenvx ${command}] 🛡️`)
-      logger.help('⮕  next run: [curl -sfS https://dotenvx.sh/ops | sh]')
-      logger.help('⮕  see more: [https://dotenvx.com/ops]')
+      const installCommand = installCommandForOps()
+      console.log(opsBanner(installCommand))
     } else {
       logger.info(`error: unknown command '${command}'`)
     }

package/src/lib/helpers/findEnvFiles.js

@@ -1,4 +1,5 @@
 const fsx = require('./fsx')
+const Errors = require('./errors')
 
 const RESERVED_ENV_FILES = ['.env.project', '.env.keys', '.env.me', '.env.x', '.env.example']
 
@@ -14,10 +15,7 @@ function findEnvFiles (directory) {
     return envFiles
   } catch (e) {
     if (e.code === 'ENOENT') {
-      const error = new Error(`missing directory (${directory})`)
-      error.code = 'MISSING_DIRECTORY'
-
-      throw error
+      throw new Errors({ directory }).missingDirectory()
     } else {
       throw e
     }

package/src/lib/helpers/installPrecommitHook.js

@@ -1,5 +1,6 @@
 const fsx = require('./fsx')
 const path = require('path')
+const Errors = require('./errors')
 
 const HOOK_SCRIPT = `#!/bin/sh
 
@@ -45,8 +46,7 @@ class InstallPrecommitHook {
         successMessage
       }
     } catch (err) {
-      const error = new Error(`failed to modify pre-commit hook: ${err.message}`)
-      throw error
+      throw new Errors({ error: err }).precommitHookModifyFailed()
     }
   }
 

package/src/lib/main.js

@@ -81,16 +81,10 @@ const config = function (options = {}) {
 
         if (error.code === 'MISSING_ENV_FILE') {
           if (!options.convention) { // do not output error for conventions (too noisy)
-            logger.error(error.message)
-            if (error.help) {
-              logger.error(error.help)
-            }
+            logger.error(error.messageWithHelp)
           }
         } else {
-          logger.error(error.message)
-          if (error.help) {
-            logger.error(error.help)
-          }
+          logger.error(error.messageWithHelp)
         }
       }
 
@@ -127,10 +121,7 @@ const config = function (options = {}) {
   } catch (error) {
     if (strict) throw error // throw immediately if strict
 
-    logger.error(error.message)
-    if (error.help) {
-      logger.help(error.help)
-    }
+    logger.error(error.messageWithHelp)
 
     return { parsed: {}, error }
   }
@@ -154,10 +145,7 @@ const parse = function (src, options = {}) {
 
   // display any errors
   for (const error of errors) {
-    logger.error(error.message)
-    if (error.help) {
-      logger.error(error.help)
-    }
+    logger.error(error.messageWithHelp)
   }
 
   return parsed
@@ -199,15 +187,9 @@ const set = function (key, value, options = {}) {
     logger.verbose(`setting for ${processedEnv.envFilepath}`)
 
     if (processedEnv.error) {
-      if (processedEnv.error.code === 'MISSING_ENV_FILE') {
-        logger.warn(processedEnv.error.message)
-        logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.envFilepath}] and re-run [dotenvx set]`)
-      } else {
-        logger.warn(processedEnv.error.message)
-        if (processedEnv.error.help) {
-          logger.help(processedEnv.error.help)
-        }
-      }
+      const error = processedEnv.error
+      const message = error.messageWithHelp || (error.help ? `${error.message}. ${error.help}` : error.message)
+      logger.warn(message)
     } else {
       fsx.writeFileX(processedEnv.filepath, processedEnv.envSrc)
 
@@ -260,10 +242,7 @@ const get = function (key, options = {}) {
 
     if (options.strict) throw error // throw immediately if strict
 
-    logger.error(error.message)
-    if (error.help) {
-      logger.error(error.help)
-    }
+    logger.error(error.messageWithHelp)
   }
 
   if (key) {

package/src/lib/services/encrypt.js

@@ -122,7 +122,12 @@ class Encrypt {
         if (!encrypted) {
           row.keys.push(key) // track key(s)
 
-          const encryptedValue = encryptValue(value, publicKey)
+          let encryptedValue
+          try {
+            encryptedValue = encryptValue(value, publicKey)
+          } catch {
+            throw new Errors({ publicKeyName, publicKey }).invalidPublicKey()
+          }
 
           // once newSrc is built write it out
           envSrc = replace(envSrc, key, encryptedValue)

package/src/lib/services/genexample.js

@@ -17,14 +17,7 @@ class Genexample {
 
   run () {
     if (this.envFile.length < 1) {
-      const code = 'MISSING_ENV_FILES'
-      const message = 'no .env* files found'
-      const help = '? add one with [echo "HELLO=World" > .env] and then run [dotenvx genexample]'
-
-      const error = new Error(message)
-      error.code = code
-      error.help = help
-      throw error
+      throw new Errors().missingEnvFiles()
     }
 
     const keys = new Set()

package/src/lib/services/prebuild.js

@@ -4,6 +4,7 @@ const path = require('path')
 const ignore = require('ignore')
 
 const Ls = require('../services/ls')
+const Errors = require('../helpers/errors')
 
 const isFullyEncrypted = require('./../helpers/isFullyEncrypted')
 const packageJson = require('./../helpers/packageJson')
@@ -24,7 +25,10 @@ class Prebuild {
 
     // 1. check for .dockerignore file
     if (!fsx.existsSync('.dockerignore')) {
-      const warning = new Error(`[dotenvx@${packageJson.version}][prebuild] .dockerignore missing`)
+      const warning = new Errors({
+        message: `[dotenvx@${packageJson.version}][prebuild] .dockerignore missing`,
+        help: 'fix: [touch .dockerignore]'
+      }).custom()
       warnings.push(warning)
     } else {
       dockerignore = fsx.readFileX('.dockerignore')
@@ -42,8 +46,10 @@ class Prebuild {
       // check if that file is being ignored
       if (ig.ignores(file)) {
         if (file === '.env.example' || file === '.env.x') {
-          const warning = new Error(`[dotenvx@${packageJson.version}][prebuild] ${file} (currently ignored but should not be)`)
-          warning.help = `[dotenvx@${packageJson.version}][prebuild] ⮕  run [dotenvx ext gitignore --pattern !${file}]`
+          const warning = new Errors({
+            message: `[dotenvx@${packageJson.version}][prebuild] ${file} (currently ignored but should not be)`,
+            help: `fix: [dotenvx ext gitignore --pattern !${file}]`
+          }).custom()
           warnings.push(warning)
         }
       } else {
@@ -54,15 +60,13 @@ class Prebuild {
           // if contents are encrypted don't raise an error
           if (!encrypted) {
             let errorMsg = `[dotenvx@${packageJson.version}][prebuild] ${file} not protected (encrypted or dockerignored)`
-            let errorHelp = `[dotenvx@${packageJson.version}][prebuild] ⮕  run [dotenvx encrypt -f ${file}] or [dotenvx ext gitignore --pattern ${file}]`
+            let errorHelp = `fix: [dotenvx encrypt -f ${file}] or [dotenvx ext gitignore --pattern ${file}]`
             if (file.includes('.env.keys')) {
               errorMsg = `[dotenvx@${packageJson.version}][prebuild] ${file} not protected (dockerignored)`
-              errorHelp = `[dotenvx@${packageJson.version}][prebuild] ⮕  run [dotenvx ext gitignore --pattern ${file}]`
+              errorHelp = `fix: [dotenvx ext gitignore --pattern ${file}]`
             }
 
-            const error = new Error(errorMsg)
-            error.help = errorHelp
-            throw error
+            throw new Errors({ message: errorMsg, help: errorHelp }).custom()
           }
         }
       }

package/src/lib/services/precommit.js

@@ -8,6 +8,7 @@ const Ls = require('../services/ls')
 const isFullyEncrypted = require('./../helpers/isFullyEncrypted')
 const packageJson = require('./../helpers/packageJson')
 const InstallPrecommitHook = require('./../helpers/installPrecommitHook')
+const Errors = require('./../helpers/errors')
 const childProcess = require('child_process')
 const MISSING_GITIGNORE = '.env.keys' // by default only ignore .env.keys. all other .env* files COULD be included - as long as they are encrypted
 
@@ -37,7 +38,10 @@ class Precommit {
 
       // 1. check for .gitignore file
       if (!fsx.existsSync('.gitignore')) {
-        const warning = new Error(`[dotenvx@${packageJson.version}][precommit] .gitignore missing`)
+        const warning = new Errors({
+          message: `[dotenvx@${packageJson.version}][precommit] .gitignore missing`,
+          help: 'fix: [touch .gitignore]'
+        }).custom()
         warnings.push(warning)
       } else {
         gitignore = fsx.readFileX('.gitignore')
@@ -58,8 +62,10 @@ class Precommit {
           // check if that file is being ignored
           if (ig.ignores(file)) {
             if (file === '.env.example' || file === '.env.x') {
-              const warning = new Error(`[dotenvx@${packageJson.version}][precommit] ${file} (currently ignored but should not be)`)
-              warning.help = `[dotenvx@${packageJson.version}][precommit] ⮕  run [dotenvx ext gitignore --pattern !${file}]`
+              const warning = new Errors({
+                message: `[dotenvx@${packageJson.version}][precommit] ${file} (currently ignored but should not be)`,
+                help: `fix: [dotenvx ext gitignore --pattern !${file}]`
+              }).custom()
               warnings.push(warning)
             }
           } else {
@@ -70,15 +76,13 @@ class Precommit {
               // if contents are encrypted don't raise an error
               if (!encrypted) {
                 let errorMsg = `[dotenvx@${packageJson.version}][precommit] ${file} not protected (encrypted or gitignored)`
-                let errorHelp = `[dotenvx@${packageJson.version}][precommit] ⮕  run [dotenvx encrypt -f ${file}] or [dotenvx ext gitignore --pattern ${file}]`
+                let errorHelp = `fix: [dotenvx encrypt -f ${file}] or [dotenvx ext gitignore --pattern ${file}]`
                 if (file.includes('.env.keys')) {
                   errorMsg = `[dotenvx@${packageJson.version}][precommit] ${file} not protected (gitignored)`
-                  errorHelp = `[dotenvx@${packageJson.version}][precommit] ⮕  run [dotenvx ext gitignore --pattern ${file}]`
+                  errorHelp = `fix: [dotenvx ext gitignore --pattern ${file}]`
                 }
 
-                const error = new Error(errorMsg)
-                error.help = errorHelp
-                throw error
+                throw new Errors({ message: errorMsg, help: errorHelp }).custom()
               }
             }
           }

package/src/lib/services/rotate.js

@@ -131,7 +131,12 @@ class Rotate {
           row.keys.push(key) // track key(s)
 
           const decryptedValue = decryptKeyValue(key, value, privateKeyName, privateKeyValue) // get decrypted value
-          const encryptedValue = encryptValue(decryptedValue, newPublicKey) // encrypt with the new publicKey
+          let encryptedValue
+          try {
+            encryptedValue = encryptValue(decryptedValue, newPublicKey) // encrypt with the new publicKey
+          } catch {
+            throw new Errors({ publicKeyName, publicKey: newPublicKey }).invalidPublicKey()
+          }
 
           envSrc = replace(envSrc, key, encryptedValue)
         }

package/src/lib/services/sets.js

@@ -109,7 +109,11 @@ class Sets {
 
         row.publicKey = publicKey
         row.privateKey = privateKey
-        row.encryptedValue = encryptValue(this.value, publicKey)
+        try {
+          row.encryptedValue = encryptValue(this.value, publicKey)
+        } catch {
+          throw new Errors({ publicKeyName, publicKey }).invalidPublicKey()
+        }
         row.privateKeyName = privateKeyName
       }
 

package/src/shared/colors.js

@@ -1,4 +1,5 @@
 const depth = require('../lib/helpers/colorDepth')
+const Errors = require('../lib/helpers/errors')
 
 const colors16 = new Map([
   ['amber', 33],
@@ -6,7 +7,7 @@ const colors16 = new Map([
   ['gray', 37],
   ['green', 32],
   ['olive', 33],
-  ['orangered', 31], // mapped to red
+  ['orangered', 33], // mapped to yellow/brown
   ['plum', 35], // mapped to magenta
   ['red', 31],
   ['electricblue', 36],
@@ -19,21 +20,23 @@ const colors256 = new Map([
   ['gray', 244],
   ['green', 34],
   ['olive', 142],
-  ['orangered', 202],
+  ['orangered', 130], // burnished copper
   ['plum', 182],
-  ['red', 196],
+  ['red', 124], // brighter garnet
   ['electricblue', 45],
   ['dodgerblue', 33]
 ])
 
 const colorsTrueColor = new Map([
-  ['amber', [236, 213, 63]]
+  ['amber', [236, 213, 63]],
+  ['orangered', [138, 90, 43]], // #8A5A2B burnished copper
+  ['red', [140, 35, 50]] // #8C2332 brighter garnet
 ])
 
 function getColor (color) {
   const colorDepth = depth.getColorDepth()
   if (!colors256.has(color)) {
-    throw new Error(`Invalid color ${color}`)
+    throw new Errors({ color }).invalidColor()
   }
   if (colorDepth >= 24 && colorsTrueColor.has(color)) {
     const [r, g, b] = colorsTrueColor.get(color)

package/src/shared/logger.js

@@ -1,4 +1,5 @@
 const packageJson = require('../lib/helpers/packageJson')
+const Errors = require('../lib/helpers/errors')
 const { getColor, bold } = require('./colors')
 
 const levels = {
@@ -13,8 +14,8 @@ const levels = {
   silly: 6
 }
 
-const error = (m) => bold(getColor('red')(m))
-const warn = getColor('orangered')
+const error = (m) => bold(getColor('red')(`☠ ${m}`))
+const warn = (m) => getColor('orangered')(`⚠ ${m}`)
 const success = getColor('amber')
 const successv = getColor('amber')
 const info = getColor('gray')
@@ -33,7 +34,7 @@ function stderr (level, message) {
 
 function stdout (level, message) {
   if (levels[level] === undefined) {
-    throw new Error(`MISSING_LOG_LEVEL: '${level}'. implement in logger.`)
+    throw new Errors({ level }).missingLogLevel()
   }
 
   if (levels[level] <= currentLevel) {