a better dotenv–from the creator of dotenv.

• run anywhere (cross-platform)
• multi-environment
• encrypted envs

Install and use it in code just like dotenv.

npm install @dotenvx/dotenvx --save

// index.js
require('@dotenvx/dotenvx').config()

console.log(`Hello ${process.env.HELLO}`)

Or install globally

brew install dotenvx/brew/dotenvx

• other global ways to install

Install globally as a cli to unlock dotenv for ANY language, framework, or platform. 💥

I am using (and recommending) this approach going forward. – motdotla

$ echo "HELLO=World" > .env
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ node index.js
Hello undefined # without dotenvx

$ dotenvx run -- node index.js
Hello World # with dotenvx
> :-D

see extended quickstart guide

More examples

• TypeScript 📘

  
  

  // package.json
  {
    "type": "module",
    "dependencies": {
      "chalk": "^5.3.0"
    }
  }

  // index.ts
  import chalk from 'chalk'
  console.log(chalk.blue(`Hello ${process.env.HELLO}`))

  $ npm install
  $ echo "HELLO=World" > .env
  
  $ dotenvx run -- npx tsx index.ts
  Hello World

• Deno 🦕

  
  

  $ echo "HELLO=World" > .env
  $ echo "console.log('Hello ' + Deno.env.get('HELLO'))" > index.ts
  
  $ deno run --allow-env index.ts
  Hello undefined
  
  $ dotenvx run -- deno run --allow-env index.ts
  Hello World

• Bun 🥟

  
  

  $ echo "HELLO=Test" > .env.test
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ bun index.js
  Hello undefined
  
  $ dotenvx run -f .env.test -- bun index.js
  Hello Test

• Python 🐍

  
  

  $ echo "HELLO=World" > .env
  $ echo 'import os;print("Hello " + os.getenv("HELLO", ""))' > index.py
  
  $ dotenvx run -- python3 index.py
  Hello World

  see extended python guide

• PHP 🐘

  
  

  $ echo "HELLO=World" > .env
  $ echo '<?php echo "Hello {$_SERVER["HELLO"]}\n";' > index.php
  
  $ dotenvx run -- php index.php
  Hello World

  see extended php guide

• Ruby 💎

  
  

  $ echo "HELLO=World" > .env
  $ echo 'puts "Hello #{ENV["HELLO"]}"' > index.rb
  
  $ dotenvx run -- ruby index.rb
  Hello World

  see extended ruby guide

• Go 🐹

  
  

  $ echo "HELLO=World" > .env
  $ echo 'package main; import ("fmt"; "os"); func main() { fmt.Printf("Hello %s\n", os.Getenv("HELLO")) }' > main.go
  
  $ dotenvx run -- go run main.go
  Hello World

  see extended go guide

• Rust 🦀

  
  

  $ echo "HELLO=World" > .env
  $ echo 'fn main() {let hello = std::env::var("HELLO").unwrap_or("".to_string());println!("Hello {hello}");}' > src/main.rs
  
  $ dotenvx run -- cargo run
  Hello World

  see extended rust guide

• Java ☕️

  
  

  $ echo "HELLO=World" > .env
  $ echo 'public class Index { public static void main(String[] args) { System.out.println("Hello " + System.getenv("HELLO")); } }' > index.java
  
  $ dotenvx run -- java index.java
  Hello World

• .NET 🔵

  
  

  $ dotnet new console -n HelloWorld -o HelloWorld
  $ cd HelloWorld
  $ echo "HELLO=World" > .env
  $ echo 'Console.WriteLine($"Hello {Environment.GetEnvironmentVariable("HELLO")}");' > Program.cs
  
  $ dotenvx run -- dotnet run
  Hello World

• Bash 🖥️

  
  

  $ echo "HELLO=World" > .env
  
  $ dotenvx run --quiet -- sh -c 'echo Hello $HELLO'
  Hello World

• Cron ⏰

  
  

  # run every day at 8am
  0 8 * * * dotenvx run -- /path/to/myscript.sh

