dotenvx

Quickstart ⚡️

Learn how dotenvx runs anywhere, support multiple environments, and adds encryption to your .env files.

Install

Install dotenvx.

# install with Homebrew and then use the dotenvx command
brew install dotenvx/brew/dotenvx
dotenvx help

Install the necessary web server libraries in the language of your choice.

npm install express --save

Create a simple Hello World program.

// index.js
const express = require('express')
const app = express()
const PORT = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send(`Hello ${process.env.HELLO || ''}`)
})

app.listen(PORT, () => {
  console.log(`Server running on port:${PORT}`)
})

Run it.

$ node index.js
Server running on port:3000
# http://localhost:3000
# Hello undefined

Run Anywhere

Run it with dotenvx run --.

$ dotenvx run -- node index.js
[[email protected]] missing .env file (.env)
[[email protected]] injecting env (0)
Server running on port:3000
# http://localhost:3000
# Hello undefined

dotenvx is more helpful than dotenv. It warns you of a missing .env file.

Create the .env file.

# .env
JELLO="World"

Run it again.

$ dotenvx run -- node index.js
[[email protected]] injecting env (1) from .env
Server running on port:3000
# http://localhost:3000
# Hello undefined

Hrm, still not saying Hello World. Pass the --debug flag to to see what's going wrong.

$ dotenvx run --debug -- node index.js
loading env from .env (.env)
{"JELLO":"World"}
JELLO set
JELLO set to World

# Oops, HELLO not JELLO ^^

It's easier to debug with dotenvx than dotenv.

Fix your .env file.

# .env
HELLO="World"

Run it one last time.

$ dotenvx run -- node index.js
[[email protected]] injecting env (1) from .env
Server running on port:3000
# http://localhost:3000
# Hello World

🎉 It worked!

Add Encryption

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

dotenvx set --encrypt

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

Look at your .env file.

.env

#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
#/            public-key encryption for .env files          /
#/       [how it works](https://dotenvx.com/encryption)     /
#/----------------------------------------------------------/
DOTENV_PUBLIC_KEY="03c13bb105c307db64cc4b433987f12694bf79231487f44459f63fe70905494913"

# .env
HELLO="encrypted:BGmkvtg+DtseC3xyeJ4ITAqxWWFsFEBxTABZNJjPoMrVVJjkeevmUK719kxqKdlNrsClsvHK2Qs1yfHXNJM6Q6d8QJ/MIRoC0GLlJQkvHVJbf/931FoAVYNit6ahNyCgOt3Y3y6s"

It's encrypted! Run your code again with dotenvx run --.

$ dotenvx run -- node index.js
[[email protected]] injecting env (2) from .env
Server running on port:3000
# http://localhost:3000
# Hello World

🎉 It worked, again! But how?

Look at your .env.keys file. It contains the private decryption key.

.env.keys

#/------------------!DOTENV_PRIVATE_KEYS!-------------------/
#/ private decryption keys. DO NOT commit to source control /
#/     [how it works](https://dotenvx.com/encryption)       /
#/----------------------------------------------------------/

# .env
DOTENV_PRIVATE_KEY="ece16b6649d3f3e3a60eb97384484902d65afc85083f3bb5162b0a35b78171fa"

The run command uses it to decrypt any encrypted values and inject them at runtime. Under the hood it uses the same public-key cryptography as Bitcoin.

This is a huge security improvement for .env files.