@dotenvx/dotenvx 1.58.0 → 1.59.0

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 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/v1.58.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.59.0...main)
+
+## [1.59.0](https://github.com/dotenvx/dotenvx/compare/v1.58.0...v1.59.0) (2026-03-28)
+
+### Changed
+
+* `encrypt` and `set` now create a `.env` file if one does not exist ([#771](https://github.com/dotenvx/dotenvx/pull/771))
+* pass `--no-create` to prevent file creation
 
 ## [1.58.0](https://github.com/dotenvx/dotenvx/compare/v1.57.5...v1.58.0) (2026-03-27)
 

package/package.json

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

package/src/cli/actions/encrypt.js

@@ -12,12 +12,13 @@ function encrypt () {
 
   const envs = this.envs
   const opsOn = options.opsOff !== true
+  const noCreate = options.create === false
 
   // stdout - should not have a try so that exit codes can surface to stdout
   if (options.stdout) {
     const {
       processedEnvs
-    } = new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, opsOn).run()
+    } = new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, opsOn, noCreate).run()
 
     for (const processedEnv of processedEnvs) {
       console.log(processedEnv.envSrc)
@@ -29,7 +30,7 @@ function encrypt () {
         processedEnvs,
         changedFilepaths,
         unchangedFilepaths
-      } = new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, opsOn).run()
+      } = new Encrypt(envs, options.key, options.excludeKey, options.envKeysFile, opsOn, noCreate).run()
 
       for (const processedEnv of processedEnvs) {
         logger.verbose(`encrypting ${processedEnv.envFilepath} (${processedEnv.filepath})`)

package/src/cli/actions/set.js

@@ -23,12 +23,13 @@ function set (key, value) {
     const envs = this.envs
     const envKeysFilepath = options.envKeysFile
     const opsOn = options.opsOff !== true
+    const noCreate = options.create === false
 
     const {
       processedEnvs,
       changedFilepaths,
       unchangedFilepaths
-    } = new Sets(key, value, envs, encrypt, envKeysFilepath, opsOn).run()
+    } = new Sets(key, value, envs, encrypt, envKeysFilepath, opsOn, noCreate).run()
 
     let withEncryption = ''
 

package/src/cli/dotenvx.js

@@ -116,6 +116,7 @@ program.command('set')
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
   .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('--ops-off', 'disable dotenvx-ops features', sesh.opsOff())
   .action(function (...args) {
     this.envs = envs
@@ -130,6 +131,7 @@ program.command('encrypt')
   .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 encrypt (default: all keys in file)')
   .option('-ek, --exclude-key <excludeKeys...>', 'keys(s) to exclude from encryption (default: none)')
+  .option('--no-create', 'do not create .env file(s) when missing')
   .option('--ops-off', 'disable dotenvx-ops features', sesh.opsOff())
   .option('--stdout', 'send to stdout')
   .action(function (...args) {

package/src/lib/helpers/kits/sample.js

@@ -0,0 +1,33 @@
+const SAMPLE_ENV_KIT = `
+# ── Database ─────────────────────────────────────
+DATABASE_URL="postgresql://postgres:pass@db.ref.supabase.co:5432/postgres"
+
+# ── Auth ─────────────────────────────────────────
+AUTH0_CLIENT_ID="xxxx"
+AUTH0_CLIENT_SECRET="xxxx"
+
+# ── AI / LLM ────────────────────────────────────
+OPENAI_API_KEY="sk-xxxx"
+ANTHROPIC_API_KEY="sk-ant-xxxx"
+
+# ── Email ────────────────────────────────────────
+RESEND_API_KEY="re_xxxx"
+
+# ── Cloud Storage ────────────────────────────────
+AWS_ACCESS_KEY_ID="xxxx"
+AWS_SECRET_ACCESS_KEY="xxxx"
+
+# ── Analytics / Monitoring ───────────────────────
+SENTRY_DSN="https://hex@o1234.ingest.us.sentry.io/1234567"
+
+# ── Payments ─────────────────────────────────────
+STRIPE_API_KEY="sk_test_xxxx"
+
+# ── Feature Flags ────────────────────────────────
+FLAGSMITH_ENV_ID="xxxx"
+
+# ── CI/CD / Deployment ──────────────────────────
+VERCEL_TOKEN="vcp_xxxx"
+`.trimStart()
+
+module.exports = SAMPLE_ENV_KIT

package/src/lib/services/encrypt.js

@@ -26,14 +26,16 @@ const {
 const replace = require('./../helpers/replace')
 const dotenvParse = require('./../helpers/dotenvParse')
 const detectEncoding = require('./../helpers/detectEncoding')
+const SAMPLE_ENV_KIT = require('./../helpers/kits/sample')
 
 class Encrypt {
-  constructor (envs = [], key = [], excludeKey = [], envKeysFilepath = null, opsOn = false) {
+  constructor (envs = [], key = [], excludeKey = [], envKeysFilepath = null, opsOn = false, noCreate = false) {
     this.envs = determine(envs, process.env)
     this.key = key
     this.excludeKey = excludeKey
     this.envKeysFilepath = envKeysFilepath
     this.opsOn = opsOn
+    this.noCreate = noCreate
 
     this.processedEnvs = []
     this.changedFilepaths = new Set()
@@ -75,8 +77,17 @@ class Encrypt {
     row.envFilepath = envFilepath
 
     try {
+      // if noCreate is on then detectEncoding will throw and we'll halt the calls
+      // but if noCreate is false then create the file if it doesn't exist
+      if (!fsx.existsSync(filepath) && !this.noCreate) {
+        fsx.writeFileX(filepath, SAMPLE_ENV_KIT)
+      }
       const encoding = detectEncoding(filepath)
       let envSrc = fsx.readFileX(filepath, { encoding })
+      if (envSrc.trim().length === 0) {
+        envSrc = SAMPLE_ENV_KIT
+        row.kitCreated = 'sample'
+      }
       const envParsed = dotenvParse(envSrc)
 
       let publicKey

package/src/lib/services/sets.js

@@ -27,13 +27,14 @@ const dotenvParse = require('./../helpers/dotenvParse')
 const detectEncoding = require('./../helpers/detectEncoding')
 
 class Sets {
-  constructor (key, value, envs = [], encrypt = true, envKeysFilepath = null, opsOn = false) {
+  constructor (key, value, envs = [], encrypt = true, envKeysFilepath = null, opsOn = false, noCreate = false) {
     this.envs = determine(envs, process.env)
     this.key = key
     this.value = value
     this.encrypt = encrypt
     this.envKeysFilepath = envKeysFilepath
     this.opsOn = opsOn
+    this.noCreate = noCreate
 
     this.processedEnvs = []
     this.changedFilepaths = new Set()
@@ -72,10 +73,30 @@ class Sets {
     row.changed = false
 
     try {
+      let seededWithInitialKey = false
+
+      if (!fsx.existsSync(filepath)) {
+        if (this.noCreate) {
+          detectEncoding(filepath) // throws ENOENT
+        } else {
+          fsx.writeFileX(filepath, '')
+        }
+      }
+
       const encoding = detectEncoding(filepath)
       let envSrc = fsx.readFileX(filepath, { encoding })
+
+      // blank files seeded by `set` should contain only the key being set
+      if (row.key && envSrc.trim().length === 0) {
+        envSrc = `${row.key}="${this.value}"\n`
+        seededWithInitialKey = true
+      }
+
       const envParsed = dotenvParse(envSrc)
       row.originalValue = envParsed[row.key] || null
+      if (seededWithInitialKey) {
+        row.originalValue = null
+      }
       const wasPlainText = !isEncrypted(row.originalValue)
       this.readableFilepaths.add(envFilepath)
 
@@ -119,7 +140,13 @@ class Sets {
 
       const goingFromPlainTextToEncrypted = wasPlainText && this.encrypt
       const valueChanged = this.value !== row.originalValue
-      if (goingFromPlainTextToEncrypted || valueChanged) {
+      const shouldPersistSeededPlainValue = seededWithInitialKey && !this.encrypt
+
+      if (shouldPersistSeededPlainValue) {
+        row.envSrc = envSrc
+        this.changedFilepaths.add(envFilepath)
+        row.changed = true
+      } else if (goingFromPlainTextToEncrypted || valueChanged) {
         row.envSrc = replace(envSrc, this.key, row.encryptedValue || this.value)
         this.changedFilepaths.add(envFilepath)
         row.changed = true