• Frameworks ▲

  
  

  $ dotenvx run -- next dev
  $ dotenvx run -- npm start
  $ dotenvx run -- bin/rails s
  $ dotenvx run -- php artisan serve

  see framework guides

• Docker 🐳

  
  

  $ docker run -it --rm -v $(pwd):/app dotenv/dotenvx run -- node index.js

  Or in any image:

  FROM node:latest
  RUN echo "HELLO=World" > .env && echo "console.log('Hello ' + process.env.HELLO)" > index.js
  RUN curl -fsS https://dotenvx.sh/ | sh
  CMD ["dotenvx", "run", "--", "echo", "Hello $HELLO"]

  see docker guide

• CI/CDs 🐙

  
  

  name: build
  on: [push]
  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: curl -fsS https://dotenvx.sh/ | sh
      - run: dotenvx run -- node build.js
        env:
          DOTENV_KEY: ${{ secrets.DOTENV_KEY }}

  see github actions guide

• Platforms

  
  

  # heroku
  heroku buildpacks:add https://github.com/dotenvx/heroku-buildpack-dotenvx
  
  # docker
  RUN curl -fsS https://dotenvx.sh/ | sh
  
  # vercel
  npm install @dotenvx/dotenvx --save

  see platform guides

• Process Managers

  
  

  // pm2
  "scripts": {
    "start": "dotenvx run -- pm2-runtime start ecosystem.config.js --env production"
  },

  see process manager guides

• npx

  
  

  # alternatively use npx
  $ npx @dotenvx/dotenvx run -- node index.js
  $ npx @dotenvx/dotenvx run -- next dev
  $ npx @dotenvx/dotenvx run -- npm start

• npm

  
  

  $ npm install @dotenvx/dotenvx --save

  {
    "scripts": {
      "start": "./node_modules/.bin/dotenvx run -- node index.js"
    },
    "dependencies": {
      "@dotenvx/dotenvx": "^0.5.0"
    }
  }

  $ npm run start
  
  > start
  > ./node_modules/.bin/dotenvx run -- node index.js
  
  [dotenvx][info] loading env (1) from .env
  Hello World

• Git

  
  

  # use as a git submodule
  $ git dotenvx run -- node index.js
  $ git dotenvx run -- next dev
  $ git dotenvx run -- npm start

• Variable Expansion

  
  

  Reference and expand variables already on your machine for use in your .env file.

  # .env
  USERNAME="username"
  DATABASE_URL="postgres://${USERNAME}@localhost/my_database"

  // index.js
  console.log('DATABASE_URL', process.env.DATABASE_URL)

  $ dotenvx run --debug -- node index.js
  [[email protected]] injecting env (2) from .env
  DATABASE_URL postgres://username@localhost/my_database

• Command Substitution

  
  

  Add the output of a command to one of your variables in your .env file.

  # .env
  DATABASE_URL="postgres://$(whoami)@localhost/my_database"

  // index.js
  console.log('DATABASE_URL', process.env.DATABASE_URL)

  $ dotenvx run --debug -- node index.js
  [[email protected]] injecting env (1) from .env
  DATABASE_URL postgres://yourusername@localhost/my_database

Create a .env.production file and use -f to load it. It's straightforward, yet flexible.

$ echo "HELLO=production" > .env.production
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ dotenvx run -f .env.production -- node index.js
[dotenvx][info] loading env (1) from .env.production
Hello production
> ^^

More examples

• multiple `.env` files

  
  

  $ echo "HELLO=local" > .env.local
  
  $ echo "HELLO=World" > .env
  
  $ dotenvx run -f .env.local -f .env -- node index.js
  [dotenvx][info] loading env (1) from .env.local,.env
  Hello local

• `--overload` flag

  
  

  $ echo "HELLO=local" > .env.local
  
  $ echo "HELLO=World" > .env
  
  $ dotenvx run -f .env.local -f .env --overload -- node index.js
  [dotenvx][info] loading env (1) from .env.local,.env
  Hello World

