@dotenvx/dotenvx 2.1.4 → 2.2.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.1.4...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.2.0...main)
+
+## [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)
+
+### Changed
+
+* `precommit` and `prebuild` respect `_PLAIN` ([#871](https://github.com/dotenvx/dotenvx/pull/871))
 
 ## [2.1.4](https://github.com/dotenvx/dotenvx/compare/v2.1.3...v2.1.4) (2026-07-02)
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.4",
+  "version": "2.2.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -43,7 +43,7 @@
   },
   "funding": "https://dotenvx.com",
   "dependencies": {
-    "@dotenvx/primitives": "^1.7.0",
+    "@dotenvx/primitives": "^1.7.1",
     "commander": "^11.1.0",
     "conf": "^10.2.0",
     "dotenv": "^17.4.2",

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) => {

package/src/cli/actions/run.js

@@ -63,6 +63,7 @@ async function run () {
 
   const sesh = new Session()
   const noArmor = options.armor === false || (!options.token && (await sesh.noArmor()))
+  const noKeychain = options.keychain === false || options.noKeychain === true
 
   if (commandArgs.length < 1) {
     if (spinner) spinner.stop()
@@ -98,6 +99,7 @@ async function run () {
       processEnv: process.env,
       envKeysFile: options.envKeysFile,
       noArmor,
+      noKeychain,
       token: options.token,
       command: commandArgs,
       onStatus: (text) => {

package/src/cli/actions/set.js

@@ -65,11 +65,12 @@ async function set (key, value) {
   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
 
   try {
-    const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await setTransform({ envs, key, value, fk, noArmor, noCreate, encrypt })
+    const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await setTransform({ envs, key, value, fk, noArmor, noCreate, encrypt, noKeychain })
 
     if (keysSrc) {
       await fsx.writeFileX(fk, keysSrc)

package/src/cli/commands/keychain.js

@@ -0,0 +1,43 @@
+function configureKeychainCommand (keychain) {
+  keychain
+    .description('store private keys in macOS Keychain')
+    .action(function () {
+      this.help()
+    })
+
+  const upAction = require('./../actions/keychain/up')
+  keychain
+    .command('up')
+    .description('store key in macOS Keychain')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(upAction)
+
+  const downAction = require('./../actions/keychain/down')
+  keychain
+    .command('down')
+    .description('move key from macOS Keychain to .env.keys')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(downAction)
+
+  const pushAction = require('./../actions/keychain/push')
+  keychain
+    .command('push')
+    .description('push key to macOS Keychain from .env.keys')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(pushAction)
+
+  const pullAction = require('./../actions/keychain/pull')
+  keychain
+    .command('pull')
+    .description('pull key from macOS Keychain into .env.keys')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(pullAction)
+
+  return keychain
+}
+
+module.exports = configureKeychainCommand

package/src/cli/dotenvx.js

@@ -72,7 +72,8 @@ 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('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -95,7 +96,8 @@ 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)', 'json')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -115,7 +117,8 @@ program.command('set')
   .option('-c, --encrypt', 'encrypt value', true)
   .option('-p, --plain', 'store value as plain text', false)
   .option('--no-create', 'do not create .env file(s) when missing')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -132,7 +135,8 @@ program.command('encrypt')
   .option('--stdout', 'send to stdout')
   .option('--token <token>', 'set Armor ⛨ token')
   .option('--no-create', 'do not create .env file(s) when missing')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -146,7 +150,8 @@ program.command('decrypt')
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
   .option('-k, --key <keys...>', 'keys(s) to decrypt (default: all keys in file)')
   .option('-ek, --exclude-key <excludeKeys...>', 'keys(s) to exclude from decryption (default: none)')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .option('--stdout', 'send to stdout')
   .action(function (...args) {
@@ -161,7 +166,8 @@ program.command('keypair')
   .argument('[KEY]', 'environment variable key name')
   .option('-f, --env-file <path>', 'path(s) to your env file(s)')
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .option('-pp, --pretty-print', 'pretty print output')
   .option('--pp', 'pretty print output (alias)')
@@ -255,7 +261,11 @@ program.addHelpText('after', ' ')
 program.addHelpText('after', 'Professional Security: ')
 program.addHelpText('after', '  login                    log in to move keys off-device, share with your team, and audit access')
 program.addHelpText('after', '  logout                   log out of connected security features')
-program.addHelpText('after', '  armor                    ⛨ move private keys off-device [www.dotenvx.com/armor]')
+program.addHelpText('after', '  keychain                 ⌥ move private keys into macOS Keychain')
+program.addHelpText('after', '  armor                    ⛨ move private keys into Dotenvx Armor [www.dotenvx.com/armor]')
+
+// dotenvx keychain
+require('./commands/keychain')(program.command('keychain', { hidden: true }))
 
 // dotenvx armor
 require('./commands/armor')(program.command('armor', { hidden: true }))

package/src/lib/main.d.ts

@@ -179,6 +179,14 @@ export interface DotenvConfigOptions {
    */
   noArmor?: boolean;
 
+  /**
+   * Turn off macOS Keychain features.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').config({ noKeychain: true })
+   */
+  noKeychain?: boolean;
+
   /**
    * Turn off Dotenvx Armor features. Alias for `noArmor`.
    *
@@ -262,6 +270,14 @@ export interface SetOptions {
    */
   noArmor?: boolean;
 
+  /**
+   * Turn off macOS Keychain features.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').set(key, value, { noKeychain: true })
+   */
+  noKeychain?: boolean;
+
   /**
    * Turn off Dotenvx Armor features. Alias for `noArmor`.
    *
@@ -347,6 +363,14 @@ export interface GetOptions {
    */
   noArmor?: boolean;
 
+  /**
+   * Turn off macOS Keychain features.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').get('KEY', { noKeychain: true })
+   */
+  noKeychain?: boolean;
+
   /**
    * Turn off Dotenvx Armor features. Alias for `noArmor`.
    *

package/src/lib/main.js

@@ -66,6 +66,7 @@ const config = function (options = {}) {
 
   // dotenvx-armor related
   const noArmor = resolveNoArmor(options)
+  const noKeychain = resolveNoKeychain(options)
 
   try {
     let envs = buildEnvs(options)
@@ -81,6 +82,7 @@ const config = function (options = {}) {
       processEnv,
       envKeysFile,
       noArmor,
+      noKeychain,
       noSpinner: options.noSpinner,
       token: options.token
     })
@@ -227,6 +229,7 @@ const set = async function (key, value, options = {}) {
   const envKeysFilepath = options.envKeysFile
   const noCreate = options.create === false
   const noArmor = resolveNoArmor(options)
+  const noKeychain = resolveNoKeychain(options)
 
   const {
     keysSrc,
@@ -239,6 +242,7 @@ const set = async function (key, value, options = {}) {
     value,
     fk: envKeysFilepath,
     noArmor,
+    noKeychain,
     noCreate,
     encrypt
   })
@@ -306,6 +310,7 @@ const get = async function (key, options = {}) {
 
   const envs = buildEnvs(options)
   const noArmor = resolveNoArmor(options)
+  const noKeychain = resolveNoKeychain(options)
 
   // ignore
   const ignore = options.ignore || []
@@ -316,7 +321,8 @@ const get = async function (key, options = {}) {
     overload: options.overload,
     all: options.all,
     envKeysFile: options.envKeysFile,
-    noArmor
+    noArmor,
+    noKeychain
   })
 
   for (const error of errors || []) {
@@ -377,6 +383,10 @@ function resolveNoArmor (options = {}) {
   return options.noArmor === true || options.noOps === true || (!options.token && sesh.noArmorSync())
 }
 
+function resolveNoKeychain (options = {}) {
+  return options.noKeychain === true || options.keychain === false
+}
+
 module.exports = {
   // dotenv proxies
   config,

package/src/lib/providers/index.js

@@ -1,25 +1,41 @@
 const Session = require('./../../db/session')
 
 const armorProvider = require('./armor/index')
+const keychainProvider = require('./keychain/index')
+
 function syncArmorProvider (publicKeyHex) {
   const { createSyncFn } = require('synckit')
   const runProviderSync = createSyncFn(require.resolve('./worker.js'))
   return runProviderSync(require.resolve('./armor/index'), publicKeyHex)
 }
 
-async function providers (options = {}) {
-  if (Object.prototype.hasOwnProperty.call(options, 'provider')) {
-    return options.provider
-  }
+function hasKey (keyring, publicKeyHex) {
+  return keyring && keyring[publicKeyHex]
+}
 
-  if (options.noArmor || options.armor === false) {
-    return null
+function composeProviders (providerFns) {
+  return async function provider (publicKeyHex) {
+    for (const providerFn of providerFns) {
+      const keyring = await providerFn(publicKeyHex)
+      if (hasKey(keyring, publicKeyHex)) return keyring
+    }
+
+    return {}
   }
+}
 
-  const sesh = new Session()
-  const noArmor = !options.token && await sesh.noArmor()
-  if (noArmor) return null
+function composeProvidersSync (providerFns) {
+  return function providerSync (publicKeyHex) {
+    for (const providerFn of providerFns) {
+      const keyring = providerFn(publicKeyHex)
+      if (hasKey(keyring, publicKeyHex)) return keyring
+    }
 
+    return {}
+  }
+}
+
+function armorProviderForOptions (options) {
   return (publicKeyHex) => armorProvider(publicKeyHex, {
     onStatus: options.onStatus,
     token: options.token,
@@ -27,20 +43,65 @@ async function providers (options = {}) {
   })
 }
 
+function useKeychain (options) {
+  if (process.platform !== 'darwin') return false
+  if (process.env.CI) return false
+  return options.noKeychain !== true && options.keychain !== false
+}
+
+function useArmor (options, noArmor) {
+  return options.noArmor !== true && options.armor !== false && !noArmor
+}
+
+function providerFrom (providerFns, compose) {
+  if (providerFns.length === 0) return null
+  if (providerFns.length === 1) return providerFns[0]
+
+  return compose(providerFns)
+}
+
+async function providers (options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, 'provider')) {
+    return options.provider
+  }
+
+  const providerFns = []
+
+  if (useKeychain(options)) {
+    providerFns.push(keychainProvider)
+  }
+
+  if (options.noArmor !== true && options.armor !== false) {
+    const sesh = new Session()
+    const noArmor = !options.token && await sesh.noArmor()
+    if (useArmor(options, noArmor)) {
+      providerFns.push(armorProviderForOptions(options))
+    }
+  }
+
+  return providerFrom(providerFns, composeProviders)
+}
+
 providers.sync = function providersSync (options = {}) {
   if (Object.prototype.hasOwnProperty.call(options, 'provider')) {
     return options.provider
   }
 
-  if (options.noArmor || options.armor === false) {
-    return null
+  const providerFns = []
+
+  if (useKeychain(options)) {
+    providerFns.push(keychainProvider)
   }
 
-  const sesh = new Session()
-  const noArmor = !options.token && sesh.noArmorSync()
-  if (noArmor) return null
+  if (options.noArmor !== true && options.armor !== false) {
+    const sesh = new Session()
+    const noArmor = !options.token && sesh.noArmorSync()
+    if (useArmor(options, noArmor)) {
+      providerFns.push(syncArmorProvider)
+    }
+  }
 
-  return syncArmorProvider
+  return providerFrom(providerFns, composeProvidersSync)
 }
 
 module.exports = providers

package/src/lib/providers/keychain/index.js

@@ -0,0 +1,20 @@
+const { execFileSync } = require('child_process')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+function index (publicKeyHex) {
+  if (process.platform !== 'darwin') return {}
+
+  try {
+    const stdout = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKeyHex, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    const privateKeyHex = stdout.trim()
+    if (!privateKeyHex) return {}
+
+    return { [publicKeyHex]: privateKeyHex }
+  } catch {
+    return {}
+  }
+}
+
+module.exports = index

package/src/lib/resolvers/envs.js

@@ -235,7 +235,7 @@ async function envs (options = {}) {
   const readableFilepaths = new Set()
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
-  const provider = options.noArmor ? null : await providers(options)
+  const provider = await providers(options)
 
   for (const env of options.envs || []) {
     if (env.type === TYPE_ENV_FILE) {
@@ -269,7 +269,7 @@ function envsSync (options = {}) {
   const readableFilepaths = new Set()
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
-  const provider = options.noArmor ? null : providers.sync(options)
+  const provider = providers.sync(options)
 
   for (const env of options.envs || []) {
     if (env.type === TYPE_ENV_FILE) {

package/src/lib/resolvers/get.js

@@ -50,6 +50,7 @@ function buildOptions (options, processEnv) {
     processEnv,
     envKeysFilepath: options.envKeysFilepath || options.envKeysFile || null,
     noArmor: options.noArmor,
+    noKeychain: options.noKeychain,
     onStatus: options.onStatus
   }
 }

package/src/lib/services/keychainDown.js

@@ -0,0 +1,57 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const upsertEnvKey = require('../helpers/upsertEnvKey')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+class KeychainDown {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    let privateKey
+
+    try {
+      privateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    } catch (error) {
+      privateKey = readEnvKey(privateKeyName, envKeysFile, { strict: false })
+
+      if (privateKey) {
+        return {
+          changed: false,
+          privateKeyName,
+          privateKeyValue: privateKey,
+          publicKeyValue: publicKey
+        }
+      }
+
+      throw error
+    }
+
+    upsertEnvKey(privateKeyName, privateKey, envKeysFile)
+    execFileSync(SECURITY_BIN, ['delete-generic-password', '-s', SERVICE, '-a', publicKey], { stdio: 'ignore' })
+
+    return {
+      changed: true,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainDown

package/src/lib/services/keychainPull.js

@@ -0,0 +1,46 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const upsertEnvKey = require('../helpers/upsertEnvKey')
+const armoredKeyDisplay = require('../helpers/armoredKeyDisplay')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+class KeychainPull {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    let privateKey
+
+    try {
+      privateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    } catch {
+      throw new Error(`[NOT_FOUND] private key not found in macOS Keychain (${armoredKeyDisplay(publicKey)}). fix: [dotenvx keychain up]`)
+    }
+
+    const result = upsertEnvKey(privateKeyName, privateKey, envKeysFile)
+
+    return {
+      changed: result.changed,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainPull

package/src/lib/services/keychainPush.js

@@ -0,0 +1,63 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const armoredKeyDisplay = require('../helpers/armoredKeyDisplay')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+function addGenericPassword (publicKey, label, privateKey) {
+  try {
+    execFileSync(SECURITY_BIN, ['add-generic-password', '-U', '-s', SERVICE, '-a', publicKey, '-l', label, '-w', privateKey], { stdio: 'ignore' })
+  } catch {
+    throw new Error('failed to save private key to macOS Keychain')
+  }
+}
+
+class KeychainPush {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    const privateKey = readEnvKey(privateKeyName, envKeysFile, { strict: true })
+    const label = `dotenvx (${armoredKeyDisplay(publicKey)})`
+
+    try {
+      const existingPrivateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+
+      if (existingPrivateKey === privateKey) {
+        return {
+          changed: false,
+          label,
+          privateKeyName,
+          privateKeyValue: privateKey,
+          publicKeyValue: publicKey
+        }
+      }
+    } catch {}
+
+    addGenericPassword(publicKey, label, privateKey)
+
+    return {
+      changed: true,
+      label,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainPush

package/src/lib/services/keychainUp.js

@@ -0,0 +1,81 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const removeEnvKey = require('../helpers/removeEnvKey')
+const armoredKeyDisplay = require('../helpers/armoredKeyDisplay')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+function addGenericPassword (publicKey, label, privateKey) {
+  try {
+    execFileSync(SECURITY_BIN, ['add-generic-password', '-U', '-s', SERVICE, '-a', publicKey, '-l', label, '-w', privateKey], { stdio: 'ignore' })
+  } catch {
+    throw new Error('failed to save private key to macOS Keychain')
+  }
+}
+
+class KeychainUp {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    const label = `dotenvx (${armoredKeyDisplay(publicKey)})`
+    let existingPrivateKey
+
+    try {
+      existingPrivateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    } catch {}
+
+    const privateKey = readEnvKey(privateKeyName, envKeysFile, { strict: !existingPrivateKey })
+
+    if (existingPrivateKey) {
+      if (!privateKey) {
+        return {
+          changed: false,
+          label,
+          privateKeyName,
+          privateKeyValue: existingPrivateKey,
+          publicKeyValue: publicKey
+        }
+      }
+
+      if (existingPrivateKey === privateKey) {
+        const result = removeEnvKey(privateKeyName, envKeysFile)
+
+        return {
+          changed: result.changed,
+          label,
+          privateKeyName,
+          privateKeyValue: privateKey,
+          publicKeyValue: publicKey
+        }
+      }
+    }
+
+    addGenericPassword(publicKey, label, privateKey)
+    removeEnvKey(privateKeyName, envKeysFile)
+
+    return {
+      changed: true,
+      label,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainUp

package/src/lib/transforms/decrypt.js

@@ -22,7 +22,7 @@ async function decrypt (options = {}) {
   const ik = options.ik
   const ek = options.ek
   const fk = options.fk
-  const provider = options.noArmor ? null : await providers(options)
+  const provider = await providers(options)
 
   const processedEnvs = []
   const changedFilepaths = []

package/src/lib/transforms/set.js

@@ -36,6 +36,7 @@ async function setTransform (options = {}) {
   const value = options.value
   const fk = options.fk || '.env.keys'
   let noArmor = options.noArmor // key storage selector below
+  const noKeychain = options.noKeychain
   const noCreate = options.noCreate
   const noEncrypt = !options.encrypt || isPlainKey(key)
 
@@ -149,7 +150,8 @@ async function setTransform (options = {}) {
           envs: [env],
           all: true,
           envKeysFile: fk,
-          noArmor
+          noArmor,
+          noKeychain
         })
 
         const before = parsed[key]