@dotenvx/dotenvx 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -2,13 +2,29 @@
 
 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.9.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.11.0...main)
+
+## [2.11.0](https://github.com/dotenvx/dotenvx/compare/v2.10.0...v2.11.0) (2026-07-15)
+
+### Added
+
+* Add convenience method `dotenvx update` ([#897](https://github.com/dotenvx/dotenvx/pull/897))
+
+### Changed
+
+* BREAKING: Send informational messages like `injected env` to stderr instead of stdout. This makes it more reliable to do things like piping output to a file without needing `--quiet`. ([#898](https://github.com/dotenvx/dotenvx/pull/898))
+
+## [2.10.0](https://github.com/dotenvx/dotenvx/compare/v2.9.0...v2.10.0) (2026-07-15)
+
+### Added
+
+* Add `run --redact` to keep secrets out of command output. ([#894](https://github.com/dotenvx/dotenvx/pull/894))
 
 ## [2.9.0](https://github.com/dotenvx/dotenvx/compare/v2.8.0...v2.9.0) (2026-07-14)
 
 ### Changed
 
-* BREAKING: `ls` from `@dotenvx/dotenvx` is now async/await.
+* BREAKING: `ls` from `@dotenvx/dotenvx` is now async/await. ([#893](https://github.com/dotenvx/dotenvx/pull/893))
 
 ## [2.8.0](https://github.com/dotenvx/dotenvx/compare/v2.7.3...v2.8.0) (2026-07-14)
 

package/README.md

@@ -1471,6 +1471,24 @@ $ dotenvx set HELLO Dotenvx -fk .env.keys -f apps/app1/.env
 $ dotenvx run -fk .env.keys -f apps/app1/.env -- yourcommand
 ```
 
+</details>
+<details><summary>`run --redact`</summary><br>
+
+Redact successfully decrypted values from the command's stdout and stderr. The command still receives the real values; only its output is filtered.
+
+```sh
+$ touch .env
+$ dotenvx set SECRET super-secret-value
+$ echo "console.log(process.env.SECRET)" > index.js
+
+$ dotenvx run --redact --quiet -- node index.js
+[REDACTED]
+```
+
+Redaction is off by default. It applies only to values that were encrypted, successfully decrypted, and injected. Plaintext values are left unchanged. Matching is exact, so transformed or derived values are not redacted.
+
+Because redaction filters stdout and stderr, interactive commands that require a TTY may behave differently.
+
 </details>
 <details><summary>`run --mask`</summary><br>
 
@@ -2335,6 +2353,21 @@ $ dotenvx ls -ef '**/.env.prod*'
       └─ .env
 ```
 
+</details>
+<details><summary>`ls --json`</summary><br>
+
+Print all matching `.env` files as a JSON array of absolute filepaths. Progress and summary details are written to stderr, so stdout can be safely piped to another command or file.
+
+```sh
+$ dotenvx ls --json
+[
+  "/path/to/project/.env",
+  "/path/to/project/apps/backend/.env"
+]
+
+$ dotenvx ls --json > dotenv-files.json
+```
+
 </details>
 <details><summary>`genexample`</summary><br>
 

package/package.json

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

package/src/cli/actions/run.js

@@ -13,6 +13,8 @@ const resolveEnvKeysFile = require('../../lib/helpers/resolveEnvKeysFile')
 const mask = require('../../lib/helpers/mask')
 const maskEnvSrc = require('../../lib/helpers/maskEnvSrc')
 const maskProcessedEnvs = require('../../lib/helpers/maskProcessedEnvs')
+const decryptedValues = require('../../lib/helpers/decryptedValues')
+const { redactOutput } = require('../../lib/helpers/redactOutput')
 
 const { determine } = require('./../../lib/helpers/envResolution')
 
@@ -53,11 +55,13 @@ async function run () {
   const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts()))
   const spinnerOptions = typeof this.optsWithGlobals === 'function' ? this.optsWithGlobals() : options
   const maskEnabled = options.mask !== undefined
+  const redactEnabled = options.redact === true
   let showChar = options.mask
   if (options.mask === true) {
     showChar = 6
   }
   let commandEnv = process.env
+  let sensitiveValues = []
 
   let commandArgs = this.args
   if (commandArgs.length < 1) {
@@ -122,6 +126,10 @@ async function run () {
       }
     })
 
+    if (redactEnabled) {
+      sensitiveValues = decryptedValues(processedEnvs)
+    }
+
     if (maskEnabled) {
       commandEnv = { ...process.env }
       maskProcessedEnvs(processedEnvs, commandEnv, showChar)
@@ -156,18 +164,18 @@ async function run () {
       }
 
       // debug parsed
-      logger.debug(processedEnv.parsed)
+      logger.debug(redactOutput(processedEnv.parsed, sensitiveValues))
 
       // verbose/debug injected key/value
       for (const [key, value] of Object.entries(processedEnv.injected || {})) {
         logger.verbose(`${key} set`)
-        logger.debug(`${key} set to ${value}`)
+        logger.debug(redactOutput(`${key} set to ${value}`, sensitiveValues))
       }
 
       // verbose/debug existed key/value
       for (const [key, value] of Object.entries(processedEnv.existed || {})) {
         logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
-        logger.debug(`${key} pre-exists as ${value} (protip: use --overload to override)`)
+        logger.debug(redactOutput(`${key} pre-exists as ${value} (protip: use --overload to override)`, sensitiveValues))
       }
     }
 
@@ -189,7 +197,7 @@ async function run () {
     process.exit(1)
   }
 
-  await executeCommand(commandArgs, commandEnv)
+  await executeCommand(commandArgs, commandEnv, sensitiveValues)
 }
 
 module.exports = run

package/src/cli/actions/update.js

@@ -0,0 +1,15 @@
+const childProcess = require('child_process')
+
+const INSTALL_COMMAND = 'curl -sfS https://dotenvx.sh | sh'
+
+function update () {
+  if (process.pkg) {
+    childProcess.execSync(INSTALL_COMMAND, { stdio: 'inherit' })
+    return
+  }
+
+  console.log('global: npm install -g @dotenvx/dotenvx@latest')
+  console.log('local:  npm install @dotenvx/dotenvx@latest --save')
+}
+
+module.exports = update

package/src/cli/dotenvx.js

@@ -70,6 +70,7 @@ program.command('run')
   .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
   .option('--token <token>', 'set Armor ⛨ token')
   .option('--mask [characters]', 'inject masked values, optionally setting visible characters')
+  .option('--redact', 'redact decrypted values from command output', false)
   .option('--no-armor', 'disable Dotenvx Armor features')
   .option('--no-native', 'disable OS secret store features')
   .action(function (...args) {
@@ -226,6 +227,13 @@ program.command('doctor', { hidden: true })
     return require('./actions/doctor').apply(this, args)
   })
 
+// dotenvx update
+program.command('update')
+  .description('update dotenvx')
+  .action(function (...args) {
+    return require('./actions/update').apply(this, args)
+  })
+
 // dotenvx login (compatibility alias for dotenvx armor login)
 program.command('login', { hidden: true })
   .description('log in to move keys off-device, share with your team, and audit access')

package/src/lib/helpers/catchAndLog.js

@@ -1,11 +1,6 @@
 const { logger } = require('./../../shared/logger')
-const Errors = require('./errors')
 
 function catchAndLog (error) {
-  if (error.code === 'EACCES' || error.code === 'EPERM') {
-    error = new Errors({ filepath: error.path }).fileNotWritable()
-  }
-
   const msg = error.messageWithHelp || error.message
   if (msg) {
     logger.error(msg)

package/src/lib/helpers/colorDepth.js

@@ -1,7 +1,13 @@
 const { WriteStream } = require('tty')
 
-const getColorDepth = () => {
+const getColorDepth = (stream) => {
+  if (stream && !stream.isTTY) return 1
+
   try {
+    if (stream && typeof stream.getColorDepth === 'function') {
+      return stream.getColorDepth()
+    }
+
     return WriteStream.prototype.getColorDepth()
   } catch (error) {
     const term = process.env.TERM

package/src/lib/helpers/decryptedValues.js

@@ -0,0 +1,32 @@
+const { encrypted, scan } = require('@dotenvx/primitives')
+
+function decryptedValues (processedEnvs) {
+  const result = new Set()
+
+  for (const processedEnv of processedEnvs || []) {
+    const src = processedEnv.src || processedEnv.string
+    if (!src) continue
+
+    let rawParsed
+    try {
+      rawParsed = scan(src).parsed
+    } catch (error) {
+      continue
+    }
+
+    for (const [key, rawValues] of Object.entries(rawParsed || {})) {
+      const rawValue = rawValues[rawValues.length - 1]
+      const injectedValue = (processedEnv.injected || {})[key]
+
+      if (!encrypted(rawValue)) continue
+      if (injectedValue === undefined || injectedValue === null || injectedValue === '') continue
+      if (encrypted(injectedValue)) continue
+
+      result.add(`${injectedValue}`)
+    }
+  }
+
+  return [...result]
+}
+
+module.exports = decryptedValues

package/src/lib/helpers/executeCommand.js

@@ -3,8 +3,9 @@ const { which } = require('@dotenvx/tooling')
 const execute = require('./../../lib/helpers/execute')
 const { logger } = require('./../../shared/logger')
 const Errors = require('./errors')
+const { createRedactedStreamWriter, redactOutput } = require('./redactOutput')
 
-async function executeCommand (commandArgs, env) {
+async function executeCommand (commandArgs, env, sensitiveValues = []) {
   const FORWARD_SIGNAL_GRACE_MS = 1000
   const FORCE_KILL_GRACE_MS = 1000
   const signals = [
@@ -130,11 +131,27 @@ async function executeCommand (commandArgs, env) {
       }
     }
 
+    const redactStdout = sensitiveValues.length > 0
+    const redactStderr = sensitiveValues.length > 0
+
     child = execute.execa(commandArgs[0], commandArgs.slice(1), {
-      stdio: 'inherit',
+      stdio: ['inherit', redactStdout ? 'pipe' : 'inherit', redactStderr ? 'pipe' : 'inherit'],
+      buffer: false,
       env: { ...process.env, ...env }
     })
 
+    if (redactStdout && child.stdout) {
+      const stdoutWriter = createRedactedStreamWriter(process.stdout, sensitiveValues, child.stdout)
+      child.stdout.on('data', stdoutWriter.write)
+      child.stdout.once('end', stdoutWriter.flush)
+    }
+
+    if (redactStderr && child.stderr) {
+      const stderrWriter = createRedactedStreamWriter(process.stderr, sensitiveValues, child.stderr)
+      child.stderr.on('data', stderrWriter.write)
+      child.stderr.once('end', stderrWriter.flush)
+    }
+
     process.on('SIGINT', sigintHandler)
     process.on('SIGTERM', sigtermHandler)
 
@@ -157,7 +174,7 @@ async function executeCommand (commandArgs, env) {
       if (error.code === 'ENOENT') {
         logger.error(`Unknown command: ${error.command}`)
       } else {
-        logger.error(error.message)
+        logger.error(redactOutput(error.message, sensitiveValues))
       }
     }
 

package/src/lib/helpers/fsx.js

@@ -1,4 +1,5 @@
 const fs = require('fs')
+const Errors = require('./errors')
 
 const ENCODING = 'utf8'
 
@@ -19,11 +20,27 @@ function readFileXSync (filepath, encoding = null) {
 }
 
 function writeFileXSync (filepath, str) {
-  return fs.writeFileSync(filepath, str, ENCODING) // utf8 always
+  try {
+    return fs.writeFileSync(filepath, str, ENCODING) // utf8 always
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw new Errors({ filepath }).fileNotWritable()
+    }
+
+    throw error
+  }
 }
 
 async function writeFileX (filepath, str) {
-  return fs.promises.writeFile(filepath, str, ENCODING)
+  try {
+    return await fs.promises.writeFile(filepath, str, ENCODING)
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw new Errors({ filepath }).fileNotWritable()
+    }
+
+    throw error
+  }
 }
 
 async function exists (filepath) {

package/src/lib/helpers/redact.js

@@ -0,0 +1,9 @@
+function redact (str) {
+  if (!str || str.length < 1) {
+    return ''
+  }
+
+  return '[REDACTED]'
+}
+
+module.exports = redact

package/src/lib/helpers/redactOutput.js

@@ -0,0 +1,120 @@
+const redact = require('./redact')
+const { StringDecoder } = require('string_decoder')
+
+function normalizedValues (values) {
+  return [...new Set((values || [])
+    .filter(value => value !== undefined && value !== null && `${value}`.length > 0)
+    .map(value => `${value}`))]
+    .sort((a, b) => b.length - a.length)
+}
+
+function redactOutput (value, sensitiveValues) {
+  const values = normalizedValues(sensitiveValues)
+  if (values.length < 1 || value === undefined || value === null) return value
+
+  if (Array.isArray(value)) {
+    return value.map(item => redactOutput(item, values))
+  }
+
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    const result = {}
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = redactOutput(item, values)
+    }
+    return result
+  }
+
+  if (typeof value !== 'string') return value
+
+  let result = value
+  for (const sensitiveValue of values) {
+    result = result.split(sensitiveValue).join(redact(sensitiveValue))
+  }
+  return result
+}
+
+function partialMatchLength (value, sensitiveValues) {
+  let longest = 0
+
+  for (const sensitiveValue of sensitiveValues) {
+    const maxLength = Math.min(value.length, sensitiveValue.length - 1)
+    for (let length = maxLength; length > longest; length--) {
+      if (sensitiveValue.startsWith(value.slice(-length))) {
+        longest = length
+        break
+      }
+    }
+  }
+
+  return longest
+}
+
+function safeBoundary (value, boundary, sensitiveValues) {
+  let result = boundary
+  let changed = true
+
+  while (changed) {
+    changed = false
+    for (const sensitiveValue of sensitiveValues) {
+      let index = value.indexOf(sensitiveValue)
+      while (index !== -1) {
+        const end = index + sensitiveValue.length
+        if (index < result && end > result) {
+          result = index
+          changed = true
+        }
+        index = value.indexOf(sensitiveValue, index + 1)
+      }
+    }
+  }
+
+  return result
+}
+
+function createRedactedStreamWriter (stream, sensitiveValues, source) {
+  const values = normalizedValues(sensitiveValues)
+  const decoder = new StringDecoder('utf8')
+  let pending = ''
+  let waitingForDrain = false
+
+  const writeToStream = (value) => {
+    if (!value) return
+
+    const canContinue = stream.write(redactOutput(value, values))
+    if (!canContinue && source && !waitingForDrain) {
+      waitingForDrain = true
+      source.pause()
+      stream.once('drain', () => {
+        waitingForDrain = false
+        source.resume()
+      })
+    }
+  }
+
+  const flush = () => {
+    pending += decoder.end()
+    if (!pending) return
+    writeToStream(pending)
+    pending = ''
+  }
+
+  const write = (chunk) => {
+    pending += Buffer.isBuffer(chunk) ? decoder.write(chunk) : `${chunk}`
+
+    const holdbackLength = partialMatchLength(pending, values)
+    let boundary = pending.length - holdbackLength
+    boundary = safeBoundary(pending, boundary, values)
+
+    const output = pending.slice(0, boundary)
+    pending = pending.slice(boundary)
+
+    writeToStream(output)
+  }
+
+  return { write, flush }
+}
+
+module.exports = {
+  redactOutput,
+  createRedactedStreamWriter
+}

package/src/lib/main.d.ts

@@ -173,7 +173,6 @@ export interface DotenvConfigOptions {
     | 'error'
     | 'warn'
     | 'success'
-    | 'successv'
     | 'info'
     | 'help'
     | 'verbose'

package/src/shared/colors.js

@@ -33,8 +33,8 @@ const colorsTrueColor = new Map([
   ['red', [140, 35, 50]] // #8C2332 brighter garnet
 ])
 
-function getColor (color) {
-  const colorDepth = depth.getColorDepth()
+function getColor (color, stream) {
+  const colorDepth = depth.getColorDepth(stream)
   if (!colors256.has(color)) {
     throw new Errors({ color }).invalidColor()
   }
@@ -53,8 +53,8 @@ function getColor (color) {
   return (message) => message
 }
 
-function bold (message) {
-  if (depth.getColorDepth() >= 4) {
+function bold (message, stream) {
+  if (depth.getColorDepth(stream) >= 4) {
     return `\x1b[1m${message}\x1b[22m`
   }
 

package/src/shared/logger.js

@@ -1,4 +1,3 @@
-const packageJson = require('../lib/helpers/packageJson')
 const Errors = require('../lib/helpers/errors')
 const { getColor, bold } = require('./colors')
 
@@ -7,7 +6,6 @@ const levels = {
   infoerror: 0,
   warn: 1,
   success: 2,
-  successv: 2,
   info: 2,
   help: 2,
   verbose: 4,
@@ -15,23 +13,26 @@ const levels = {
   silly: 6
 }
 
-const error = (m) => bold(getColor('red')(`☠ ${m}`))
-const infoerror = getColor('gray') // actually an error
-const warn = (m) => getColor('orangered')(`⚠ ${m}`)
-const success = getColor('amber')
-const successv = (m) => getColor('amber')(`⟐ ${m}`)
-const info = getColor('gray')
-const help = getColor('dodgerblue')
-const verbose = (m) => getColor('plum')(`┆ ${m}`)
-const debug = (m) => getColor('plum')(`┆ ${m}`)
+const error = (m, stream) => bold(getColor('red', stream)(`☠ ${m}`), stream)
+const infoerror = (m, stream) => getColor('gray', stream)(m) // actually an error
+const warn = (m, stream) => getColor('orangered', stream)(`⚠ ${m}`)
+const success = (m, stream) => getColor('amber', stream)(m)
+const info = (m, stream) => getColor('gray', stream)(m)
+const help = (m, stream) => getColor('dodgerblue', stream)(m)
+const verbose = (m, stream) => getColor('plum', stream)(`┆ ${m}`)
+const debug = (m, stream) => getColor('plum', stream)(`┆ ${m}`)
 
 let currentLevel = levels.info // default log level
-let currentName = 'dotenvx' // default logger name
-let currentVersion = packageJson.version // default logger version
 
 function stderr (level, message) {
-  const formattedMessage = formatMessage(level, message)
-  console.error(formattedMessage)
+  if (levels[level] === undefined) {
+    throw new Errors({ level }).missingLogLevel()
+  }
+
+  if (levels[level] <= currentLevel) {
+    const formattedMessage = formatMessage(level, message, process.stderr)
+    console.error(formattedMessage)
+  }
 }
 
 function stdout (level, message) {
@@ -40,40 +41,38 @@ function stdout (level, message) {
   }
 
   if (levels[level] <= currentLevel) {
-    const formattedMessage = formatMessage(level, message)
+    const formattedMessage = formatMessage(level, message, process.stdout)
     console.log(formattedMessage)
   }
 }
 
-function formatMessage (level, message) {
+function formatMessage (level, message, stream) {
   const formattedMessage = typeof message === 'object' ? JSON.stringify(message) : message
 
   switch (level.toLowerCase()) {
     // errors
     case 'error':
-      return error(formattedMessage)
+      return error(formattedMessage, stream)
     case 'infoerror':
-      return infoerror(formattedMessage)
+      return infoerror(formattedMessage, stream)
     // warns
     case 'warn':
-      return warn(formattedMessage)
+      return warn(formattedMessage, stream)
     // successes
     case 'success':
-      return success(formattedMessage)
-    case 'successv': // success with 'version'
-      return successv(`${formattedMessage} · ${currentName}@${currentVersion}`)
+      return success(formattedMessage, stream)
     // info
     case 'info':
-      return info(formattedMessage)
+      return info(formattedMessage, stream)
     // help
     case 'help':
-      return help(formattedMessage)
+      return help(formattedMessage, stream)
     // verbose
     case 'verbose':
-      return verbose(formattedMessage)
+      return verbose(formattedMessage, stream)
     // debug
     case 'debug':
-      return debug(formattedMessage)
+      return debug(formattedMessage, stream)
   }
 }
 
@@ -85,18 +84,17 @@ const logger = {
   error: (msg) => stderr('error', msg),
   infoerror: (msg) => stderr('infoerror', msg),
   // warns
-  warn: (msg) => stdout('warn', msg),
+  warn: (msg) => stderr('warn', msg),
   // success
-  success: (msg) => stdout('success', msg),
-  successv: (msg) => stdout('successv', msg),
+  success: (msg) => stderr('success', msg),
   // info
   info: (msg) => stdout('info', msg),
   // help
-  help: (msg) => stdout('help', msg),
+  help: (msg) => stderr('help', msg),
   // verbose
-  verbose: (msg) => stdout('verbose', msg),
+  verbose: (msg) => stderr('verbose', msg),
   // debug
-  debug: (msg) => stdout('debug', msg),
+  debug: (msg) => stderr('debug', msg),
   setLevel: (level) => {
     if (levels[level] !== undefined) {
       currentLevel = levels[level]
@@ -104,11 +102,9 @@ const logger = {
     }
   },
   setName: (name) => {
-    currentName = name
     logger.name = name
   },
   setVersion: (version) => {
-    currentVersion = version
     logger.version = version
   }
 }