• `--verbose` flag

  
  

  $ echo "HELLO=production" > .env.production
  
  $ dotenvx run -f .env.production --verbose -- node index.js
  [dotenvx][verbose] injecting env from /path/to/.env.production
  [dotenvx][verbose] HELLO set
  [dotenvx][info] loading env (1) from .env.production
  Hello production

• `--debug` flag

  
  

  $ echo "HELLO=production" > .env.production
  
  $ dotenvx run -f .env.production --debug -- node index.js
  [dotenvx][debug] configuring options
  [dotenvx][debug] {"envFile":[".env.production"]}
  [dotenvx][verbose] injecting env from /path/to/.env.production
  [dotenvx][debug] reading env from /path/to/.env.production
  [dotenvx][debug] parsing env from /path/to/.env.production
  [dotenvx][debug] {"HELLO":"production"}
  [dotenvx][debug] writing env from /path/to/.env.production
  [dotenvx][verbose] HELLO set
  [dotenvx][debug] HELLO set to production
  [dotenvx][info] loading env (1) from .env.production
  Hello production

• `--quiet` flag

  
  

  Use --quiet to suppress all output (except errors).

  $ echo "HELLO=production" > .env.production
  
  $ dotenvx run -f .env.production --quiet -- node index.js
  Hello production

• `--log-level` flag

  
  

  Set --log-level to whatever you wish. For example, to supress warnings (risky), set log level to error:

  $ echo "HELLO=production" > .env.production
  
  $ dotenvx run -f .env.production --log-level=error -- node index.js
  Hello production

  Available log levels are error, warn, info, verbose, debug, silly

• `--convention` flag

  
  

  Load envs using Next.js' convention. Set --convention to nextjs:

  $ echo "HELLO=development local" > .env.development.local
  $ echo "HELLO=local" > .env.local
  $ echo "HELLO=development" > .env.development
  $ echo "HELLO=env" > .env
  
  $ dotenvx run --convention=nextjs -- node index.js
  Hello development local

  (more conventions available upon request)

Add encryption to your .env files with a single command. Pass the --encrypt flag.

$ dotenvx set HELLO World --encrypt
set HELLO with encryption (.env)

A DOTENV_PUBLIC_KEY (encryption key) and a DOTENV_PRIVATE_KEY (decryption key) are generated using the same public-key cryptography as Bitcoin.

More examples

• `.env`

  
  

  $ dotenvx set HELLO World --encrypt
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -- node index.js
  [dotenvx] injecting env (2) from .env
  Hello World

• `.env.production`

  
  

  $ dotenvx set HELLO Production --encrypt -f .env.production
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ DOTENV_PRIVATE_KEY_PRODUCTION="<.env.production private key>" dotenvx run -- node index.js
  [dotenvx] injecting env (2) from .env.production
  Hello Production

  Note the DOTENV_PRIVATE_KEY_PRODUCTION ends with _PRODUCTION. This instructs dotenvx run to load the .env.production file.

• `.env.ci`

  
  

  $ dotenvx set HELLO Ci --encrypt -f .env.ci
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ DOTENV_PRIVATE_KEY_CI="<.env.ci private key>" dotenvx run -- node index.js
  [dotenvx] injecting env (2) from .env.ci
  Hello Ci

  Note the DOTENV_PRIVATE_KEY_CI ends with _CI. This instructs dotenvx run to load the .env.ci file. See the pattern?

• combine multiple encrypted .env files

  
  

  $ dotenvx set HELLO World --encrypt -f .env
  $ dotenvx set HELLO Production --encrypt -f .env.production
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ DOTENV_PRIVATE_KEY="<.env private key>" DOTENV_PRIVATE_KEY_PRODUCTION="<.env.production private key>" dotenvx run -- node index.js
  [dotenvx] injecting env (3) from .env, .env.production
  Hello World

  Note the DOTENV_PRIVATE_KEY instructs dotenvx run to load the .env file and the DOTENV_PRIVATE_KEY_PRODUCTION instructs it to load the .env.production file. See the pattern?

• other curves

  
  

  secp256k1 is a well-known and battle tested curve, in use with Bitcoin and other cryptocurrencies, but we are open to adding support for more curves.

  If your organization's compliance department requires NIST approved curves or other curves like curve25519, please reach out at [email protected].

