@dotenvx/dotenvx 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -2,19 +2,25 @@
 
 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.6.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.7.0...main)
+
+## [2.7.0](https://github.com/dotenvx/dotenvx/compare/v2.6.0...v2.7.0) (2026-07-13)
+
+### Added
+
+* Added support for `--mask` on `get, run, decrypt` ([#885](https://github.com/dotenvx/dotenvx/pull/885))
 
 ## [2.6.0](https://github.com/dotenvx/dotenvx/compare/v2.5.0...v2.6.0) (2026-07-11)
 
 ### Added
 
-* Support `native up|down|pull|push` for windows ([#834](https://github.com/dotenvx/dotenvx/pull/884))
+* Support `native up|down|pull|push` for windows ([#884](https://github.com/dotenvx/dotenvx/pull/884))
 
 ## [2.5.0](https://github.com/dotenvx/dotenvx/compare/v2.4.2...v2.5.0) (2026-07-11)
 
 ### Added
 
-* Support `native up|down|pull|push` for windows ([#833](https://github.com/dotenvx/dotenvx/pull/883))
+* Support `native up|down|pull|push` for windows ([#883](https://github.com/dotenvx/dotenvx/pull/883))
 
 ## [2.4.1](https://github.com/dotenvx/dotenvx/compare/v2.4.0...v2.4.1) (2026-07-10)
 

package/README.md

@@ -1471,6 +1471,21 @@ $ 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 --mask`</summary><br>
+
+Inject masked values into the command. By default, up to the first six characters are visible.
+
+```sh
+$ echo "SECRET=abcdefghijkl" > .env
+$ echo "console.log(process.env.SECRET)" > index.js
+
+$ dotenvx run --mask --quiet -- node index.js
+abcdef******
+```
+
+Pass a number to control how many characters are visible, such as `--mask 0` to fully mask values.
+
 </details>
 <details><summary>`run --token`</summary><br>
 
@@ -1510,6 +1525,20 @@ $ dotenvx get HELLO
 World
 ```
 
+</details>
+<details><summary>`get KEY --mask`</summary><br>
+
+Return a masked environment variable value. By default, up to the first six characters are visible.
+
+```sh
+$ echo "SECRET=abcdefghijkl" > .env
+
+$ dotenvx get SECRET --mask
+abcdef******
+```
+
+Pass a number to control how many characters are visible, such as `--mask 0` to fully mask values.
+
 </details>
 <details><summary>`get KEY --no-native`</summary><br>
 
@@ -2141,6 +2170,23 @@ or send to a file:
 $ dotenvx decrypt --stdout > somefile.txt
 ```
 
+</details>
+<details><summary>`decrypt --stdout --mask`</summary><br>
+
+Decrypt the contents of an encrypted `.env` file to stdout with its values masked. The encrypted `.env` file remains unchanged.
+
+```sh
+$ echo "SECRET=abcdefghijkl" > .env
+$ dotenvx encrypt
+◈ encrypted (.env)
+
+$ dotenvx decrypt --stdout --mask
+...
+SECRET="abcdef******"
+```
+
+Pass a number to control how many characters are visible, such as `--mask 0` to fully mask values.
+
 </details>
 <details><summary>`keypair`</summary><br>
 
@@ -2725,6 +2771,33 @@ Hello Dotenvx
 
 It defaults to looking for a `.env` file.
 
+</details>
+<details><summary>`config(mask: true)` - mask</summary><br>
+
+Inject and return masked values. By default, up to the first six characters are visible.
+
+```ini
+# .env
+SECRET="abcdefghijkl"
+```
+
+```js
+// index.js
+const dotenvx = require('@dotenvx/dotenvx')
+const result = dotenvx.config({ mask: true, quiet: true })
+
+console.log(process.env.SECRET)
+console.log(result.parsed.SECRET)
+```
+
+```sh
+$ node index.js
+abcdef******
+abcdef******
+```
+
+Set `mask: 0` to fully mask values.
+
 </details>
 <details><summary>`config(path: ['.env.local', '.env'])` - multiple files</summary><br>
 
@@ -3051,6 +3124,25 @@ console.log(decryptedValue)
 
 This is known as *Decryption at Access* and is written about in [the whitepaper](https://dotenvx.com/dotenvx.pdf).
 
+</details>
+<details><summary>`get(KEY, {mask:})`</summary><br>
+
+Programmatically return a masked environment variable value.
+
+```js
+// index.js
+const dotenvx = require('@dotenvx/dotenvx')
+const maskedValue = await dotenvx.get('SECRET', { mask: true })
+console.log(maskedValue)
+```
+
+```sh
+$ node index.js
+abcdef******
+```
+
+Set `mask: 0` to fully mask values.
+
 </details>
 
 &nbsp;

package/package.json

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

package/src/cli/actions/decrypt.js

@@ -6,6 +6,7 @@ const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
 
 const decryptTransform = require('./../../lib/transforms/decrypt')
+const maskEnvSrc = require('../../lib/helpers/maskEnvSrc')
 
 async function decrypt () {
   const options = this.opts()
@@ -44,7 +45,16 @@ async function decrypt () {
         errorCount += 1
         logger.error(processedEnv.error.messageWithHelp || processedEnv.error.message)
       } else {
-        console.log(processedEnv.envSrc)
+        let showChar = options.mask
+        if (options.mask === true) {
+          showChar = 6
+        }
+
+        let envSrc = processedEnv.envSrc
+        if (options.mask !== undefined) {
+          envSrc = maskEnvSrc(processedEnv.envSrc, showChar)
+        }
+        console.log(envSrc)
       }
     }
 

package/src/cli/actions/get.js

@@ -8,6 +8,7 @@ const getResolver = require('./../../lib/resolvers/get')
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
 const buildCommandEnvs = require('../../lib/helpers/buildCommandEnvs')
 const resolveEnvKeysFile = require('../../lib/helpers/resolveEnvKeysFile')
+const mask = require('../../lib/helpers/mask')
 
 async function get (key) {
   const options = normalizeDotenvConfigConvention(this.opts())
@@ -55,6 +56,17 @@ async function get (key) {
     }
 
     if (spinner) spinner.stop()
+    if (options.mask !== undefined) {
+      let showChar = options.mask
+      if (options.mask === true) {
+        showChar = 6
+      }
+
+      for (const key of Object.keys(parsed)) {
+        parsed[key] = mask(parsed[key], showChar)
+      }
+    }
+
     if (key) {
       const single = parsed[key]
       if (single === undefined) {

package/src/cli/actions/run.js

@@ -10,6 +10,9 @@ const normalizeDotenvConfigQuiet = require('../../lib/helpers/normalizeDotenvCon
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
 const buildCommandEnvs = require('../../lib/helpers/buildCommandEnvs')
 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 { determine } = require('./../../lib/helpers/envResolution')
 
@@ -48,6 +51,12 @@ function uniqueInjectedKeys (processedEnvs) {
 
 async function run () {
   const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts()))
+  const maskEnabled = options.mask !== undefined
+  let showChar = options.mask
+  if (options.mask === true) {
+    showChar = 6
+  }
+  let commandEnv = process.env
 
   let commandArgs = this.args
   if (commandArgs.length < 1) {
@@ -56,7 +65,16 @@ async function run () {
 
   const spinner = await createSpinner({ ...options, text: 'injecting' })
 
-  logger.debug(`options: ${JSON.stringify(options)}`)
+  let debugOptions = options
+  if (maskEnabled) {
+    let token = options.token
+    if (options.token) {
+      token = mask(options.token, showChar)
+    }
+
+    debugOptions = { ...options, env: (options.env || []).map(envSrc => maskEnvSrc(envSrc, showChar)), token }
+  }
+  logger.debug(`options: ${JSON.stringify(debugOptions)}`)
   logger.debug(`process command [${commandArgs.join(' ')}]`)
 
   const ignore = options.ignore || []
@@ -103,13 +121,22 @@ async function run () {
       }
     })
 
+    if (maskEnabled) {
+      commandEnv = { ...process.env }
+      maskProcessedEnvs(processedEnvs, commandEnv, showChar)
+    }
+
     for (const processedEnv of processedEnvs) {
       if (processedEnv.type === 'envFile') {
         logger.verbose(`loading env from ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
       }
 
       if (processedEnv.type === 'env') {
-        logger.verbose(`loading env from string (${processedEnv.string})`)
+        let envString = processedEnv.string
+        if (maskEnabled) {
+          envString = maskEnvSrc(processedEnv.string, showChar)
+        }
+        logger.verbose(`loading env from string (${envString})`)
       }
 
       for (const error of processedEnv.errors || []) {
@@ -161,7 +188,7 @@ async function run () {
     process.exit(1)
   }
 
-  await executeCommand(commandArgs, process.env)
+  await executeCommand(commandArgs, commandEnv)
 }
 
 module.exports = run

package/src/cli/dotenvx.js

@@ -69,6 +69,7 @@ program.command('run')
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
   .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('--no-armor', 'disable Dotenvx Armor features')
   .option('--no-native', 'disable OS secret store features')
   .action(function (...args) {
@@ -89,6 +90,7 @@ program.command('get')
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
   .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
   .option('-a, --all', 'include all machine envs as well')
+  .option('--mask [characters]', 'mask values, optionally setting visible characters')
   .option('-pp, --pretty-print', 'pretty print output')
   .option('--pp', 'pretty print output (alias)')
   .option('--format <type>', 'format of the output (json, shell, colon, eval)', 'json')
@@ -146,6 +148,7 @@ program.command('decrypt')
   .option('--no-armor', 'disable Dotenvx Armor features')
   .option('--no-native', 'disable OS secret store features')
   .option('--stdout', 'send to stdout')
+  .option('--mask [characters]', 'mask stdout values, optionally setting visible characters')
   .action(function (...args) {
     this.envs = envs
     return require('./actions/decrypt').apply(this, args)

package/src/lib/helpers/mask.js

@@ -0,0 +1,22 @@
+function mask (str, showChar = 6) {
+  if (!str || str.length < 1) {
+    return ''
+  }
+
+  const number = Number(showChar)
+  showChar = 0
+  if (Number.isFinite(number)) {
+    showChar = Math.abs(Math.trunc(number))
+  }
+
+  let visibleChars = Math.min(showChar, Math.ceil(str.length / 2))
+  if (str.length === 1) {
+    visibleChars = 0
+  }
+  const visiblePart = str.slice(0, visibleChars)
+  const maskedPart = '*'.repeat(str.length - visibleChars)
+
+  return visiblePart + maskedPart
+}
+
+module.exports = mask

package/src/lib/helpers/maskEnvSrc.js

@@ -0,0 +1,15 @@
+const { scan, upsert } = require('@dotenvx/primitives')
+
+const mask = require('./mask')
+
+function maskEnvSrc (envSrc, showChar) {
+  const { parsed } = scan(envSrc)
+
+  for (const [key, values] of Object.entries(parsed)) {
+    envSrc = upsert(envSrc, key, values.map(value => mask(value, showChar)))
+  }
+
+  return envSrc
+}
+
+module.exports = maskEnvSrc

package/src/lib/helpers/maskProcessedEnvs.js

@@ -0,0 +1,29 @@
+const mask = require('./mask')
+
+function maskProcessedEnvs (processedEnvs, processEnv, showChar) {
+  // Track every key resolved from the requested env sources so the same keys
+  // can also be masked in the environment receiving the resolved values.
+  const resolvedKeys = new Set()
+
+  for (const processedEnv of processedEnvs) {
+    for (const key of Object.keys(processedEnv.parsed || {})) {
+      resolvedKeys.add(key)
+    }
+
+    // These values may be logged, so mask each resolver reporting bucket.
+    for (const values of [processedEnv.parsed, processedEnv.injected, processedEnv.existed]) {
+      for (const key of Object.keys(values || {})) {
+        values[key] = mask(values[key], showChar)
+      }
+    }
+  }
+
+  // Leave unrelated inherited environment variables unchanged.
+  for (const key of resolvedKeys) {
+    if (processEnv[key] !== undefined) {
+      processEnv[key] = mask(processEnv[key], showChar)
+    }
+  }
+}
+
+module.exports = maskProcessedEnvs

package/src/lib/main.d.ts

@@ -114,6 +114,14 @@ export interface DotenvConfigOptions {
    */
   processEnv?: DotenvPopulateInput;
 
+  /**
+   * Mask resolved values, optionally setting the number of visible characters.
+   * @default false
+   * @example require('@dotenvx/dotenvx').config({ mask: true })
+   * @example require('@dotenvx/dotenvx').config({ mask: 0 })
+   */
+  mask?: boolean | number;
+
   /**
    * Customize the path to your .env.keys file. This is useful with monorepos.
    * @default []
@@ -309,6 +317,14 @@ export function set(
 ): Promise<SetOutput>;
 
 export interface GetOptions {
+  /**
+   * Mask returned values, optionally setting the number of visible characters.
+   * @default false
+   * @example require('@dotenvx/dotenvx').get('KEY', { mask: true })
+   * @example require('@dotenvx/dotenvx').get('KEY', { mask: 0 })
+   */
+  mask?: boolean | number;
+
   /**
    * Suppress specific errors like MISSING_ENV_FILE. The error keys can be found
    * in src/lib/helpers/errors.js

package/src/lib/main.js

@@ -25,6 +25,8 @@ const decryptKeyValue = require('./helpers/cryptography/decryptKeyValue')
 const Errors = require('./helpers/errors')
 const normalizeDotenvConfigQuiet = require('./helpers/normalizeDotenvConfigQuiet')
 const normalizeDotenvConfigConvention = require('./helpers/normalizeDotenvConfigConvention')
+const mask = require('./helpers/mask')
+const maskProcessedEnvs = require('./helpers/maskProcessedEnvs')
 
 function uniqueInjectedKeys (processedEnvs) {
   const result = new Set()
@@ -88,6 +90,11 @@ const config = function (options = {}) {
       token: options.token
     })
 
+    if (options.mask !== undefined) {
+      const showChar = options.mask === true ? 6 : options.mask
+      maskProcessedEnvs(processedEnvs, processEnv, showChar)
+    }
+
     let lastError
     /** @type {Record<string, string>} */
     const parsedAll = {}
@@ -326,6 +333,13 @@ const get = async function (key, options = {}) {
     noKeychain
   })
 
+  if (options.mask !== undefined) {
+    const showChar = options.mask === true ? 6 : options.mask
+    for (const key of Object.keys(parsed)) {
+      parsed[key] = mask(parsed[key], showChar)
+    }
+  }
+
   for (const error of errors || []) {
     if (ignore.includes(error.code)) {
       continue // ignore error