dotenv-vault

Sync .env files. Stop sharing them over insecure channels like Slack and email and never lose an important .env file again.

dotenv-vault extends the proven & trusted foundation of dotenv with syncing, multiple environments, and integration wherever you develop and deploy - all using a new standard .env.vault file.

Watch the 1 minute video

• Usage
• Multiple Environments
• Integrations
• How It Works
• Commands

Usage

Usage is similar to git. Run the command:

$ npx dotenv-vault new

Follow those instructions and then run:

$ npx dotenv-vault login

Then run push and pull:

$ npx dotenv-vault push
$ npx dotenv-vault pull

That's it! You synced your .env file.

Visit dotenv.org/docs for a complete getting started guide.

Multiple Environments

After you've pushed your .env file, you can manage your secrets across multiple environments. Open an environment to view and edit its environment variables.

$ npx dotenv-vault open production

Edit those values. Would you also like to pull your production .env to your machine? Run the command:

$ npx dotenv-vault pull production

Visit dotenv.org/docs/tutorials/environments to learn more.

Integrations

Dotenv Vault integrates everywhere you already deploy your code.

Run the build command to generate your encrypted .env.vault file, commit that safely to code, and deploy.

$ npx dotenv-vault build
$ git commit -am "Add .env.vault"
$ git push

There's nothing else like it. Node.JS, Ruby, and Python supported – more languages coming soon. Request a language

Vercel	Heroku	GitHub Actions	GitLab CI/CD
Netlify	Docker	Docker Compose	CircleCI
Serverless	Railway	Render	Travis CI
Google Cloud	Fly.io	Northflank	Buddy
Cloud66	Digital Ocean	Dagger	Bitbucket
Node.js	pnpm	Express	NextJS
Remix	Astro	Rails	Ruby
Sinatra	Flask	Python	Supabase
Pulumi	Angular	Nuxt	Vite
Slack	and more!

Visit tutorials/integrations to learn more.

How It Works

Below is a high level overview of how dotenv-vault works. You can also learn more at docs[docs] and security.

Step 1

npx dotenv-vault push

You run npx dotenv-vault push. Your request is started.

Step 2

Encrypted Connection

Your .env file is encrypted and sent securely over SSL to Dotenv's in-memory servers.

Step 3

Dotenv Servers

This encrypted payload is decrypted and briefly held in memory to complete the next steps. Afterward, the memory is flushed. Rest assured the decrypted version is never persisted to Dotenv systems.

Step 4

Parsing

Your .env file is parsed line by line - in memory.

Note: There are minor differences between dotenv parsers across various languages and frameworks. So far Dotenv Vault handles 100% of these, and we continue to add test cases to cover all edge cases.

Step 5

Secret Extraction

Each key/value pair (and any comments) are extracted - in memory.

Step 6

Secret Division

The secret is divided into its separate key and value. This is by design. They will be stored in separate databases for added security. This way if an attacker somehow gained access to one database they would not be able to make sense of the data - having only half the puzzle.

Step 7

AES-GCM Encryption

The KEY is encrypted. The VALUE is encrypted. They are encrypted with different master encryption keys. This way if an attacker somehow gained access to the VALUE decryption key they would find the data useless. They would not know if the secret belonged to Twilio or to AWS.

Encryption uses the AES-GCM algorithm. It is:

• well-studied
• NIST recommended
• an IETF standard
• fast thanks to a dedicated instruction set

Additionally, all master encryption keys are rotated on an unpublished schedule, further adding to the level of security.

Step 8

Tokenization

The encrypted VALUE is sent to Dotenv Vault for safe storage. A token is returned as an identifier. The token is used in the next step for mapping the KEY to the VALUE for later secure-read operations.

Multiple security measures go into the Vault. They include but are not limited to:

• Separate datastore from the application database
• Not accessible via the internet and all external connections are prevented
• Encrypted clients are required and these clients have to go through the application - which has its own additional layers of encryption
• There are stricter TLS requirements for connecting to the Vault. TLS 1.0 cannot be used to connect.
• The secrets stored in the Vault are not just encrypted at the datastore level. They are also encrypted at each datastore entry as you saw in the prior step(s).

Step 9

Store Key Part with Token