• `run` - Variable Expansion

  
  

  Reference and expand variables already on your machine for use in your .env file.

  # .env
  USERNAME="username"
  DATABASE_URL="postgres://${USERNAME}@localhost/my_database"

  // index.js
  console.log('DATABASE_URL', process.env.DATABASE_URL)

  $ dotenvx run --debug -- node index.js
  [dotenvx] injecting env (2) from .env
  DATABASE_URL postgres://username@localhost/my_database

• `run` - Command Substitution

  
  

  Add the output of a command to one of your variables in your .env file.

  # .env
  DATABASE_URL="postgres://$(whoami)@localhost/my_database"

  // index.js
  console.log('DATABASE_URL', process.env.DATABASE_URL)

  $ dotenvx run --debug -- node index.js
  [dotenvx] injecting env (1) from .env
  DATABASE_URL postgres://yourusername@localhost/my_database

• `run` - Shell Expansion

  
  

  Prevent your shell from expanding inline $VARIABLES before dotenvx has a chance to inject it. Use a subshell.

  $ dotenvx run --env="HELLO=World" -- sh -c 'echo Hello $HELLO'
  Hello World

• `run` - multiple `-f` flags

  
  

  Compose multiple .env files for environment variables loading, as you need.

  $ echo "HELLO=local" > .env.local
  $ echo "HELLO=World" > .env
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -f .env.local -f .env -- node index.js
  [dotenvx] injecting env (1) from .env.local, .env
  Hello local

• `run --env HELLO=String`

  
  

  Set environment variables as a simple KEY=value string pair.

  $ echo "HELLO=World" > .env
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run --env HELLO=String -f .env -- node index.js
  [dotenvx] injecting env (1) from .env, and --env flag
  Hello String

• `run --overload`

  
  

  Override existing env variables. These can be variables already on your machine or variables loaded as files consecutively. The last variable seen will 'win'.

  $ echo "HELLO=local" > .env.local
  $ echo "HELLO=World" > .env
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -f .env.local -f .env --overload -- node index.js
  [dotenvx] injecting env (1) from .env.local, .env
  Hello World

• `DOTENV_PRIVATE_KEY=key run`

  
  

  Decrypt your encrypted .env by setting DOTENV_PRIVATE_KEY before dotenvx run.

  $ touch .env
  $ dotenvx set HELLO encrypted --encrypt
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  # check your .env.keys files for your privateKey
  $ DOTENV_PRIVATE_KEY="122...0b8" dotenvx run -- node index.js
  [dotenvx] injecting env (2) from .env
  Hello encrypted

• `DOTENV_PRIVATE_KEY_PRODUCTION=key run`

  
  

  Decrypt your encrypted .env.production by setting DOTENV_PRIVATE_KEY_PRODUCTION before dotenvx run. Alternatively, this can be already set on your server or cloud provider.

  $ touch .env.production
  $ dotenvx set HELLO "production encrypted" -f .env.production --encrypt
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  # check .env.keys for your privateKey
  $ DOTENV_PRIVATE_KEY_PRODUCTION="122...0b8" dotenvx run -- node index.js
  [dotenvx] injecting env (2) from .env.production
  Hello production encrypted

  Note the DOTENV_PRIVATE_KEY_PRODUCTION ends with _PRODUCTION. This instructs dotenvx run to load the .env.production file.

• `DOTENV_PRIVATE_KEY_CI=key dotenvx run`

  
  

  Decrypt your encrypted .env.ci by setting DOTENV_PRIVATE_KEY_CI before dotenvx run. Alternatively, this can be already set on your server or cloud provider.

  $ touch .env.ci
  $ dotenvx set HELLO "ci encrypted" -f .env.production --encrypt
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  # check .env.keys for your privateKey
  $ DOTENV_PRIVATE_KEY_CI="122...0b8" dotenvx run -- node index.js
  [dotenvx] injecting env (2) from .env.ci
  Hello ci encrypted

  Note the DOTENV_PRIVATE_KEY_CI ends with _CI. This instructs dotenvx run to load the .env.ci file. See the pattern?

