@dotenvx/dotenvx 2.1.5 → 2.2.1

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.1.5...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.2.1...main)
+
+## [2.2.1](https://github.com/dotenvx/dotenvx/compare/v2.2.0...v2.2.1) (2026-07-08)
+
+### Changed
+
+* Move `genexample` to top level commands ([#873](https://github.com/dotenvx/dotenvx/pull/873))
+
+## [2.2.0](https://github.com/dotenvx/dotenvx/compare/v2.1.5...v2.2.0) (2026-07-07)
+
+### Added
+
+* Use `dotenvx keychain up|down` to move your private keys to your macOS Keychain ([#872](https://github.com/dotenvx/dotenvx/pull/872))
 
 ## [2.1.5](https://github.com/dotenvx/dotenvx/compare/v2.1.4...v2.1.5) (2026-07-06)
 

package/README.md

@@ -1384,6 +1384,15 @@ Set Armor ⛨ token for retrieving armored private keys.
 $ dotenvx run --token "$DOTENVX_ARMOR_TOKEN" -- yourcommand
 ```
 
+</details>
+<details><summary>`run --no-keychain`</summary><br>
+
+Turn off macOS Keychain lookups.
+
+```sh
+$ dotenvx run --no-keychain -- yourcommand
+```
+
 </details>
 <details><summary>`run --no-armor`</summary><br>
 
@@ -1393,8 +1402,6 @@ Turn off [Dotenvx Armor ⛨](https://dotenvx.com/armor) features.
 $ dotenvx run --no-armor -- yourcommand
 ```
 
-`--no-vlt` and `--no-ops` are deprecated aliases.
-
 </details>
 <details><summary>`get KEY`</summary><br>
 
@@ -1407,6 +1414,15 @@ $ dotenvx get HELLO
 World
 ```
 
+</details>
+<details><summary>`get KEY --no-keychain`</summary><br>
+
+Turn off macOS Keychain lookups for get.
+
+```sh
+$ dotenvx get HELLO --no-keychain
+```
+
 </details>
 <details><summary>`get KEY -f`</summary><br>
 
@@ -1722,6 +1738,15 @@ set HELLO_PLAIN (.env)
 
 Keys ending in `_PLAIN` are not encrypted by `dotenvx set` or `dotenvx encrypt`.
 
+</details>
+<details><summary>`set KEY value --no-keychain`</summary><br>
+
+Turn off macOS Keychain lookups for set.
+
+```sh
+$ dotenvx set HELLO Dotenvx --no-keychain
+```
+
 </details>
 <details><summary>`encrypt`</summary><br>
 
@@ -1753,6 +1778,16 @@ $ dotenvx encrypt -f .env.production
 ⮕  next run [DOTENV_PRIVATE_KEY='bff...bc4' dotenvx run -- yourcommand] to test decryption locally
 ```
 
+</details>
+<details><summary>`encrypt --no-keychain`</summary><br>
+
+Turn off macOS Keychain lookups for encrypt.
+
+```sh
+$ dotenvx encrypt --no-keychain
+◈ encrypted (.env)
+```
+
 </details>
 <details><summary>`encrypt --no-armor`</summary><br>
 
@@ -1763,8 +1798,6 @@ $ dotenvx encrypt --no-armor
 ◈ encrypted (.env)
 ```
 
-`--no-vlt` and `--no-ops` are deprecated aliases.
-
 </details>
 <details><summary>`encrypt -fk`</summary><br>
 
@@ -1884,6 +1917,16 @@ $ dotenvx decrypt
 ◇ decrypted (.env)
 ```
 
+</details>
+<details><summary>`decrypt --no-keychain`</summary><br>
+
+Turn off macOS Keychain lookups for decrypt.
+
+```sh
+$ dotenvx decrypt --no-keychain
+◇ decrypted (.env)
+```
+
 </details>
 <details><summary>`decrypt -f`</summary><br>
 
@@ -1995,6 +2038,16 @@ $ dotenvx keypair
 {"DOTENV_PUBLIC_KEY":"<publicKey>","DOTENV_PRIVATE_KEY":"<privateKey>"}
 ```
 
+</details>
+<details><summary>`keypair --no-keychain`</summary><br>
+
+Turn off macOS Keychain lookups for keypair.
+
+```sh
+$ dotenvx keypair --no-keychain
+{"DOTENV_PUBLIC_KEY":"<publicKey>","DOTENV_PRIVATE_KEY":"<privateKey>"}
+```
+
 </details>
 <details><summary>`keypair -f`</summary><br>
 
@@ -2121,101 +2174,14 @@ $ dotenvx ls -ef '**/.env.prod*'
 ```
 
 </details>
-<details><summary>`help`</summary><br>
-
-Output help for `dotenvx`.
-
-```sh
-$ dotenvx help
-Usage: dotenvx run -- yourcommand
-
-a secure dotenv–from the creator of `dotenv`
-
-Options:
-  -l, --log-level <level>      set log level (default: "info")
-  -q, --quiet                  sets log level to error
-  -v, --verbose                sets log level to verbose
-  -d, --debug                  sets log level to debug
-  -V, --version                output the version number
-  -h, --help                   display help for command
-
-Commands:
-  run                inject env at runtime [dotenvx run -- yourcommand]
-  get [KEY]          return a single environment variable
-  set <KEY> <value>  set a single environment variable
-  encrypt            encrypt .env file(s)
-  decrypt            decrypt .env file(s)
-  keypair [KEY]      print public/private keys for .env file(s)
-  ls [directory]     print all .env files in a tree structure
-  gitignore          append to .gitignore
-  precommit [directory]
-                     prevent committing .env files to code
-  prebuild [directory]
-                     prevent including .env files in docker
- 
-Professional Security: 
-  login                    log in to move keys off-device, share with your team, and audit access
-  logout                   log out of connected security features
-  armor                    ⛨ move private keys off-device [www.dotenvx.com/armor]
-```
-
-You can get more detailed help per command with `dotenvx help COMMAND`.
-
-```sh
-$ dotenvx help run
-Usage: @dotenvx/dotenvx run [options]
-
-inject env at runtime [dotenvx run -- yourcommand]
-
-Options:
-  -e, --env <strings...>            environment variable(s) set as string (example: "HELLO=Dotenvx") (default: [])
-  -f, --env-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'])
-  -h, --help                        display help for command
-
-Examples:
-
-  $ dotenvx run -- npm run dev
-  $ dotenvx run -- flask --app index run
-  $ dotenvx run -- php artisan serve
-  $ dotenvx run -- bin/rails s
-
-Try it:
-
-  $ echo "HELLO=Dotenvx" > .env
-  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
-
-  $ dotenvx run -- node index.js
-  [dotenvx@1.X.X] injecting env (1) from .env
-  Hello Dotenvx
-```
-
-</details>
-<details><summary>`--version`</summary><br>
-
-Check current version of `dotenvx`.
-
-```sh
-$ dotenvx --version
-X.X.X
-```
-
-</details>
-
-### Utilities
-
-Additional workflow helpers.
-
-<details><summary>`ext genexample`</summary><br>
+<details><summary>`genexample`</summary><br>
 
 In one command, generate a `.env.example` file from your current `.env` file contents.
 
 ```sh
 $ echo "HELLO=Dotenvx" > .env
 
-$ dotenvx ext genexample
+$ dotenvx genexample
 ▣ generated (.env.example)
 ```
 
@@ -2225,7 +2191,7 @@ HELLO=""
 ```
 
 </details>
-<details><summary>`ext genexample -f`</summary><br>
+<details><summary>`genexample -f`</summary><br>
 
 Pass multiple `.env` files to generate your `.env.example` file from the combination of their contents.
 
@@ -2233,7 +2199,7 @@ Pass multiple `.env` files to generate your `.env.example` file from the combina
 $ echo "HELLO=Dotenvx" > .env
 $ echo "DB_HOST=example.com" > .env.production
 
-$ dotenvx ext genexample -f .env -f .env.production
+$ dotenvx genexample -f .env -f .env.production
 ▣ generated (.env.example)
 ```
 
@@ -2244,7 +2210,7 @@ DB_HOST=""
 ```
 
 </details>
-<details><summary>`ext genexample directory`</summary><br>
+<details><summary>`genexample directory`</summary><br>
 
 Generate a `.env.example` file inside the specified directory. Useful for monorepos.
 
@@ -2253,7 +2219,7 @@ $ echo "HELLO=Dotenvx" > .env
 $ mkdir -p apps/backend
 $ echo "HELLO=Backend" > apps/backend/.env
 
-$ dotenvx ext genexample apps/backend
+$ dotenvx genexample apps/backend
 ▣ generated (.env.example)
 ```
 
@@ -2357,6 +2323,207 @@ CMD ["/usr/local/bin/dotenvx", "run", "--", "node", "apps/backend/index.js"]
 ```
 
 </details>
+<details><summary>`keychain`</summary><br>
+
+Store private keys in macOS Keychain to keep them out of `.env.keys`.
+
+Currently supported on macOS.
+
+</details>
+<details><summary>`keychain up`</summary><br>
+
+Move a private key from `.env.keys` into macOS Keychain.
+
+```sh
+$ dotenvx keychain up
+```
+
+Specify files with `-f` and `-fk`.
+
+```sh
+$ dotenvx keychain up -f .env.production -fk .env.keys
+```
+
+</details>
+<details><summary>`keychain down`</summary><br>
+
+Move a private key from macOS Keychain back into `.env.keys`.
+
+```sh
+$ dotenvx keychain down
+```
+
+</details>
+<details><summary>`keychain push`</summary><br>
+
+Copy a private key from `.env.keys` into macOS Keychain.
+
+```sh
+$ dotenvx keychain push
+```
+
+</details>
+<details><summary>`keychain pull`</summary><br>
+
+Copy a private key from macOS Keychain into `.env.keys`.
+
+```sh
+$ dotenvx keychain pull
+```
+
+</details>
+<details><summary>`armor`</summary><br>
+
+Move private keys into [Dotenvx Armor ⛨](https://dotenvx.com/armor) for off-device storage, sharing with your team, and audited access.
+
+</details>
+<details><summary>`armor up`</summary><br>
+
+Move a private key from `.env.keys` into Dotenvx Armor.
+
+```sh
+$ dotenvx login
+$ dotenvx armor up
+```
+
+Specify environment and team.
+
+```sh
+$ dotenvx armor up -f .env.production --team acme
+```
+
+</details>
+<details><summary>`armor down`</summary><br>
+
+Move a private key from Dotenvx Armor back into `.env.keys`.
+
+```sh
+$ dotenvx armor down
+```
+
+</details>
+<details><summary>`armor push`</summary><br>
+
+Copy a private key from `.env.keys` into Dotenvx Armor.
+
+```sh
+$ dotenvx armor push
+```
+
+</details>
+<details><summary>`armor pull`</summary><br>
+
+Copy a private key from Dotenvx Armor into `.env.keys`.
+
+```sh
+$ dotenvx armor pull
+```
+
+Use a token when running non-interactively.
+
+```sh
+$ dotenvx armor pull -f .env.production --token "$DOTENVX_ARMOR_TOKEN"
+```
+
+</details>
+<details><summary>`armor move`</summary><br>
+
+Move an armored key to another team.
+
+```sh
+$ dotenvx armor move --team acme
+```
+
+</details>
+<details><summary>`help`</summary><br>
+
+Output help for `dotenvx`.
+
+```sh
+$ dotenvx help
+Usage: dotenvx run -- yourcommand
+
+a secure dotenv–from the creator of `dotenv`
+
+Options:
+  -l, --log-level <level>      set log level (default: "info")
+  -q, --quiet                  sets log level to error
+  -v, --verbose                sets log level to verbose
+  -d, --debug                  sets log level to debug
+  -V, --version                output the version number
+  -h, --help                   display help for command
+
+Commands:
+  run                inject env at runtime [dotenvx run -- yourcommand]
+  get [KEY]          return a single environment variable
+  set <KEY> <value>  set a single environment variable
+  encrypt            encrypt .env file(s)
+  decrypt            decrypt .env file(s)
+  keypair [KEY]      print public/private keys for .env file(s)
+  ls [directory]     print all .env files in a tree structure
+  genexample [directory]
+                     generate .env.example
+  gitignore          append to .gitignore
+  precommit [directory]
+                     prevent committing .env files to code
+  prebuild [directory]
+                     prevent including .env files in docker
+ 
+Professional Security: 
+  login                    log in to move keys off-device, share with your team, and audit access
+  logout                   log out of connected security features
+  armor                    ⛨ move private keys off-device [www.dotenvx.com/armor]
+```
+
+You can get more detailed help per command with `dotenvx help COMMAND`.
+
+```sh
+$ dotenvx help run
+Usage: @dotenvx/dotenvx run [options]
+
+inject env at runtime [dotenvx run -- yourcommand]
+
+Options:
+  -e, --env <strings...>            environment variable(s) set as string (example: "HELLO=Dotenvx") (default: [])
+  -f, --env-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'])
+  -h, --help                        display help for command
+
+Examples:
+
+  $ dotenvx run -- npm run dev
+  $ dotenvx run -- flask --app index run
+  $ dotenvx run -- php artisan serve
+  $ dotenvx run -- bin/rails s
+
+Try it:
+
+  $ echo "HELLO=Dotenvx" > .env
+  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
+
+  $ dotenvx run -- node index.js
+  [dotenvx@1.X.X] injecting env (1) from .env
+  Hello Dotenvx
+```
+
+</details>
+<details><summary>`--version`</summary><br>
+
+Check current version of `dotenvx`.
+
+```sh
+$ dotenvx --version
+X.X.X
+```
+
+</details>
+
+### Utilities
+
+Additional workflow helpers.
+
 <details><summary>`ext scan`</summary><br>
 
 Scan for leaked secrets.
@@ -2614,8 +2781,6 @@ Turn off [Dotenvx Armor ⛨](https://dotenvx.com/armor) features.
 require('@dotenvx/dotenvx').config({noArmor: true})
 ```
 
-`noVlt` and `noOps` are deprecated aliases.
-
 </details>
 <details><summary>`parse(src)`</summary><br>
 

package/package.json

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

package/src/cli/actions/decrypt.js

@@ -17,6 +17,7 @@ async function decrypt () {
   const envs = this.envs
   const sesh = new Session()
   const noArmor = options.armor === false || (await sesh.noArmor())
+  const noKeychain = options.keychain === false || options.noKeychain === true
 
   let errorCount = 0
 
@@ -30,6 +31,7 @@ async function decrypt () {
       ek: options.excludeKey,
       fk: options.envKeysFile,
       noArmor,
+      noKeychain,
       onStatus: (text) => {
         if (spinner && text) {
           spinner.text = text
@@ -64,6 +66,7 @@ async function decrypt () {
         ek: options.excludeKey,
         fk: options.envKeysFile,
         noArmor,
+        noKeychain,
         onStatus: (text) => {
           if (spinner && text) {
             spinner.text = text

package/src/cli/actions/encrypt.js

@@ -21,12 +21,13 @@ async function encryptAction () {
   const fk = options.envKeysFile || '.env.keys'
   const noCreate = options.create === false
   const noArmor = options.armor === false || (!options.token && (await sesh.noArmor()))
+  const noKeychain = options.keychain === false || options.noKeychain === true
 
   let errorCount = 0
 
   // stdout - should not have a try so that exit codes can surface to stdout
   if (options.stdout) {
-    const { processedEnvs } = await encryptTransform({ envs, ik, ek, fk, noArmor, noCreate })
+    const { processedEnvs } = await encryptTransform({ envs, ik, ek, fk, noArmor, noCreate, noKeychain })
 
     if (spinner) spinner.stop()
     for (const processedEnv of processedEnvs) {
@@ -47,7 +48,7 @@ async function encryptAction () {
   }
 
   try {
-    const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await encryptTransform({ envs, ik, ek, fk, noArmor, noCreate })
+    const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await encryptTransform({ envs, ik, ek, fk, noArmor, noCreate, noKeychain })
 
     if (keysSrc) {
       await fsx.writeFileX(fk, keysSrc)

package/src/cli/actions/get.js

@@ -33,6 +33,7 @@ async function get (key) {
   try {
     const sesh = new Session()
     const noArmor = options.armor === false || (await sesh.noArmor())
+    const noKeychain = options.keychain === false || options.noKeychain === true
     const { parsed, errors } = await getResolver({
       key,
       envs,
@@ -40,6 +41,7 @@ async function get (key) {
       all: options.all,
       envKeysFile: options.envKeysFile,
       noArmor,
+      noKeychain,
       onStatus: (text) => {
         if (spinner && text) {
           spinner.text = text

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

@@ -0,0 +1,29 @@
+const { logger } = require('../../../shared/logger')
+const KeychainDown = require('./../../../lib/services/keychainDown')
+const createSpinner = require('../../../lib/helpers/createSpinner')
+const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
+
+async function down () {
+  const options = this.opts()
+  const spinner = await createSpinner({ ...options, text: 'unkeychaining' })
+
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    const { changed, privateKeyName, publicKeyValue } = new KeychainDown(options.envFile, options.envKeysFile).run()
+    const keyDisplay = armoredKeyDisplay(publicKeyValue) || privateKeyName
+
+    if (spinner) spinner.stop()
+    if (changed) {
+      logger.success(`◇ moved to .env.keys (${keyDisplay})`)
+    } else {
+      logger.info(`○ no change (${keyDisplay})`)
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    logger.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = down

package/src/cli/actions/keychain/pull.js

@@ -0,0 +1,29 @@
+const { logger } = require('../../../shared/logger')
+const KeychainPull = require('./../../../lib/services/keychainPull')
+const createSpinner = require('../../../lib/helpers/createSpinner')
+const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
+
+async function pull () {
+  const options = this.opts()
+  const spinner = await createSpinner({ ...options, text: 'pulling' })
+
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    const { changed, privateKeyName, publicKeyValue } = new KeychainPull(options.envFile, options.envKeysFile).run()
+    const keyDisplay = armoredKeyDisplay(publicKeyValue) || privateKeyName
+
+    if (spinner) spinner.stop()
+    if (changed) {
+      logger.success(`◇ pulled to .env.keys (${keyDisplay})`)
+    } else {
+      logger.info(`○ no change (${keyDisplay})`)
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    logger.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = pull

package/src/cli/actions/keychain/push.js

@@ -0,0 +1,29 @@
+const { logger } = require('../../../shared/logger')
+const KeychainPush = require('./../../../lib/services/keychainPush')
+const createSpinner = require('../../../lib/helpers/createSpinner')
+const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
+
+async function push () {
+  const options = this.opts()
+  const spinner = await createSpinner({ ...options, text: 'pushing' })
+
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    const { changed, privateKeyName, publicKeyValue } = new KeychainPush(options.envFile, options.envKeysFile).run()
+    const keyDisplay = armoredKeyDisplay(publicKeyValue) || privateKeyName
+
+    if (spinner) spinner.stop()
+    if (changed) {
+      logger.success(`⌥ pushed (${keyDisplay})`)
+    } else {
+      logger.info(`○ no change (${keyDisplay})`)
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    logger.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = push

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

@@ -0,0 +1,29 @@
+const { logger } = require('../../../shared/logger')
+const KeychainUp = require('./../../../lib/services/keychainUp')
+const createSpinner = require('../../../lib/helpers/createSpinner')
+const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
+
+async function up () {
+  const options = this.opts()
+  const spinner = await createSpinner({ ...options, text: 'keychaining' })
+
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    const { changed, privateKeyName, publicKeyValue } = new KeychainUp(options.envFile, options.envKeysFile).run()
+    const keyDisplay = armoredKeyDisplay(publicKeyValue) || privateKeyName
+
+    if (spinner) spinner.stop()
+    if (changed) {
+      logger.success(`⌥ keychained (${keyDisplay})`)
+    } else {
+      logger.info(`○ no change (${keyDisplay})`)
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    logger.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = up

package/src/cli/actions/keypair.js

@@ -21,6 +21,7 @@ async function keypair (key) {
       envFile: options.envFile,
       envKeysFile: options.envKeysFile,
       armor: options.armor,
+      noKeychain: options.keychain === false || options.noKeychain === true,
       token: options.token,
       command: process.argv.slice(2),
       onStatus: (text) => {