Lastly, the encrypted KEY and token (representing the encrypted VALUE) are placed in an envelope and stored together in the application database.

Step 10

Success 201

A success message is returned to the developer.

Learn more at dotenv.org/security

Commands

Below are a list of dotenv-vault cli commands. You can also learn more on the docs page.

• new
• login
• logout
• push
• pull
• open
• whoami
• build
• keys
• rotatekey
• decrypt
• versions

new

Create your project at Dotenv Vault.

Example:

$ npx dotenv-vault new

ARGUMENTS

[DOTENV_VAULT]

Set .env.vault identifier. Defaults to generated value.

$ npx dotenv-vault new vlt_6beaae5…
local:    Adding .env.vault (DOTENV_VAULT)... done
local:    Added to .env.vault (DOTENV_VAULT=vlt_6beaa...)

FLAGS

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

---

login

Log in to dotenv-vault.

Example:

$ npx dotenv-vault login

ARGUMENTS

[DOTENV_ME]

Set .env.me identifier. Defaults to generated value.

$ npx dotenv-vault login me_00c7fa…

FLAGS

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault login -y

---

logout

Log out of dotenv-vault.

Example:

$ npx dotenv-vault logout

FLAGS

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault logout -y

---

push

Push .env securely.

Example:

$ npx dotenv-vault push

ARGUMENTS

[ENVIRONMENT]

Set environment to push to. Defaults to development

$ npx dotenv-vault push production

[FILENAME]

Set input filename. Defaults to .env for development and .env.{environment} for other environments

$ npx dotenv-vault push production .env.production

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault push --dotenvMe=me_b1831e…

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault push -y

---

pull

Pull .env securely.

Example:

$ npx dotenv-vault pull

ARGUMENTS

[ENVIRONMENT]

Set environment to pull from. Defaults to development

$ npx dotenv-vault pull production

[FILENAME]

Set output filename. Defaults to .env for development and .env.{environment} for other environments

$ npx dotenv-vault pull production .env.production

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault pull --dotenvMe=me_b1831e…

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault pull -y

If you want to pull a specific version you can do so. For example,

npx dotenv-vault pull development@v14

---

open

Open project page.

Example:

$ npx dotenv-vault open

ARGUMENTS

[ENVIRONMENT]

Set environment to open to. Defaults to development.

$ npx dotenv-vault open production

FLAGS

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault open -y

---

whoami

Display the current logged in user.

Example:

$ npx dotenv-vault whoami

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault whoami dotenvMe=me_b1831e…

---

build

Build .env.vault file.

Example:

$ npx dotenv-vault build

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault build dotenvMe=me_b1831e…

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault build -y

---

keys

List .env.vault decryption keys.

Example:

$ npx dotenv-vault keys

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault keys dotenvMe=me_b1831e…

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault keys -y

---

rotatekey

Rotate DOTENV_KEY.

Example:

$ npx dotenv-vault rotatekey production

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault rotatekey dotenvMe=me_b1831e…

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault rotatekey -y

---

decrypt

Decrypt .env.vault locally.

Example:

$ npx dotenv-vault decrypt dotenv://:[email protected]/vault/.env.vault?environment=development

ARGUMENTS

[DOTENV_KEY]

Set DOTENV_KEY to decrypt .env.vault. Development key will decrypt development, production will decrypt production, and so on.

$ npx dotenv-vault decrypt dotenv://:[email protected]/vault/.env.vault?environment=development

---

versions

List version history.

Example:

$ npx dotenv-vault versions

ARGUMENTS

[ENVIRONMENT]

Set environment to check versions against. Defaults to development.

$ npx dotenv-vault versions production

FLAGS

-m, --dotenvMe

Pass .env.me (DOTENV_ME) credential directly (rather than reading from .env.me file)

$ npx dotenv-vault versions dotenvMe=me_b1831e…

-y, --yes

Automatic yes to prompts. Assume yes to all prompts and run non-interactively.

$ npx dotenv-vault versions -y

If you want to pull a specific version you can do so. For example,

npx dotenv-vault pull development@v14

Health

Visit health.dotenv.org for more information.

Contributing

See CONTRIBUTING.md

Changelog

See CHANGELOG.md

License

MIT