• `DOTENV_PRIVATE_KEY=key DOTENV_PRIVATE_KEY_PRODUCTION=key run` - Combine Multiple

  
  

  Decrypt your encrypted .env and .env.production files by setting DOTENV_PRIVATE_KEY and DOTENV_PRIVATE_KEY_PRODUCTION before dotenvx run.

  $ touch .env
  $ touch .env.production
  $ dotenvx set HELLO encrypted --encrypt
  $ dotenvx set HELLO "production encrypted" -f .env.production --encrypt
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  # check .env.keys for your privateKeys
  $ DOTENV_PRIVATE_KEY="122...0b8" DOTENV_PRIVATE_KEY_PRODUCTION="122...0b8" dotenvx run -- node index.js
  [dotenvx] injecting env (3) from .env, .env.production
  Hello encrypted
  
  $ DOTENV_PRIVATE_KEY_PRODUCTION="122...0b8" DOTENV_PRIVATE_KEY="122...0b8" dotenvx run -- node index.js
  [dotenvx] injecting env (3) from .env.production, .env
  Hello production encrypted

  Compose any encrypted files you want this way. As long as a DOTENV_PRIVATE_KEY_${environment} is set, the values from .env.${environment} will be decrypted at runtime.

• `run --verbose`

  
  

  Set log level to verbose. (log levels)

  $ echo "HELLO=production" > .env.production
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -f .env.production --verbose -- node index.js
  loading env from .env.production (/path/to/.env.production)
  HELLO set
  [dotenvx] injecting env (1) from .env.production
  Hello production

• `run --debug`

  
  

  Set log level to debug. (log levels)

  $ echo "HELLO=production" > .env.production
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -f .env.production --debug -- node index.js
  process command [node index.js]
  options: {"env":[],"envFile":[".env.production"]}
  loading env from .env.production (/path/to/.env.production)
  {"HELLO":"production"}
  HELLO set
  HELLO set to production
  [dotenvx] injecting env (1) from .env.production
  executing process command [node index.js]
  expanding process command to [/opt/homebrew/bin/node index.js]
  Hello production

• `run --quiet`

  
  

  Use --quiet to suppress all output (except errors). (log levels)

  $ echo "HELLO=production" > .env.production
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -f .env.production --quiet -- node index.js
  Hello production

• `run --log-level`

  
  

  Set --log-level to whatever you wish. For example, to supress warnings (risky), set log level to error:

  $ echo "HELLO=production" > .env.production
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run -f .env.production --log-level=error -- node index.js
  Hello production

  Available log levels are error, warn, info, verbose, debug, silly (source)

• `run --convention=nextjs`

  
  

  Load envs using Next.js' convention. Set --convention to nextjs:

  $ echo "HELLO=development local" > .env.development.local
  $ echo "HELLO=local" > .env.local
  $ echo "HELLO=development" > .env.development
  $ echo "HELLO=env" > .env
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx run --convention=nextjs -- node index.js
  [dotenvx] injecting env (1) from .env.development.local, .env.local, .env.development, .env
  Hello development local

  (more conventions available upon request)

• `get KEY`

  
  

  Return a single environment variable's value.

  $ echo "HELLO=World" > .env
  
  $ dotenvx get HELLO
  World

• `get KEY -f`

  
  

  Return a single environment variable's value from a specific .env file.

  $ echo "HELLO=World" > .env
  $ echo "HELLO=production" > .env.production
  
  $ dotenvx get HELLO -f .env.production
  production

• `get KEY --env`

  
  

  Return a single environment variable's value from a --env string.

  $ dotenvx get HELLO --env HELLO=String -f .env.production
  String

• `get KEY --overload`

  
  

  Return a single environment variable's value where each found value is overloaded.

  $ echo "HELLO=World" > .env
  $ echo "HELLO=production" > .env.production
  
  $ dotenvx get HELLO -f .env.production --env HELLO=String -f .env --overload
  World

