Learn the basics of dotenvx in just a few minutes.

  • run anywhere (cross-platform)
  • multiple environments
  • encrypted envs

Run Anywhere

Run it with dotenvx run -- yourcommand.

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

$ node index.js
Hello undefined

$ dotenvx run -- node index.js
Hello World

Multiple Environments

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
Hello production

Add Encryption

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

Add encryption

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

You encrypted HELLO.


#/            public-key encryption for .env files          /
#/       [how it works](     /

# .env.production

Run your code again.

$ dotenvx run -f .env.production -- node index.js
Hello production (encrypted)

It worked, again - this time with encryption. How? Look at your .env.keys file. It contains the private decryption key.


#/ private decryption keys. DO NOT commit to source control /
#/     [how it works](       /

# .env.production

Alternatively, preface dotenvx run -- with DOTENV_PRIVATE_KEY_PRODUCTION.

$ DOTENV_PRIVATE_KEY_PRODUCTION="bd7c50b352ce23973ec9db355d70212305a0baaade92f0165f02915b213bfbe2" dotenvx run -- node index.js
Hello production (encrypted)

dotenvx run is smart enough to introspect from either the DOTENV_PRIVATE_KEY_PRODUCTION environment variable or from the .env.keys file.

We recommend using the .env.keys when simulating production on your local machine. On your production server set the single DOTENV_PRIVATE_KEY_PRODUCTION value and all future deployments of your .env.production will be decrypted at runtime.

Do NOT commit your .env.keys file to code, but it is safe (and recommended) to commit your encrypted .env.production file to code.

Under the hood, this is all implemented using the same public-key cryptography as Bitcoin.

Enjoy safer .env files! 🎉