@dotenvx/dotenvx 1.46.0 → 1.47.1

package/CHANGELOG.md

@@ -2,19 +2,56 @@
 
 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.46.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.47.1...main)
 
-## Added
+## 1.47.1
+
+### Added
+
+* Add convenience log that `radar active 📡` when dotenvx-radar is installed ([#625](https://github.com/dotenvx/dotenvx/pull/625))
+
+## 1.47.0
+
+### Added
+
+* Add optional `dotenvx radar` command ([#624](https://github.com/dotenvx/dotenvx/pull/624))
+* Radar is an early access commercial extension for dotenvx that will auto backup your .env files.
+
+```
+ _______________________________________________________________________
+|                                                                       |
+|  Dotenvx Radar: Env Observability                                     |
+|                                                                       |
+|  ░▒▓███████▓▒░ ░▒▓██████▓▒░░▒▓███████▓▒░ ░▒▓██████▓▒░░▒▓███████▓▒░    |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓███████▓▒░░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓████████▓▒░▒▓███████▓▒░    |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓███████▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|                                                                       |
+|  Observe, version, and back up your environment variables at runtime. |
+|                                                                       |
+|  Purchase lifetime access at https://dotenvx.com/radar                |
+|                                                                       |
+| --------------------------------------------------------------------- |
+| - thank you for using dotenvx! - @motdotla                            |
+|_______________________________________________________________________|
+```
+
+## 1.46.0
+
+### Added
 
 * Add error when hoisting issue experienced around commander.js ([#623](https://github.com/dotenvx/dotenvx/pull/623))
 
-## Removed
+### Removed
 
 * Remove `git-dotenvx` and `git dotenvx` shorthand ([#621](https://github.com/dotenvx/dotenvx/pull/621))
 
 ## 1.45.2
 
-## Changed
+### Changed
 
 * Minor README updates
 

package/README.md

@@ -767,6 +767,104 @@ Advanced CLI commands.
   DATABASE_URL postgres://username@localhost/my_database
   ```
 
+  </details>
+* <details><summary>`run` - Default Values</summary><br>
+
+  Use default values when environment variables are unset or empty.
+
+  ```ini
+  # .env
+  # Default value syntax: use value if set, otherwise use default
+  DATABASE_HOST=${DB_HOST:-localhost}
+  DATABASE_PORT=${DB_PORT:-5432}
+  
+  # Alternative syntax (no colon): use value if set, otherwise use default
+  API_URL=${API_BASE_URL-https://api.example.com}
+  ```
+  ```js
+  // index.js
+  console.log('DATABASE_HOST', process.env.DATABASE_HOST)
+  console.log('DATABASE_PORT', process.env.DATABASE_PORT)
+  console.log('API_URL', process.env.API_URL)
+  ```
+  ```sh
+  $ dotenvx run --debug -- node index.js
+  [dotenvx@1.X.X] injecting env (3) from .env
+  DATABASE_HOST localhost
+  DATABASE_PORT 5432
+  API_URL https://api.example.com
+  ```
+
+  </details>
+* <details><summary>`run` - Alternate Values</summary><br>
+
+  Use alternate values when environment variables are set and non-empty.
+
+  ```ini
+  # .env
+  NODE_ENV=production
+  
+  # Alternate value syntax: use alternate if set and non-empty, otherwise empty
+  DEBUG_MODE=${NODE_ENV:+false}
+  LOG_LEVEL=${NODE_ENV:+error}
+  
+  # Alternative syntax (no colon): use alternate if set, otherwise empty  
+  CACHE_ENABLED=${NODE_ENV+true}
+  ```
+  ```js
+  // index.js
+  console.log('NODE_ENV', process.env.NODE_ENV)
+  console.log('DEBUG_MODE', process.env.DEBUG_MODE)
+  console.log('LOG_LEVEL', process.env.LOG_LEVEL)
+  console.log('CACHE_ENABLED', process.env.CACHE_ENABLED)
+  ```
+  ```sh
+  $ dotenvx run --debug -- node index.js
+  [dotenvx@1.X.X] injecting env (4) from .env
+  NODE_ENV production
+  DEBUG_MODE false
+  LOG_LEVEL error
+  CACHE_ENABLED true
+  ```
+
+  </details>
+* <details><summary>`run` - Interpolation Syntax Summary (Variable Expansion, Default/Alternate Values)</summary><br>
+
+  Complete reference for variable interpolation patterns supported by dotenvx:
+
+  ```ini
+  # .env
+  DEFINED_VAR=hello
+  EMPTY_VAR=
+  # UNDEFINED_VAR is not set
+  
+  # Default value syntax - use variable if set/non-empty, otherwise use default
+  TEST1=${DEFINED_VAR:-fallback}     # Result: "hello"
+  TEST2=${EMPTY_VAR:-fallback}       # Result: "fallback"  
+  TEST3=${UNDEFINED_VAR:-fallback}   # Result: "fallback"
+  
+  # Default value syntax (no colon) - use variable if set, otherwise use default
+  TEST4=${DEFINED_VAR-fallback}      # Result: "hello"
+  TEST5=${EMPTY_VAR-fallback}        # Result: "" (empty, but set)
+  TEST6=${UNDEFINED_VAR-fallback}    # Result: "fallback"
+  
+  # Alternate value syntax - use alternate if variable is set/non-empty, otherwise empty
+  TEST7=${DEFINED_VAR:+alternate}    # Result: "alternate"
+  TEST8=${EMPTY_VAR:+alternate}      # Result: "" (empty)
+  TEST9=${UNDEFINED_VAR:+alternate}  # Result: "" (empty)
+  
+  # Alternate value syntax (no colon) - use alternate if variable is set, otherwise empty  
+  TEST10=${DEFINED_VAR+alternate}    # Result: "alternate"
+  TEST11=${EMPTY_VAR+alternate}      # Result: "alternate" (empty but set)
+  TEST12=${UNDEFINED_VAR+alternate}  # Result: "" (empty)
+  ```
+
+  **Key differences:**
+  - `:-` vs `-`: The colon makes empty values trigger the fallback
+  - `:+` vs `+`: The colon makes empty values not trigger the alternate  
+  - Default syntax (`-`): Use variable value or fallback
+  - Alternate syntax (`+`): Use alternate value or empty string
+
   </details>
 * <details><summary>`run` - Command Substitution</summary><br>
 
@@ -897,6 +995,31 @@ Advanced CLI commands.
 
   Note that with `--overload` subsequent files DO override pre-existing variables defined in previous files.
 
+  </details>
+* <details><summary>`run` - Environment Variable Precedence (Container/Cloud Deployments)</summary><br>
+
+  When deploying applications in containers or cloud environments, you often need to override specific environment variables at runtime without modifying committed `.env` files. By default, dotenvx follows the historic dotenv principle: **environment variables already present take precedence over `.env` files**.
+
+  ```sh
+  # .env.prod contains: MODEL_REGISTRY=registry.company.com/models/v1
+  $ echo "MODEL_REGISTRY=registry.company.com/models/v1" > .env.prod
+  $ echo "console.log('MODEL_REGISTRY:', process.env.MODEL_REGISTRY)" > app.js
+
+  # Without environment variable set - uses .env.prod value
+  $ dotenvx run -f .env.prod -- node app.js
+  MODEL_REGISTRY: registry.company.com/models/v1
+
+  # With environment variable set (e.g., via Azure Container Service) - environment variable takes precedence
+  $ MODEL_REGISTRY=registry.azure.com/models/v2 dotenvx run -f .env.prod -- node app.js
+  MODEL_REGISTRY: registry.azure.com/models/v2
+
+  # To force .env.prod to override environment variables, use --overload
+  $ MODEL_REGISTRY=registry.azure.com/models/v2 dotenvx run -f .env.prod --overload -- node app.js
+  MODEL_REGISTRY: registry.company.com/models/v1
+  ```
+
+  **For container deployments:** Set environment variables through your cloud provider's UI/configuration (Azure Container Service, AWS ECS, etc.) to override specific values from committed `.env` files without rebuilding your application.
+
   </details>
 * <details><summary>`DOTENV_PRIVATE_KEY=key run`</summary><br>
   

package/package.json

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

package/src/cli/actions/run.js

@@ -6,6 +6,7 @@ const Run = require('./../../lib/services/run')
 
 const conventions = require('./../../lib/helpers/conventions')
 const DeprecationNotice = require('./../../lib/helpers/deprecationNotice')
+const logRadar = require('./../../lib/helpers/logRadar')
 
 async function run () {
   const commandArgs = this.args
@@ -40,6 +41,8 @@ async function run () {
 
     new DeprecationNotice().dotenvKey() // DEPRECATION NOTICE
 
+    logRadar()
+
     const {
       processedEnvs,
       readableStrings,

package/src/cli/dotenvx.js

@@ -44,7 +44,7 @@ program
     setLogLevel(options)
   })
 
-// for dynamic loading of dotenvx-pro, etc
+// for dynamic loading of dotenvx-radar, etc
 program
   .argument('[command]', 'dynamic command')
   .argument('[args...]', 'dynamic command arguments')
@@ -69,7 +69,7 @@ program.command('run')
   .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', collectEnvs('envFile'), [])
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
   .option('-fv, --env-vault-file <paths...>', 'path(s) to your .env.vault file(s)', collectEnvs('envVaultFile'), [])
-  .option('-o, --overload', 'override existing env variables')
+  .option('-o, --overload', 'override existing env variables (by default, existing env vars take precedence over .env files)')
   .option('--strict', 'process.exit(1) on any errors', false)
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
   .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
@@ -88,7 +88,7 @@ program.command('get')
   .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', collectEnvs('envFile'), [])
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
   .option('-fv, --env-vault-file <paths...>', 'path(s) to your .env.vault file(s)', collectEnvs('envVaultFile'), [])
-  .option('-o, --overload', 'override existing env variables')
+  .option('-o, --overload', 'override existing env variables (by default, existing env vars take precedence over .env files)')
   .option('--strict', 'process.exit(1) on any errors', false)
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
   .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
@@ -200,7 +200,7 @@ program.command('help [command]')
 // dotenvx pro
 program.addHelpText('after', ' ')
 program.addHelpText('after', 'Advanced: ')
-program.addHelpText('after', '  pro                          🏆 pro')
+program.addHelpText('after', '  radar                        📡 radar')
 program.addHelpText('after', '  ext                          🔌 extensions')
 
 // dotenvx ext

package/src/lib/helpers/executeDynamic.js

@@ -50,6 +50,31 @@ function executeDynamic (program, command, rawArgs) {
       console.log('')
       logger.warn(`[INSTALLATION_NEEDED] install dotenvx-${command} to use [dotenvx ${command}] commands 🏆`)
       logger.help('? see installation instructions [https://github.com/dotenvx/dotenvx-pro]')
+    } else if (command === 'radar') {
+      const radar = ` _______________________________________________________________________
+|                                                                       |
+|  Dotenvx Radar: Env Observability                                     |
+|                                                                       |
+|  ░▒▓███████▓▒░ ░▒▓██████▓▒░░▒▓███████▓▒░ ░▒▓██████▓▒░░▒▓███████▓▒░    |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓███████▓▒░░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓████████▓▒░▒▓███████▓▒░    |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓███████▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░   |
+|                                                                       |
+|  Observe, version, and back up your environment variables at runtime. |
+|                                                                       |
+|  Purchase lifetime access at https://dotenvx.com/radar                |
+|                                                                       |
+| --------------------------------------------------------------------- |
+| - thank you for using dotenvx! - @motdotla                            |
+|_______________________________________________________________________|`
+
+      console.log(radar)
+      console.log('')
+      logger.warn(`[INSTALLATION_NEEDED] install dotenvx-${command} to use [dotenvx ${command}] 📡`)
+      logger.help('? see installation instructions [https://dotenvx.com/radar]')
     } else {
       logger.info(`error: unknown command '${command}'`)
     }

package/src/lib/helpers/logRadar.js

@@ -0,0 +1,31 @@
+const path = require('path')
+const childProcess = require('child_process')
+
+const { logger } = require('./../../shared/logger')
+
+function logRadar () {
+  let installed = false
+
+  try {
+    // if installed as sibling module
+    const projectRoot = path.resolve(process.cwd())
+    const dotenvxRadarPath = require.resolve('@dotenvx/dotenvx-radar', { paths: [projectRoot] })
+    require(dotenvxRadarPath)
+    installed = true
+  } catch (_e) {
+    try {
+      // if installed as binary cli
+      childProcess.execSync('dotenvx-radar help', { stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim()
+      installed = true
+      // if succeeds
+    } catch (_e) {
+      // do nothing
+    }
+  }
+
+  if (installed) {
+    logger.successv('radar active 📡')
+  }
+}
+
+module.exports = logRadar

package/src/lib/main.js

@@ -321,7 +321,7 @@ module.exports = {
   ls,
   keypair,
   genexample,
-  // expose for libs depending on @dotenvx/dotenvx - like dotenvx-pro
+  // expose for libs depending on @dotenvx/dotenvx - like dotenvx-radar
   setLogLevel,
   logger,
   getColor,