• `get KEY --convention=nextjs`

  
  

  Return a single environment variable's value using Next.js' convention. Set --convention to nextjs:

  $ echo "HELLO=development local" > .env.development.local
  $ echo "HELLO=local" > .env.local
  $ echo "HELLO=development" > .env.development
  $ echo "HELLO=env" > .env
  $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
  $ dotenvx get HELLO --convention=nextjs
  development local

• `get` (json)

  
  

  Return a json response of all key/value pairs in a .env file.

  $ echo "HELLO=World" > .env
  
  $ dotenvx get
  {"HELLO":"World"}

• `get --all`

  
  

  Return preset machine envs as well.

  $ echo "HELLO=World" > .env
  
  $ dotenvx get --all
  {"PWD":"/some/file/path","USER":"username","LIBRARY_PATH":"/usr/local/lib", ..., "HELLO":"World"}

• `get --all --pretty-print`

  
  

  Make the output more readable - pretty print it.

  $ echo "HELLO=World" > .env
  
  $ dotenvx get --all --pretty-print
  {
    "PWD": "/some/filepath",
    "USER": "username",
    "LIBRARY_PATH": "/usr/local/lib",
    ...,
    "HELLO": "World"
  }

• `set KEY value`

  
  

  Set a single key/value.

  $ touch .env
  
  $ dotenvx set HELLO World
  set HELLO (.env)

• `set KEY value --encrypt`

  
  

  Set an encrypted key/value.

  $ touch .env
  
  $ dotenvx set HELLO World --encrypt
  set HELLO with encryption (.env)

• `set KEY value -f`

  
  

  Set an (encrypted) key/value for another .env file.

  $ touch .env.production
  
  $ dotenvx set HELLO production --encrypt -f .env.production
  set HELLO with encryption (.env.production)

• `set KEY "value with spaces"`

  
  

  Set a value containing spaces.

  $ touch .env.ci
  
  $ dotenvx set HELLO "my ci" -f .env.ci
  set HELLO (.env.ci)

• `convert`

  
  

  Convert a .env file to an encrypted .env file.

  $ echo "HELLO=World" > .env
  
  $ dotenvx convert
  ✔ encrypted (.env)
  ✔ key added to .env.keys (DOTENV_PRIVATE_KEY)
  ℹ add .env.keys to .gitignore: [echo ".env.keys" >> .gitignore]
  ℹ run [DOTENV_PRIVATE_KEY='122...0b8' dotenvx run -- yourcommand] to test decryption locally

• `convert -f`

  
  

  Convert a specified .env file to an encrypted .env file.

  $ echo "HELLO=World" > .env
  $ echo "HELLO=Production" > .env.production
  
  $ dotenvx convert -f .env.production
  ✔ encrypted (.env.production)
  ✔ key added to .env.keys (DOTENV_PRIVATE_KEY_PRODUCTION)
  ℹ add .env.keys to .gitignore: [echo ".env.keys" >> .gitignore]
  ℹ run [DOTENV_PRIVATE_KEY_PRODUCTION='bff..bc4' dotenvx run -- yourcommand] to test decryption locally

• `ls`

  
  

  Print all .env files in a tree structure.

  $ touch .env
  $ touch .env.production
  $ mkdir -p apps/backend
  $ touch apps/backend/.env
  
  $ dotenvx ls
  ├─ .env.production
  ├─ .env
  └─ apps
     └─ backend
        └─ .env

• `ls directory`

  
  

  Print all .env files inside a specified path to a directory.

  $ touch .env
  $ touch .env.production
  $ mkdir -p apps/backend
  $ touch apps/backend/.env
  
  $ dotenvx ls apps/backend
  └─ .env

• `ls -f`

  
  

  Glob .env filenames matching a wildcard.

  $ touch .env
  $ touch .env.production
  $ mkdir -p apps/backend
  $ touch apps/backend/.env
  $ touch apps/backend/.env.prod
  
  $ dotenvx ls -f **/.env.prod*
  ├─ .env.production
  └─ apps
     └─ backend
        └─ .env.prod

