@dotenvx/dotenvx 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -2,13 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.9.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.10.0...main)
+
+## [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.10.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/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) {

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/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
+}