dotenv-vault
Dotenv Vault securely syncs secrets and app configuration across your machines, environments, and team members. Stop sharing .env files over insecure channels like Slack and email - from the same people that pioneered dotenv.
Works With
Works with any dotenv library and integrates into most infrastructure (and growing).
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Usage
Usage is easy! 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!
Read our security statement.
npx dotenv-vault@latest push
. (otherwise, npx caches the first version it encounters on your machine)
How It Works
Dotenv Vault holds your secrets in a secure and sophisticated way. Learn more
- Step 1 You run
npx dotenv-vault push
. The request is started. - Step 2 The .env file is encrypted and sent securely over SSL to Dotenv's in-memory servers.
- Step 3 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 peristed to Dotenv systems.
- Step 4 The .env file is parsed line by line - in memory. Note: There are some differences between dotenv parsers across various languages and frameworks. So far Dotenv Vault handles these 100%, and we continue to add test cases to cover all edge cases.
- Step 5 Each key/value pair (and any comments) are extracted - in memory.
- Step 6 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 of the puzzle.
- Step 7 The
KEY
is encrypted. TheVALUE
is encrypted. They are encrypted with different master encryption keys. This way if an attacker somehow gained access to theVALUE
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 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 theKEY
to theVALUE
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 Lastly, the encrypted
KEY
and token (representing the encryptedVALUE
) are placed in an envelope and stored together in the application database. - Step 10 success message is returned to the user.
Commands
dotenv-vault new [dotenvVault]
Create your project at Dotenv Vault.
Example:
$ dotenv-vault new
Arguments
[dotenvVault]
Set .env.vault identifier. Defaults to generated value.
Example:
$ dotenv-vault new vlt_a5ue8β¦
# set .env.vault project identifier to vlt_a5ue8β¦
Options
-y, --yes
Automatic yes to prompts. Assume yes to all prompts and run non-interactively.
Examples:
$ dotenv-vault new -y
# skips over prompt for permission to open browser window
dotenv-vault login [dotenvMe]
Authenticate your project at Dotenv Vault.
Example:
$ dotenv-vault login
Arguments
[dotenvMe]
Set .env.me credential. Defaults to generated value.
Example:
$ dotenv-vault login me_13b33β¦
# set .env.me credential to me_13b33β¦
Options
-y, --yes
Automatic yes to prompts. Assume yes to all prompts and run non-interactively.
Examples:
$ dotenv-vault login --yes
# skips over prompt for permission to open browser window
dotenv-vault push [environment] [filename]
Push your .env
file securely to Dotenv Vault
Example:
$ dotenv-vault push
# pushes local .env to remote development
Arguments
[environment]
Example:
$ dotenv-vault push staging
# pushes local .env.staging to remote staging environment
[filename]
Set input filename. Defaults to .env.
Example:
$ dotenv-vault push staging .env.stag
# pushes .env.stag to remote staging environment
Options
--dotenvMe
Directly pass your DOTENV_ME
value to the command line, instead of reading from a .env.me
file.
Examples:
$ dotenv-vault push development --dotenvMe=me_1234
# pushes local .env to remote development
-y, --yes
Automatic yes to prompts. Assume yes to all prompts and run non-interactively.
Examples:
$ dotenv-vault push --yes
# skips over prompt for permission to open browser window
dotenv-vault pull [environment] [filename]
Pulls your development|staging|ci|production environment(s) to your machine.
Example:
$ dotenv-vault pull
# pulls remote development envs to .env
Arguments
[environment]
Pull .env.ci, .env.staging, and .env.production
Example:
$ dotenv-vault pull staging
# pulls remote staging envs to .env.staging
[filename]
Set output filename. Defaults to .env for development and .env.{environment} for other environments. Exception: When using DOTENV_IT
tokens it defaults to .env
for all environments.
Example:
$ dotenv-vault pull production .env
# pulls remote production envs to .env
Options
--dotenvMe
Directly pass your DOTENV_ME
value to the command line, instead of reading from a .env.me
file.
Examples:
$ dotenv-vault pull staging --dotenvMe=me_1234
# pulls remote staging envs to .env.staging
$ dotenv-vault pull production .env --dotenvMe=me_1234
# pulls remote production envs to .env
-y, --yes
Automatic yes to prompts. Assume yes to all prompts and run non-interactively.
Examples:
$ dotenv-vault pull -y
# skips over prompt for permission to open browser window
dotenv-vault open
Open your project in the UI at Dotenv Vault.
Example:
$ dotenv-vault open
Options
-y, --yes
Automatic yes to prompts. Assume yes to all prompts and run non-interactively.
Examples:
$ dotenv-vault open -y
# skips over prompt for permission to open browser window
dotenv-vault whoami
Display the current logged in user
Example:
$ dotenv-vault whoami
Options
--dotenvMe
Directly pass your DOTENV_ME
value to the command line, instead of reading from a .env.me
file.
Examples:
$ dotenv-vault whoami --dotenvMe=me_1234
dotenv-vault help [command]
Display help for dotenv-vault commands.
USAGE
$ dotenv-vault help [command]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
Example:
$ dotenv-vault help push
Contributing Guide
See CONTRIBUTING.md
Development Guide
Fork and clone the repo. Use ./bin/dev
to run local development commands.
./bin/dev new
./bin/dev push
./bin/dev pull
# etc
If you need to send the request to a different vault url, modify your command(s) to the following.
NODE_TLS_REJECT_UNAUTHORIZED=0 DOTENV_API_URL=https://vault.dotenv.development ./bin/dev
Note that dotenv-vault uses oclif.
Testing
npm test
Tarballs
Publishing
Only for those with permission.
npm version patch
npm publish
Other notes.
npx oclif@3.0.1 pack tarballs
bash
env $(cat .env | xargs) npx oclif@3.0.1 upload tarballs
env $(cat .env | xargs) npx oclif@3.0.1 promote --version VERSION --sha SHA
CHANGELOG
See CHANGELOG.md