• `genexample`

  
  

  In one command, generate a .env.example file from your current .env file contents.

  $ echo "HELLO=World" > .env
  
  $ dotenvx genexample
  ✔ updated .env.example (1)

  # .env.example
  HELLO=""

• `genexample -f`

  
  

  Pass multiple .env files to generate your .env.example file from the combination of their contents.

  $ echo "HELLO=World" > .env
  $ echo "DB_HOST=example.com" > .env.production
  
  $ dotenvx genexample -f .env -f .env.production
  ✔ updated .env.example (2)

  # .env.example
  HELLO=""
  DB_HOST=""

• `genexample directory`

  
  

  Generate a .env.example file inside the specified directory. Useful for monorepos.

  $ echo "HELLO=World" > .env
  $ mkdir -p apps/backend
  $ echo "HELLO=Backend" > apps/backend/.env
  
  $ dotenvx genexample apps/backend
  ✔ updated .env.example (1)

  # apps/backend/.env.example
  HELLO=""

• `gitignore`

  
  

  Gitignore your .env files.

  $ dotenvx gitignore
  creating .gitignore
  appending .env* to .gitignore
  done

• `precommit`

  
  

  Prevent .env files from being committed to code.

  $ dotenvx precommit
  [dotenvx][precommit] success

• `precommit --install`

  
  

  Install a shell script to .git/hooks/pre-commit to prevent accidentally committing any .env files to source control.

  $ dotenvx precommit --install
  [dotenvx][precommit] dotenvx precommit installed [.git/hooks/pre-commit]

• `prebuild`

  
  

  Prevent .env files from being built into your docker containers.

  Add it to your Dockerfile.

  RUN curl -fsS https://dotenvx.sh/ | sh
  
  ...
  
  RUN dotenvx prebuild
  CMD ["dotenvx", "run", "--", "node", "index.js"]

• `scan`

  
  

  Use gitleaks under the hood to scan for possible secrets in your code.

  $ dotenvx scan
  
      ○
      │╲
      │ ○
      ○ ░
      ░    gitleaks
  
  100 commits scanned.
  no leaks found

• `help`

  
  

  Output help for dotenvx.

  $ dotenvx help
  Usage: @dotenvx/dotenvx [options] [command]
  
  a better 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 [options]                     inject env at runtime [dotenvx run -- yourcommand]
    get [options] [key]               return a single environment variable
    set [options] <KEY> <value>       set a single environment variable
    ...
    help [command]                    display help for command

  You can get more detailed help per command with dotenvx help COMMAND.

  $ 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=World") (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=World" > .env
    $ echo "console.log('Hello ' + process.env.HELLO)" > index.js
  
    $ dotenvx run -- node index.js
    [dotenvx] injecting env (1) from .env
    Hello World

• `--version`

  
  

  Check current version of dotenvx.

  $ dotenvx --version
  X.X.X

• quickstart guides
  • run anywhere
  • multi-environment
  • encrypted envs
• dotenvx/docs
  • languages
  • frameworks
  • platforms
  • ci/cd

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.

# from this:
./node_modules/.bin/dotenvx run --env-file .env -- yourcommand
# to this:
./node_modules/.bin/dotenvx run -f .env -- yourcommand

more context

I've decided we should sunset it as a technological solution to this.

The .env.vault file got us far, but it had limitations such as:

• Pull Requests - it was difficult to tell which key had been changed
• Security - there was no mechanism to give a teammate the ability to encrypt without also giving them the ability to decrypt. Sometimes you just want to let a contractor encrypt a new value, but you don't want them to know the rest of the secrets.
• Conceptual - it takes more mental energy to understand the .env.vault format. Encrypted values inside a .env file is easier to quickly grasp.
• Combining Multiple Files - there was simply no mechanism to do this well with the .env.vault file format.

That said, the .env.vault tooling will still stick around for at least 1 year under dotenvx vault parent command. I'm still using it in projects as are many thousands of other people.

Yes. Working on this soon.

You can fork this repo and create pull requests or if you have questions or feedback:

• github.com/dotenvx/dotenvx - bugs and discussions
• @dotenvx 𝕏 (DMs are open)