@dotenvx/dotenvx

a better dotenv–from the creator of dotenv.

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

 

Quickstart

brew install dotenvx/brew/dotenvx

• other ways to install

 

Run Anywhere

$ 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
> :-D

More examples

• Python 🐍

  
  

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

• PHP 🐘

  
  

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

• Ruby 💎

  
  

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

• Rust 🦀

  
  

  $ 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
  

• Frameworks ▲

  
  

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

• 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"]
  

• CI/CDs 🐙

  
  

  examples coming soon
  

• Platforms

  
  

  examples coming soon
  

• npx

  
  

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

• Git

  
  

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

 

Multiple Environments

Pass the --env-file flag (shorthand -f) to run any environment from a .env.environment file.

$ dotenvx run --env-file=.env.production -- node index.js
[dotenvx][INFO] Injecting 12 production environment variables into your application process

Combine multiple .env files if you like.

$ dotenvx run --env-file=.env.local --env-file=.env -- node index.js
[dotenvx][INFO] Injecting 12 local, 1 development environment variables into your application process

 

Encrypt Your Env Files

$ dotenvx encrypt

This will encrypt your .env file to a .env.vault file. Commit your .env.vault file safely to code. This will also generate a .env.keys file. Do NOT commit this file to code. Keep your .env.keys secret. 🤫

 

Usage

Guide

Begin by creating a simple 'hello world' program.

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

Run it.

$ node index.js
Hello undefined

Run it with dotenvx.

$ dotenvx run -- node index.js
[dotenvx@x.x.x][WARN] ENOENT: no such file or directory, open '/../../.env'
Hello undefined

It warns you when there is no .env file (pass the --quiet flag to suppress these warnings).

Create the .env file.

# env
JELLO="World"

Run it again.

$ dotenvx run -- node index.js
[dotenvx@x.x.x][INFO] Injecting 0 environment variables into your application process
Hello undefined

Hrm, still undefined. Pass the --debug flag to debug the issue. I'll give you a hint: 🍮

$ dotenvx run --debug -- node index.js
[dotenvx@x.x.x][VERBOSE] Loading env from /../../.env
[dotenvx@x.x.x][DEBUG] Reading env from /../../.env
[dotenvx@x.x.x][DEBUG] Parsing env from /../../.env
[dotenvx@x.x.x][DEBUG] {"JELLO":"World"}

# Oops, HELLO not JELLO ^^

Fix your .env file.

# .env
HELLO="World"

One last time. Le tired.

$ dotenvx run -- node index.js
[dotenvx@x.x.x][INFO] Injecting 1 environment variable into your application process
Hello World

🎉 It worked!

 

Install

Installing with brew is most straight forward:

brew install dotenvx/brew/dotenvx

Other Ways to Install

1. After brew, installing globally using npm is easiest:

npm install @dotenvx/dotenvx --global

1. Or use with npx:

npx @dotenvx/dotenvx help

1. Or install in your package.json

npm i @dotenvx/dotenvx --save

// package.json
"scripts": {
  "start": "./node_modules/.bin/dotenvx run -- nodex index.js"
}

1. Or download it directly as a standalone binary:

curl -fsS https://dotenvx.sh/ | sh

# download it to `./dotenvx`
curl -fsS https://dotenvx.sh/ | sh

# check it works
./dotenvx help

# move it to `/usr/local/bin/dotenvx`
sudo install -m 755 dotenvx /usr/local/bin

# check it still works
/usr/local/bin/dotenvx help

# check it is in your path
which dotenv
dotenvx help

Contributing

If you have questions or feedback:

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

Changelog

0.5.0

Added

run support for .env.vault files 🔑 (#2)