@dotenvx/dotenvx 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -2,7 +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.8.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. ([#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.8.0",
+  "version": "2.10.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/cli/actions/ls.js

@@ -1,24 +1,76 @@
 const { objectTreeify: treeify } = require('@dotenvx/tooling')
+const path = require('path')
 
 const { logger } = require('./../../shared/logger')
 
 const main = require('./../../lib/main')
 const ArrayToTree = require('./../../lib/helpers/arrayToTree')
+const catchAndLog = require('../../lib/helpers/catchAndLog')
+const createSpinner = require('../../lib/helpers/createSpinner')
 
-function ls (directory) {
+async function ls (directory) {
   // debug args
   logger.debug(`directory: ${directory}`)
 
   const options = this.opts()
+  let spinnerOptions
+  if (typeof this.optsWithGlobals === 'function') {
+    spinnerOptions = this.optsWithGlobals()
+  } else {
+    spinnerOptions = options
+  }
+  const spinner = await createSpinner({ ...spinnerOptions, ...options, text: 'traversing' })
+  const startedAt = Date.now()
+  let directoryCount = 1
   logger.debug(`options: ${JSON.stringify(options)}`)
 
-  const filepaths = main.ls(directory, options.envFile, options.excludeEnvFile)
-  logger.debug(`filepaths: ${JSON.stringify(filepaths)}`)
+  try {
+    const filepaths = await main.ls(directory, options.envFile, options.excludeEnvFile, (filepath) => {
+      directoryCount += 1
 
-  const tree = new ArrayToTree(filepaths).run()
-  logger.debug(`tree: ${JSON.stringify(tree)}`)
+      if (spinner) {
+        const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1000)
+        let directoryLabel = 'directories'
+        if (directoryCount === 1) {
+          directoryLabel = 'directory'
+        }
 
-  logger.info(treeify(tree))
+        spinner.text = `traversing ${directoryCount.toLocaleString()} ${directoryLabel} (${elapsedSeconds}s) — ${filepath}`
+      }
+    })
+    logger.debug(`filepaths: ${JSON.stringify(filepaths)}`)
+
+    if (spinner) spinner.stop()
+
+    if (options.json) {
+      const cwd = path.resolve(directory || '.')
+      const absoluteFilepaths = filepaths.map(filepath => path.resolve(cwd, filepath))
+      console.log(JSON.stringify(absoluteFilepaths, null, 2))
+    } else {
+      const tree = new ArrayToTree(filepaths).run()
+      logger.debug(`tree: ${JSON.stringify(tree)}`)
+      logger.info(treeify(tree))
+    }
+
+    if (!spinnerOptions.quiet && !options.quiet) {
+      const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1000)
+      const matchedDirectoryCount = new Set(filepaths.map(filepath => path.dirname(filepath))).size
+      let fileLabel = 'files'
+      if (filepaths.length === 1) {
+        fileLabel = 'file'
+      }
+      let directoryLabel = 'directories'
+      if (matchedDirectoryCount === 1) {
+        directoryLabel = 'directory'
+      }
+
+      console.error(`▣ found ${filepaths.length.toLocaleString()} .env ${fileLabel} across ${matchedDirectoryCount.toLocaleString()} ${directoryLabel} of ${directoryCount.toLocaleString()} scanned in ${elapsedSeconds}s`)
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    catchAndLog(error)
+    process.exit(1)
+  }
 }
 
 module.exports = ls

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/commands/ext.js

@@ -24,6 +24,7 @@ ext.command('ls')
   .argument('[directory]', 'directory to list .env files from', '.')
   .option('-f, --env-file <filenames...>', 'path(s) to your env file(s)', '.env*')
   .option('-ef, --exclude-env-file <excludeFilenames...>', 'path(s) to exclude from your env file(s) (default: none)')
+  .option('--json', 'output a JSON array of absolute filepaths')
   .action(function (...args) {
     return require('./../actions/ls').apply(this, args)
   })

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) {
@@ -176,6 +177,7 @@ program.command('ls')
   .argument('[directory]', 'directory to list .env files from', '.')
   .option('-f, --env-file <filenames...>', 'path(s) to your env file(s)', '.env*')
   .option('-ef, --exclude-env-file <excludeFilenames...>', 'path(s) to exclude from your env file(s) (default: none)')
+  .option('--json', 'output a JSON array of absolute filepaths')
   .action(function (...args) {
     return require('./actions/ls').apply(this, 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
+}

package/src/lib/main.d.ts

@@ -391,9 +391,11 @@ export function get(
  * @param directory - current working directory
  * @param envFile - glob pattern to match env files
  * @param excludeEnvFile - glob pattern to exclude env files
+ * @param onDirectory - called as each directory is traversed
  */
 export function ls(
   directory: string,
   envFile: string | string[],
-  excludeEnvFile: string | string[]
-): string[];
+  excludeEnvFile: string | string[],
+  onDirectory?: (directory: string) => void
+): Promise<string[]>;

package/src/lib/main.js

@@ -389,8 +389,8 @@ const get = async function (key, options = {}) {
 }
 
 /** @type {import('./main').ls} */
-const ls = function (directory, envFile, excludeEnvFile) {
-  return lsResolver({ directory, envFile, excludeEnvFile })
+const ls = async function (directory, envFile, excludeEnvFile, onDirectory) {
+  return await lsResolver({ directory, envFile, excludeEnvFile, onDirectory })
 }
 
 function resolveNoArmor (options = {}) {

package/src/lib/resolvers/ls.js

@@ -2,6 +2,14 @@ const { Fdir } = require('@dotenvx/tooling')
 const path = require('path')
 const { match } = require('@dotenvx/primitives')
 
+const DEFAULT_EXCLUDED_DIRECTORY_EXTENSIONS = new Set([
+  '.app',
+  '.key',
+  '.numbers',
+  '.pages',
+  '.photoslibrary'
+])
+
 function patternsFor (value) {
   if (!Array.isArray(value)) {
     return [`**/${value}`]
@@ -18,24 +26,44 @@ function excludePatternsFor (value) {
   return value.map(part => `**/${part}`)
 }
 
-function ls (options = {}) {
+function crawler (options = {}) {
   const ignore = ['node_modules/**', '**/node_modules/**', '.git/**', '**/.git/**']
   const cwd = path.resolve(options.directory || './')
   const envFile = options.envFile || ['.env*']
   const excludeEnvFile = options.excludeEnvFile || []
   const excludePatterns = excludePatternsFor(excludeEnvFile)
-  const excludes = excludePatterns.length > 0 ? ignore.concat(excludePatterns) : ignore
+  let excludes
+  if (excludePatterns.length > 0) {
+    excludes = ignore.concat(excludePatterns)
+  } else {
+    excludes = ignore
+  }
   const exclude = match(excludes, { dot: true })
   const include = match(patternsFor(envFile), {
     dot: true,
     ignore: excludes
   })
+  const onDirectory = options.onDirectory || (() => {})
 
   return new Fdir()
     .withRelativePaths()
+    .exclude((dirname, directory) => {
+      if (dirname === 'node_modules' || dirname === '.git') return true
+      if (DEFAULT_EXCLUDED_DIRECTORY_EXTENSIONS.has(path.extname(dirname).toLowerCase())) return true
+
+      onDirectory(path.relative(cwd, directory) || '.')
+      return false
+    })
     .filter((filepath) => !exclude(filepath) && include(filepath))
     .crawl(cwd)
-    .sync()
+}
+
+async function ls (options = {}) {
+  return await crawler(options).withPromise()
+}
+
+ls.sync = function (options = {}) {
+  return crawler(options).sync()
 }
 
 module.exports = ls

package/src/lib/services/prebuild.js

@@ -82,7 +82,7 @@ class Prebuild {
   }
 
   _filepaths () {
-    return ls({
+    return ls.sync({
       directory: this.directory,
       excludeEnvFile: this.excludeEnvFile
     })

package/src/lib/services/precommit.js

@@ -100,7 +100,7 @@ class Precommit {
   }
 
   _filepaths () {
-    return ls({
+    return ls.sync({
       directory: this.directory,
       excludeEnvFile: this.excludeEnvFile
     })