@dotenvx/dotenvx 2.28.0 → 2.28.2

package/CHANGELOG.md

@@ -2,7 +2,20 @@
 
 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.28.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.28.2...main)
+
+## [2.28.2](https://github.com/dotenvx/dotenvx/compare/v2.28.1...v2.28.2) (2026-09-19)
+
+### Changed
+
+* Only owner can write to and read from .env.keys file ([#979](https://github.com/dotenvx/dotenvx/pull/979))
+
+## [2.28.1](https://github.com/dotenvx/dotenvx/compare/v2.28.0...v2.28.1) (2026-09-19)
+
+### Changed
+
+* Send pk via stdin to keychain. was argv. thank you @kta1kri for the security report. ([#978](https://github.com/dotenvx/dotenvx/pull/978))
+* Move some commands under a hidden menu ([#973](https://github.com/dotenvx/dotenvx/pull/973))
 
 ## [2.28.0](https://github.com/dotenvx/dotenvx/compare/v2.27.0...v2.28.0) (2026-09-16)
 

package/README.md

@@ -1599,7 +1599,7 @@ end
 
 Both `dotenvx run -f .env.production -- node index.js` and `dotenvx validate -f .env.production` use the production rules. Block declarations inherit top-level options and override only the options they specify. A block's `encrypted` directive applies to all inherited and newly declared variables; a per-variable `encrypted:` option inside that block overrides it.
 
-Paths in file blocks are relative to the Envfile. They match the selected paths exactly after path normalization (`./.env.production` matches `.env.production`); they are not basename matches or globs. Directory inputs and `DOTENV_PATH` use their resolved file paths.
+Paths in file blocks are relative to the Envfile. They match the selected paths exactly after path normalization (`./.env.production` matches `.env.production`); they are not basename matches or globs. Directory inputs and `DOTENV_FILE` use their resolved file paths.
 
 When no file block matches, top-level rules apply. When one or more blocks match, each matching block's inherited rules must hold for the final resolved environment. Shell values, fallback files, and `--overload` cannot bypass them. A selected missing file still activates its block. Multiple matching blocks cannot cancel each other's restrictions; conflicting proxy domains are rejected. Blocks cannot be nested, and duplicate declarations within one scope or duplicate file blocks are errors.
 
@@ -2790,6 +2790,26 @@ $ dotenvx ls --json
 $ dotenvx ls --json > dotenv-files.json
 ```
 
+</details>
+<details><summary>`define` (hidden)</summary><br>
+
+Create an `Envfile` to validate your project's environment variables:
+
+```sh
+$ dotenvx define
+≡ defined (Envfile)
+```
+
+Merges variable names from both `.env.example` and `.env`, skipping missing files and including each name once. Use `dotenvx define -f .env.production` to read only a specific input. If neither default file exists, it creates a starter. An existing `Envfile` is always left unchanged. The hidden `dotenvx init` command currently performs the same step.
+
+The first line is `encrypted false` by default, or `encrypted true` if any application variable assignment in either input starts with `encrypted:`. Duplicate assignments are all inspected. This sets the encryption requirement for all declarations; use `encrypted: false` on individual variables that should remain plaintext.
+
+Generated declarations are required by default. Review them and mark optional variables with `optional: true`.
+
+Only names are copied: values are never included, decrypted, expanded, or fetched from secret providers. Dotenvx public and private key entries are excluded. Your env files are unchanged.
+
+Run `dotenvx validate` (or `dotenvx validate -f .env.production` for another file) to check your configuration. Once `Envfile` exists, `dotenvx run` validates automatically before starting your command.
+
 </details>
 <details><summary>`validate`</summary><br>
 
@@ -2914,11 +2934,22 @@ $ dotenvx precommit
 </details>
 <details><summary>`precommit --install`</summary><br>
 
-Install a shell script to `.git/hooks/pre-commit` to prevent accidentally committing any `.env` files to source control.
+Install a pre-commit hook and a required Git clean filter in the current repository. The filter rejects plaintext `.env*` files before staging, including with `git add -A` or `git add -f`. Encrypted files pass through unchanged. `.env.example`, `.env.vault`, and `.env.x` retain their exemptions; `.env.keys*` files are always rejected.
+
+The filter uses repository-local Git configuration and `info/attributes`; run the installer in each clone. Keep the installed dotenvx executable available, or staging protected files will fail. It does not inspect content already staged before installation, and local Git configuration can be overridden.
+
+To enable the clean filter for all existing and future repositories for your user, run this once, even outside a Git repository:
+
+```sh
+$ dotenvx precommit --install --global
+```
+
+This writes the filter configuration to your global Git config and adds the `.env*` rule to your global attributes file. It preserves an existing `core.attributesFile`; otherwise it uses `$XDG_CONFIG_HOME/git/attributes` or `~/.config/git/attributes`. It leaves hooks unchanged. Repository attributes and configuration can override the global protection. Use a persistent dotenvx installation: moving or removing its executable requires reinstalling the filter.
 
 ```sh
 $ dotenvx precommit --install
 ▣ dotenvx precommit installed [.git/hooks/pre-commit]
+▣ dotenvx required clean filter installed (blocks staging plaintext .env files)
 ```
 
 </details>
@@ -3249,7 +3280,7 @@ inject env at runtime [dotenvx run -- yourcommand]
 
 Options:
   -e, --env <strings...>            environment variable(s) set as string (example: "HELLO=World") (default: [])
-  -f, --env-file <paths...>         path(s) to your env file(s) (default: [])
+  -f, --file <paths...>             path(s) to your env file(s) (default: [])
   -fv, --env-vault-file <paths...>  path(s) to your .env.vault file(s) (default: [])
   -o, --overload                    override existing env variables
   --convention <name>               load a .env convention (available conventions: ['nextjs'])
@@ -3747,8 +3778,9 @@ There are global settings available that can be configured as environment variab
 ```ini
 # config
 DOTENV_CONVENTION= # set to a default convention like 'nextjs' or 'flow'
-DOTENV_PATH= # path to your env file; comma-separate multiple paths
-DOTENV_F= # synonym for DOTENV_PATH
+DOTENV_FILE= # path to your env file; comma-separate multiple paths
+DOTENV_PATH= # synonym for DOTENV_FILE
+DOTENV_F= # synonym for DOTENV_FILE
 DOTENV_IGNORE= # MISSING_ENV_FILE,OTHER
 DOTENV_QUIET= # set to "true" to default to --quiet
 
@@ -3872,13 +3904,13 @@ Breaking this encryption would require brute-forcing both AES-256 and elliptic c
 
 You are using Node 20 or greater and it adds a differing implementation of `--env-file` flag support. Rather than warn on a missing `.env` file (like dotenv has historically done), it raises an error: `node: .env: not found`.
 
-This fix is easy. Replace `--env-file` with `-f`.
+This fix is easy. Replace `--env-file` with `--file` (or `-f`).
 
 ```bash
-# from this:
+# from this (legacy spelling):
 ./node_modules/.bin/dotenvx run --env-file .env -- yourcommand
 # to this:
-./node_modules/.bin/dotenvx run -f .env -- yourcommand
+./node_modules/.bin/dotenvx run --file .env -- yourcommand
 ```
 
 [more context](https://github.com/dotenvx/dotenvx/issues/131)

package/package.json

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

package/src/cli/actions/define.js

@@ -0,0 +1,17 @@
+const initEnvfile = require('../../lib/services/init')
+const { logger } = require('../../shared/logger')
+const catchAndLog = require('../../lib/helpers/catchAndLog')
+
+module.exports = function define () {
+  try {
+    const { created } = initEnvfile({ envFile: this.opts().envFile })
+    if (created) {
+      logger.success('≡ defined (Envfile)')
+    } else {
+      logger.info('○ Envfile already exists (unchanged)')
+    }
+  } catch (error) {
+    catchAndLog(error)
+    process.exitCode = 1
+  }
+}

package/src/cli/actions/encrypt.js

@@ -54,7 +54,7 @@ async function encryptAction () {
     const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await encryptTransform({ envs, ik, ek, fk, noArmor, noCreate, noNative, no1Password, noBitwarden })
 
     if (keysSrc) {
-      await fsx.writeFileX(fk, keysSrc)
+      await fsx.writeKeyFile(fk, keysSrc)
     }
 
     if (spinner) spinner.stop()

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

@@ -4,6 +4,9 @@ const Precommit = require('./../../../lib/services/precommit')
 const catchAndLog = require('./../../../lib/helpers/catchAndLog')
 
 function precommit (directory) {
+  if (this.opts().clean !== undefined) {
+    return require('./precommitClean')(this.opts().clean)
+  }
   // debug args
   logger.debug(`directory: ${directory}`)
 

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

@@ -0,0 +1,21 @@
+const fs = require('fs')
+const path = require('path')
+const { sealed } = require('@dotenvx/primitives')
+
+function precommitClean (filepath) {
+  try {
+    const content = fs.readFileSync(0)
+    const filename = path.posix.basename(filepath)
+    const exempt = ['.env.example', '.env.vault', '.env.x'].includes(filename)
+    if (filename.startsWith('.env.keys') || (!exempt && !sealed(content.toString('utf8')))) {
+      throw new Error(`refusing to stage ${JSON.stringify(filepath)}: encrypt this env file or add it to .gitignore`)
+    }
+    // stdout is Git's blob content: no logging, normalization, or extra newline.
+    process.stdout.write(content)
+  } catch (error) {
+    process.stderr.write(`dotenvx: ${error.message}\n`)
+    process.exitCode = 1
+  }
+}
+
+module.exports = precommitClean

package/src/cli/actions/get.js

@@ -18,7 +18,7 @@ async function get (key) {
   const spinnerOptions = typeof this.optsWithGlobals === 'function' ? this.optsWithGlobals() : options
   const spinner = await createSpinner({ ...spinnerOptions, ...options, text: 'decrypting' })
 
-  logger.debug(`options: ${JSON.stringify(options)}`)
+  logger.debug(`options: ${JSON.stringify({ ...options, ...(options.lockPassword !== undefined ? { lockPassword: '[REDACTED]' } : {}) })}`)
   if (key) {
     logger.debug(`key: ${key}`)
   }
@@ -41,6 +41,7 @@ async function get (key) {
       envKeysFile: resolveEnvKeysFile(options.envKeysFile),
       noArmor,
       noNative,
+      lockPassword: options.lockPassword,
       no1Password: options['1password'] === false || options.no1Password === true,
       noBitwarden: options.bitwarden === false || options.noBitwarden === true,
       onStatus: (text) => {

package/src/cli/actions/init.js

@@ -0,0 +1,3 @@
+module.exports = function init () {
+  return require('./define').apply(this, arguments)
+}

package/src/cli/actions/lock/down.js

@@ -1,32 +1,10 @@
-const crypto = require('crypto')
+const unlockedValue = require('../../../lib/helpers/unlockedValue')
 
 const { logger } = require('../../../shared/logger')
 const LockDown = require('./../../../lib/services/lockDown')
 const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
 const prompts = require('../../../lib/helpers/prompts')
-
-function unlockedValue (lockedPrivateKey, passphrase) {
-  const parts = lockedPrivateKey.split(':')
-  const payload = Buffer.from(parts.slice(2).join(':'), 'base64url')
-  const version = payload.subarray(0, 1)[0]
-  const salt = payload.subarray(1, 17)
-  const iv = payload.subarray(17, 29)
-  const tag = payload.subarray(29, 45)
-  const ciphertext = payload.subarray(45)
-  const key = crypto.scryptSync(passphrase, salt, 32)
-  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv)
-
-  if (version !== 1) {
-    throw new Error('unsupported locked private key version')
-  }
-
-  decipher.setAuthTag(tag)
-
-  return Buffer.concat([
-    decipher.update(ciphertext),
-    decipher.final()
-  ]).toString('utf8')
-}
+const resolveLockPassword = require('../../../lib/helpers/resolveLockPassword')
 
 async function down () {
   const options = this.opts()
@@ -38,14 +16,17 @@ async function down () {
     let results = plan.alreadyUnlocked
 
     if (plan.locked.length > 0) {
-      const passphrase = await prompts.password({
-        message: 'passphrase',
-        prefix: '⊡',
-        separator: '='
-      }, {
-        input: process.stdin,
-        output: process.stderr
-      })
+      const preset = resolveLockPassword(options)
+      const passphrase = preset !== undefined
+        ? preset
+        : await prompts.password({
+          message: 'passphrase',
+          prefix: '⊡',
+          separator: '='
+        }, {
+          input: process.stdin,
+          output: process.stderr
+        })
 
       results = lockDown.run(lockedPrivateKey => unlockedValue(lockedPrivateKey, passphrase)).results
     }

package/src/cli/actions/lock/up.js

@@ -1,30 +1,10 @@
-const crypto = require('crypto')
+const lockedValue = require('../../../lib/helpers/lockedValue')
 
 const { logger } = require('../../../shared/logger')
 const LockUp = require('./../../../lib/services/lockUp')
 const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
 const prompts = require('../../../lib/helpers/prompts')
-
-function lockedValue (privateKey, passphrase, publicKey) {
-  const salt = crypto.randomBytes(16)
-  const iv = crypto.randomBytes(12)
-  const key = crypto.scryptSync(passphrase, salt, 32)
-  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv)
-  const ciphertext = Buffer.concat([
-    cipher.update(privateKey, 'utf8'),
-    cipher.final()
-  ])
-  const tag = cipher.getAuthTag()
-  const payload = Buffer.concat([
-    Buffer.from([1]),
-    salt,
-    iv,
-    tag,
-    ciphertext
-  ]).toString('base64url')
-
-  return `locked:${publicKey}:${payload}`
-}
+const resolveLockPassword = require('../../../lib/helpers/resolveLockPassword')
 
 async function up () {
   const options = this.opts()
@@ -44,14 +24,17 @@ async function up () {
     }))
 
     if (plan.matches.length > 0) {
-      const passphrase = await prompts.password({
-        message: 'passphrase',
-        prefix: '⊡',
-        separator: '='
-      }, {
-        input: process.stdin,
-        output: process.stderr
-      })
+      const preset = resolveLockPassword(options)
+      const passphrase = preset !== undefined
+        ? preset
+        : await prompts.password({
+          message: 'passphrase',
+          prefix: '⊡',
+          separator: '='
+        }, {
+          input: process.stdin,
+          output: process.stderr
+        })
 
       results = lockUp.run((privateKey, publicKey) => lockedValue(privateKey, passphrase, publicKey)).results
     }

package/src/cli/actions/run.js

@@ -25,7 +25,7 @@ function inferCommandArgsFromProcessArgv (argv) {
   if (separatorIndex !== -1) return args.slice(separatorIndex + 1)
 
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '-f' || args[i] === '--env-file') {
+    if (args[i] === '-f' || args[i] === '--file' || args[i] === '--env-file') {
       i++
       continue
     }
@@ -77,6 +77,7 @@ async function run () {
 
     debugOptions = { ...options, env: (options.env || []).map(envSrc => maskEnvSrc(envSrc, showChar)), token }
   }
+  if (options.lockPassword !== undefined) debugOptions = { ...debugOptions, lockPassword: '[REDACTED]' }
   logger.debug(`options: ${JSON.stringify(debugOptions)}`)
   logger.debug(`process command [${commandArgs.join(' ')}]`)
 

package/src/cli/actions/set.js

@@ -70,7 +70,7 @@ async function set (key, value) {
     const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await setTransform({ envs, key, value, fk, noArmor, noCreate, encrypt, noNative, no1Password, noBitwarden })
 
     if (keysSrc) {
-      await fsx.writeFileX(fk, keysSrc)
+      await fsx.writeKeyFile(fk, keysSrc)
     }
 
     let withEncryption = ''

package/src/cli/commands/custody.js

@@ -1,4 +1,4 @@
-function configureCustodyCommand (command, name, providerPath) {
+function configureCustodyCommand (command, name, custodianId) {
   command.hook('preAction', async () => {
     const Session = require('../../db/session')
     await new Session().notifyUpdate()
@@ -23,7 +23,7 @@ function configureCustodyCommand (command, name, providerPath) {
         const options = this.opts()
         const spinner = await createSpinner({ ...this.optsWithGlobals(), text: `${operation === 'up' || operation === 'push' ? 'storing in' : 'reading from'} ${name}` })
         try {
-          const result = await transfer(require(providerPath), name, operation, options.envFile, options.envKeysFile)
+          const result = await transfer(require('../../lib/custodians').get(custodianId), name, operation, options.envFile, options.envKeysFile)
           if (spinner) spinner.stop()
           const display = armoredKeyDisplay(result.publicKeyValue) || result.privateKeyName
           const messages = { up: `stored in ${name}`, down: `moved to ${options.envKeysFile}`, push: `pushed to ${name}`, pull: `pulled to ${options.envKeysFile}` }

package/src/cli/commands/ext.js

@@ -61,7 +61,9 @@ ext.command('precommit')
   .description('prevent committing .env files to code')
   .addHelpText('after', help.precommit)
   .argument('[directory]', 'directory to prevent committing .env files from', '.')
-  .option('-i, --install', 'install to .git/hooks/pre-commit')
+  .option('-i, --install', 'install a pre-commit hook and required Git clean filter')
+  .option('--global', 'with --install, install the clean filter for all repositories')
+  .addOption(ext.createOption('--clean <path>', 'validate Git filter input from stdin').hideHelp())
   .action(function (...args) {
     return require('./../actions/ext/precommit').apply(this, args)
   })

package/src/cli/commands/fileOptions.js

@@ -0,0 +1,22 @@
+// Keep the existing envFile option attribute and parsing behavior for both
+// spellings, including mixed repeated flags. Only --file is advertised.
+function configureFileOptions (command) {
+  const legacy = command.options.find(option => option.long === '--env-file')
+  if (legacy && !command.options.some(option => option.long === '--file')) {
+    const index = command.options.indexOf(legacy)
+    const visible = command.createOption(legacy.flags.replace('--env-file', '--file'), legacy.description)
+    visible.attributeName = () => legacy.attributeName()
+    if (legacy.parseArg) visible.argParser(legacy.parseArg)
+    if (legacy.defaultValue !== undefined) visible.default(legacy.defaultValue, legacy.defaultValueDescription)
+    legacy.short = undefined
+    legacy.flags = legacy.flags.replace(/^-f,?\s*/, '')
+    legacy.hideHelp()
+    command.addOption(visible)
+    command.options.pop()
+    command.options.splice(index, 0, visible)
+  }
+  for (const child of command.commands) configureFileOptions(child)
+  return command
+}
+
+module.exports = configureFileOptions

package/src/cli/dotenvx.js

@@ -78,6 +78,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('--lock-password <password>', 'password to unlock private keys (defaults to DOTENVX_LOCK_PASSWORD)')
   .option('--no-armor', 'disable Dotenvx Armor features')
   .option('--no-native', 'disable OS secret store features')
   .option('--no-1password', 'disable 1Password secret reference resolution')
@@ -106,6 +107,7 @@ program.command('get')
   .option('-pp, --pretty-print', 'pretty print output')
   .option('--pp', 'pretty print output (alias)')
   .option('--format <type>', 'format of the output (json, shell, colon, eval, eval-export)', 'json')
+  .option('--lock-password <password>', 'password to unlock private keys (defaults to DOTENVX_LOCK_PASSWORD)')
   .option('--no-armor', 'disable Dotenvx Armor features')
   .option('--no-native', 'disable OS secret store features')
   .option('--no-1password', 'disable 1Password secret reference resolution')
@@ -211,7 +213,7 @@ program.command('keypair')
   })
 
 // dotenvx ls
-program.command('ls')
+program.command('ls', { hidden: true })
   .description('print all .env files in a tree structure')
   .argument('[directory]', 'directory to list .env files from', '.')
   .option('-f, --env-file <filenames...>', 'path(s) to your env file(s)', '.env*')
@@ -221,8 +223,24 @@ program.command('ls')
     return require('./actions/ls').apply(this, args)
   })
 
+// dotenvx init
+program.command('init', { hidden: true })
+  .description('create an Envfile from .env.example and .env')
+  .option('-f, --env-file <path>', 'file to read variable names from')
+  .action(function () {
+    return require('./actions/init').apply(this, arguments)
+  })
+
+// dotenvx define
+program.command('define', { hidden: true })
+  .description('define your environment in an Envfile')
+  .option('-f, --env-file <path>', 'file to read variable names from')
+  .action(function () {
+    return require('./actions/define').apply(this, arguments)
+  })
+
 // dotenvx validate
-program.command('validate')
+program.command('validate', { hidden: true })
   .description('validate .env file(s) against Envfile')
   .option('--strict', 'process.exit(1) on any errors, including missing env files', false)
   .option('-e, --env <strings...>', 'environment variable(s) set as string (example: "HELLO=World")', collectEnvs('env'), [])
@@ -242,7 +260,7 @@ program.command('validate')
   })
 
 // dotenvx gitignore
-program.command('gitignore')
+program.command('gitignore', { hidden: true })
   .description('append to .gitignore')
   .addHelpText('after', help.gitignore)
   .option('--pattern <patterns...>', 'pattern(s) to gitignore', ['.env*'])
@@ -251,7 +269,7 @@ program.command('gitignore')
   })
 
 // dotenvx genexample
-program.command('genexample')
+program.command('genexample', { hidden: true })
   .description('generate .env.example')
   .argument('[directory]', 'directory to generate from', '.')
   .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', '.env')
@@ -260,17 +278,19 @@ program.command('genexample')
   })
 
 // dotenvx precommit
-program.command('precommit')
+program.command('precommit', { hidden: true })
   .description('prevent committing .env files to code')
   .addHelpText('after', help.precommit)
   .argument('[directory]', 'directory to prevent committing .env files from', '.')
-  .option('-i, --install', 'install to .git/hooks/pre-commit')
+  .option('-i, --install', 'install a pre-commit hook and required Git clean filter')
+  .option('--global', 'with --install, install the clean filter for all repositories')
+  .addOption(program.createOption('--clean <path>', 'validate Git filter input from stdin').hideHelp())
   .action(function (...args) {
     return require('./actions/ext/precommit').apply(this, args)
   })
 
 // dotenvx prebuild
-program.command('prebuild')
+program.command('prebuild', { hidden: true })
   .description('prevent including .env files in docker')
   .addHelpText('after', help.prebuild)
   .argument('[directory]', 'directory to prevent including .env files from', '.')
@@ -286,6 +306,13 @@ program.command('doctor', { hidden: true })
     return require('./actions/doctor').apply(this, args)
   })
 
+// dotenvx hidden (a menu of top-level commands)
+program.command('hidden')
+  .allowExcessArguments(false)
+  .description('hidden features')
+  .addHelpText('after', '\nHidden Commands:\n  init                   create an Envfile from .env.example and .env\n  define                 define your environment in an Envfile\n  validate               validate .env file(s) against Envfile\n  genexample [directory] generate .env.example\n  gitignore              append to .gitignore\n  ls [directory]         print all .env files in a tree structure\n  prebuild [directory]   prevent including .env files in docker\n  precommit [directory]  prevent committing .env files to code\n  lock                   ⊡ lock private keys with a local passphrase\n  native                 ⌥ move private keys in/out of your OS secret store\n  1password              □ move private keys in/out of 1Password\n  bitwarden              □ move private keys in/out of Bitwarden\n  armor                  ⛨ move private keys in/out of Dotenvx Armor [www.dotenvx.com/armor]\n  curl                   ⛨ call authenticated api Dotenvx Armor [www.dotenvx.com/armor]\n\nRun directly: dotenvx <command>')
+  .action(function () { this.outputHelp() })
+
 // dotenvx update
 program.command('update')
   .description('update dotenvx')
@@ -344,20 +371,8 @@ program.command('help [command]')
     }
   })
 
-// security sections (hidden commands advertised here)
-program.addHelpText('after', ' ')
-program.addHelpText('after', 'Local Custody:')
-program.addHelpText('after', '  lock                     ⊡ lock private keys with a local passphrase')
-program.addHelpText('after', '  native                   ⌥ move private keys in/out of your OS secret store')
-program.addHelpText('after', '  1password                □ move private keys in/out of 1Password')
-program.addHelpText('after', '  bitwarden                □ move private keys in/out of Bitwarden')
-program.addHelpText('after', ' ')
-program.addHelpText('after', 'Managed Custody:')
-program.addHelpText('after', '  armor                    ⛨ move private keys in/out of Dotenvx Armor [www.dotenvx.com/armor]')
-program.addHelpText('after', '  curl                     ⛨ call authenticated api Dotenvx Armor [www.dotenvx.com/armor]')
-
-require('./commands/custody')(program.command('1password', { hidden: true }), '1Password', '../../lib/helpers/onePasswordCustody')
-require('./commands/custody')(program.command('bitwarden', { hidden: true }), 'Bitwarden', '../../lib/helpers/bitwardenCustody')
+require('./commands/custody')(program.command('1password', { hidden: true }), '1Password', 'onepassword')
+require('./commands/custody')(program.command('bitwarden', { hidden: true }), 'Bitwarden', 'bitwarden')
 
 // dotenvx native
 require('./commands/native')(program.command('native', { hidden: true }))
@@ -390,4 +405,6 @@ program.helpInformation = function () {
 }
 /* c8 ignore stop */
 
+require('./commands/fileOptions')(program)
+
 program.parse(process.argv)

package/src/lib/custodians/index.js

@@ -0,0 +1,73 @@
+const protection = require('./lock')
+
+// Explicit registration keeps bundling predictable and avoids executing
+// arbitrary modules discovered in a project's working directory.
+const builtins = [
+  require('./local/native'),
+  require('./local/onepassword'),
+  require('./local/bitwarden'),
+  require('./local/file'),
+  require('./managed/armor')
+]
+
+function createRegistry (custodians) {
+  const entries = new Map()
+  for (const custodian of custodians) {
+    if (!custodian || typeof custodian.id !== 'string' || !custodian.id || entries.has(custodian.id)) {
+      throw new Error('custodians must have unique, nonempty ids')
+    }
+    for (const method of ['enabled', 'available', 'store']) {
+      if (typeof custodian[method] !== 'function') throw new Error(`custodian ${custodian.id} requires ${method}()`)
+    }
+    entries.set(custodian.id, custodian)
+  }
+
+  function get (id) {
+    const custodian = entries.get(id)
+    if (!custodian) throw new Error(`unknown custodian: ${id}`)
+    return custodian
+  }
+
+  return {
+    get,
+    async choices (options = {}, custody = 'local') {
+      const choices = []
+      for (const custodian of entries.values()) {
+        if ((custodian.custody || 'local') !== custody) continue
+        choices.push({ name: custodian.name, value: custodian.id, disabled: !custodian.enabled(options) || !await custodian.available() })
+      }
+      return choices
+    },
+    providers (options = {}, sync = false) {
+      const providers = []
+      for (const custodian of entries.values()) {
+        if (custodian.custody === 'managed') continue
+        const method = sync ? 'getSync' : 'get'
+        if (!custodian.enabled(options) || !custodian.get || (custodian.configured && !custodian.configured())) continue
+        if (typeof custodian[method] !== 'function') throw new Error(`custodian ${custodian.id} does not support synchronous reads`)
+        if (sync) {
+          providers.push(publicKey => protection.unlockSync(publicKey, custodian[method](publicKey), options))
+        } else {
+          providers.push(async publicKey => protection.unlock(publicKey, await custodian[method](publicKey), options))
+        }
+      }
+      return providers
+    },
+    async store (selection, publicKey, privateKey, context = {}) {
+      const { id, lock = false } = typeof selection === 'string' ? { id: selection } : selection
+      const custodian = get(id)
+      if (lock) {
+        if (custodian.custody === 'managed') throw new Error('password locking is only supported for local custody')
+        privateKey = await protection.lock(publicKey, privateKey, context)
+      }
+      const result = await custodian.store(publicKey, privateKey, context) || {}
+      // Only the native custodian's unavailable-write path requests fallback.
+      // Authentication and verification errors propagate without writing a file.
+      if (result.fallback) return get(result.fallback).store(publicKey, privateKey, context)
+      return result
+    }
+  }
+}
+
+module.exports = createRegistry(builtins)
+module.exports.createRegistry = createRegistry