# Sync .env filesβ€”from the creator of `dotenv`. ![dotenv.org](https://camo.githubusercontent.com/d7e7cf2efaac9771ba254c1df4b16f8318c92bf92bec8a0bdb979d711831ee95/68747470733a2f2f646f74656e762e6f72672f62616e6e65722e706e67 align="center") `dotenv-vault` is a cli to *sync .env files across machines, environments, and team members*. ## 🌱 Install It works with a single command. Run `npx dotenv-vault@latest push`. ```basic npx dotenv-vault@latest push ``` ```basic remote: Securely pushing (.env)... done remote: Securely pushed development (.env) remote: Securely built vault (.env.vault) ``` That's it. You securely synced your `.env` file. Next, tell your teammate to run `npx dotenv-vault@latest pull` ```basic npx dotenv-vault@latest pull ``` Nice! See further [usage](https://github.com/dotenv-org/dotenv-vault#%EF%B8%8F-usage) and [commands](https://github.com/dotenv-org/dotenv-vault#-commands). --- #### Other Ways to Install Don't want to use [npx](https://docs.npmjs.com/cli/v7/commands/npx)? Install a number of other ways. Install via [Homebrew](https://github.com/dotenv-org/homebrew-brew) ```basic $ brew install dotenv-org/brew/dotenv-vault $ dotenv-vault help ``` [![windows icon](https://camo.githubusercontent.com/9df9fe270a0f5e5f0ecdae49239f671757dc098635958a3fb69bdebed7fcfbd0/68747470733a2f2f6170692e69636f6e6966792e64657369676e2f6d64692f77696e646f77732e737667 align="center")](https://camo.githubusercontent.com/9df9fe270a0f5e5f0ecdae49239f671757dc098635958a3fb69bdebed7fcfbd0/68747470733a2f2f6170692e69636f6e6966792e64657369676e2f6d64692f77696e646f77732e737667) Install on [Windows](https://dotenv-vault-assets.dotenv.org/) * [32-bit installer](https://dotenv-vault-assets.dotenv.org/channels/stable/dotenv-vault-x86.exe) * [64-bit installer](https://dotenv-vault-assets.dotenv.org/channels/stable/dotenv-vault-x64.exe) Install and run commands via [Docker](https://hub.docker.com/r/dotenv/dotenv-vault) ```basic $ docker run -w $(pwd) -v $(pwd):$(pwd) -it dotenv/dotenv-vault help ``` [Learn more about installation](https://www.dotenv.org/install/) ## πŸ—οΈ Usage When you make a change to your `.env` file, push it up. ```basic $ npx dotenv-vault@latest push ``` Commit your `.env.vault` file safely to code. ```basic $ git add .env.vault $ git commit -am "Add .env.vault" $ git push ``` Now your teammate can pull the latest `.env` changes. ```basic $ git pull $ npx dotenv-vault@latest pull ``` That's it! [Learn more about usage](https://www.dotenv.org/docs/quickstart?r=1) ## πŸš€ Deploying Stop scattering your production secrets across multiple third-parties and tools. Instead, use an encrypted `.env.vault` file. Generate your encrypted `.env.vault` file. ```basic $ npx dotenv-vault@latest build ``` Fetch your production `DOTENV_KEY`. ```basic $ npx dotenv-vault@latest keys production remote: Listing .env.vault decryption keys... done dotenv://:key_1234…@dotenv.org/vault/.env.vault?environment=production ``` Set `DOTENV_KEY` on your server. ```basic # heroku example heroku config:set DOTENV_KEY=dotenv://:key_1234…@dotenv.org/vault/.env.vault?environment=production ``` Commit your `.env.vault` file safely to code and deploy. ```basic $ git add .env.vault $ git commit -am "Update .env.vault" $ git push $ git push heroku main # heroku example ``` That's it! On deploy, your `.env.vault` file will be decrypted and its secrets injected as environment variables – just in time. [Learn more about deploying](https://www.dotenv.org/docs/quickstart?r=1) ## 🌴 Manage Multiple Environments After you've pushed your `.env` file, dotenv-vault automatically sets up multiple environments. Manage multiple environments with the included UI. [learn more](https://github.com/dotenv-org/dotenv-vault/blob/master/docs/tutorials/environments) ```basic $ npx dotenv-vault@latest open production ``` That's it! Manage your ci, staging, and production secrets from there. Would you also like to pull your production `.env` to your machine? Run the command: ```basic $ npx dotenv-vault@latest pull production ``` ℹ️ **πŸ” Vault Managed vs πŸ’» Locally Managed**: The above example, for brevity's sake, used the πŸ” Vault Managed solution to manage your `.env.vault` file. You can instead use the πŸ’» Locally Managed solution. [See the faq further below](https://github.com/dotenv-org/dotenv-vault#how-do-i-use--locally-managed-dotenv-vault). Our vision is that other platforms and orchestration tools adopt the `.env.vault` standard as they did the `.env` standard. We don't expect to be the only ones providing tooling to manage and generate `.env.vault` files. [Learn more about environments](https://www.dotenv.org/docs/tutorials/environments?r=1) ## πŸ“š Examples

Vercel

Heroku

GitHub Actions

GitLab CI/CD

Netlify

Docker

Docker Compose

CircleCI

Serverless

Railway

Render

Travis CI

Google Cloud

Fly.io

Slack

Buddy

Cloud66

Digital Ocean

Dagger

Bitbucket

Node.js

Express

NextJS

Remix

Astro

Rails

Ruby

Sinatra

Flask

Python

Supabase

Pulumi

Angular

Nuxt

Vite

[See more integration guides](https://www.dotenv.org/docs/) ## πŸ“– Commands ```basic $ npx dotenv-vault@latest help ``` * [new](https://github.com/dotenv-org/dotenv-vault#new) * [login](https://github.com/dotenv-org/dotenv-vault#login) * [logout](https://github.com/dotenv-org/dotenv-vault#logout) * [push](https://github.com/dotenv-org/dotenv-vault#push) * [pull](https://github.com/dotenv-org/dotenv-vault#pull) * [open](https://github.com/dotenv-org/dotenv-vault#open) * [whoami](https://github.com/dotenv-org/dotenv-vault#whoami) * [build](https://github.com/dotenv-org/dotenv-vault#build) * [keys](https://github.com/dotenv-org/dotenv-vault#keys) * [rotatekey](https://github.com/dotenv-org/dotenv-vault#rotatekey) * [decrypt](https://github.com/dotenv-org/dotenv-vault#decrypt) * [versions](https://github.com/dotenv-org/dotenv-vault#versions) * [local](https://github.com/dotenv-org/dotenv-vault#local-build) * [local build](https://github.com/dotenv-org/dotenv-vault#local-build) * [local decrypt](https://github.com/dotenv-org/dotenv-vault#local-decrypt) * [local keys](https://github.com/dotenv-org/dotenv-vault#local-keys) ### `new` Create your project at Dotenv Vault. Example: ```basic $ npx dotenv-vault@latest new ``` ##### ARGUMENTS *\[DOTENV\_VAULT\]* Set .env.vault identifier. Defaults to generated value. ```basic $ npx dotenv-vault@latest 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: ```basic $ npx dotenv-vault@latest login ``` ##### ARGUMENTS *\[DOTENV\_ME\]* Set .env.me identifier. Defaults to generated value. ```basic $ npx dotenv-vault@latest login me_00c7fa… ``` ##### FLAGS *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest login -y ``` --- ### `logout` Log out of dotenv-vault. Example: ```basic $ npx dotenv-vault@latest logout ``` ##### FLAGS *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest logout -y ``` --- ### `push` Push `.env` securely. Example: ```basic $ npx dotenv-vault@latest push ``` ##### ARGUMENTS *\[ENVIRONMENT\]* Set environment to push to. Defaults to development ```basic $ npx dotenv-vault@latest push production ``` *\[FILENAME\]* Set input filename. Defaults to .env for development and .env.{environment} for other environments ```basic $ npx dotenv-vault@latest push production .env.production ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest push --dotenvMe=me_b1831e… ``` *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest push -y ``` --- ### `pull` Pull `.env` securely. Example: ```basic $ npx dotenv-vault@latest pull ``` ##### ARGUMENTS *\[ENVIRONMENT\]* Set environment to pull from. Defaults to development ```basic $ npx dotenv-vault@latest pull production ``` *\[FILENAME\]* Set output filename. Defaults to .env for development and .env.{environment} for other environments ```basic $ npx dotenv-vault@latest pull production .env.production ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest pull --dotenvMe=me_b1831e… ``` *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest pull -y ``` If you want to pull a specific version you can do so. For example, ```basic npx dotenv-vault@latest pull development@v14 ``` --- ### `open` Open project page. Example: ```basic $ npx dotenv-vault@latest open ``` ##### ARGUMENTS *\[ENVIRONMENT\]* Set environment to open to. Defaults to development. ```basic $ npx dotenv-vault@latest open production ``` ##### FLAGS *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest open -y ``` --- ### `whoami` Display the current logged in user. Example: ```basic $ npx dotenv-vault@latest whoami ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest whoami dotenvMe=me_b1831e… ``` --- ### `build` Build .env.vault file. Example: ```basic $ npx dotenv-vault@latest build ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest build dotenvMe=me_b1831e… ``` *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest build -y ``` --- ### `keys` List .env.vault decryption keys. Example: ```basic $ npx dotenv-vault@latest keys ``` ##### ARGUMENTS *\[ENVIRONMENT\]* Set environment. Defaults to all. ```basic $ npx dotenv-vault@latest keys production… remote: Listing .env.vault decryption keys... done dotenv://:key_899..@dotenv.org/vault/.env.vault?environment=production ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest keys dotenvMe=me_b1831e… ``` *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest keys -y ``` --- ### `rotatekey` Rotate DOTENV\_KEY. Example: ```basic $ npx dotenv-vault@latest rotatekey production ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest rotatekey dotenvMe=me_b1831e… ``` *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest rotatekey -y ``` --- ### `decrypt` Decrypt .env.vault locally. Example: ```basic $ npx dotenv-vault@latest decrypt dotenv://:key_1234@dotenv.org/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. ```basic $ npx dotenv-vault@latest decrypt dotenv://:key_1234@dotenv.org/vault/.env.vault?environment=development ``` --- ### `versions` List version history. Example: ```basic $ npx dotenv-vault@latest versions ``` ##### ARGUMENTS *\[ENVIRONMENT\]* Set environment to check versions against. Defaults to development. ```basic $ npx dotenv-vault@latest versions production ``` ##### FLAGS *\-m, --dotenvMe* Pass .env.me (DOTENV\_ME) credential directly (rather than reading from .env.me file) ```basic $ npx dotenv-vault@latest versions dotenvMe=me_b1831e… ``` *\-y, --yes* Automatic yes to prompts. Assume yes to all prompts and run non-interactively. ```basic $ npx dotenv-vault@latest versions -y ``` If you want to pull a specific version you can do so. For example, ```basic npx dotenv-vault@latest pull development@v14 ``` --- ### `local build` Build .env.vault from local only Example: ```basic $ npx dotenv-vault@latest local build ``` This will encrypt the contents of your `.env` file and any `.env.ENVIRONMENT` files you have locally into your `.env.vault` file. ### `local decrypt` Decrypt .env.vault from local only Example: ```basic $ npx dotenv-vault@latest local decrypt dotenv://:key_1234@dotenv.local/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. ```basic $ npx dotenv-vault@latest local decrypt dotenv://:key_1234@dotenv.local/vault/.env.vault?environment=development ``` ### `local keys` List .env.vault local decryption keys from .env.keys file Example: ```basic $ npx dotenv-vault@latest local keys local: Listing .env.vault decryption keys from .env.keys... done environment DOTENV_KEY ─────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────── develompent dotenv://:key_33ee..@dotenv.local/vault/.env.va… production dotenv://:key_7038..@dotenv.local/vault/.env.va… ``` ##### ARGUMENTS *\[ENVIRONMENT\]* Set `ENVIRONMENT` to output a single environment's DOTENV\_KEY. ```basic $ npx dotenv-vault@latest local keys development… local: Listing .env.vault decryption keys from .env.keys... done dotenv://:key_a682c..@dotenv.local/vault/.env.vault?environment=development ``` ## ❓ FAQ ### Why is the `.env.vault` file not decrypting my environment variables successfully? First, make sure you are using `dotenv@16.1.0` or greater. (If you are using a different language make sure you have installed one of its [libraries](https://github.com/dotenv-org/dotenv-vault#what-languages-does-this-work-with).) Second, test decryption is working locally. ```basic $ npx dotenv-vault@latest decrypt dotenv://:key_1234..@dotenv.local/vault/.env.vault?environment=production # outputs environment variables ``` Third, test decryption on boot is working locally. ```basic $ DOTENV_KEY='dotenv://:key_1234..@dotenv.local/vault/.env.vault?environment=production' npm start # boots your app with production envs ``` ### Should I commit my `.env.vault` file? Yes. It is safe and recommended to do so. DO commit your `.env.vault` file to code. DO NOT commit your `.env` file. The `.env.vault` file contains ciphertext generated using AES-256. AES-256 is trusted by the US Government to transmit top-secret information and has a brute-force timescale of about a billion years. ### I accidentally leaked my `DOTENV_KEY`, what can I do? Does that attacker also have access to your `.env.vault` file? * No: good, the attacker cannot do any damage. They need both the `DOTENV_KEY` and `.env.vault` file to access your secrets. This extra layer of security sets the `.env.vault` file apart as a superior solution to other SecretOps solutions. * Yes: IMMEDIATELY start rotating your secrets at your third-party API providers. This scenario would be the same no matter what SecretOps solution you use. After completing the above, rotate your `DOTENV_KEY` using the [rotatekey](https://github.com/dotenv-org/dotenv-vault#rotatekey) command, rebuild your `.env.vault` file, and redeploy. ### Is it safe to store my secrets with dotenv-vault? It safer than scattering your secrets across multiple cloud providers. Those providers are focused on code deployment and server performance over secrets security.\[1\] Dotenv Vault's singular focus is secrets security, and as a result we go to great lengths to make sure your secrets are safe. Afterall, we keep our secrets here too.\[2\] * [\[1\] CircleCI Breach](https://techcrunch.com/2023/01/05/circleci-breach/) * [\[2\] Security at Dotenv Vault](https://www.dotenv.org/security) ### What languages does this work with? The `.env.vault` file and its encryption algorithm is language-agnostic so technically it works with any language. We've built convenience libraries for it in a handful of languages and are adding more quickly. * [Go](https://github.com/dotenv-org/godotenvvault) * [Kotlin](https://github.com/dotenv-org/dotenv-vault-kotlin) * [NodeJS](https://github.com/motdotla/dotenv) * [PHP](https://github.com/dotenv-org/phpdotenv-vault) * [Python](https://github.com/dotenv-org/python-dotenv-vault) * [Ruby](https://github.com/dotenv-org/dotenv-vault-ruby) ### How do I use πŸ’» Locally Managed dotenv-vault? There are a series of **πŸ’» Locally Managed** commands available to you. Locally managed never makes a remote API call. It is completely managed on your machine. **πŸ” Vault Managed** adds conveniences like backing up your .env file, secure sharing across your team, access permissions, and version history. **πŸ’» Locally Managed** is a good choice for someone who would prefer to handle this coordination themselves and does not want to trust Dotenv Vault with their secrets. Here's how it works. Generate your `.env.vault` file. ```basic $ npx dotenv-vault@latest local build ``` This creates two files: * `.env.vault` - encrypted contents of .env\* file(s) * `.env.keys` - decryption key(s) Boot using `.env.vault`. ```basic $ DOTENV_KEY= npm start [dotenv@16.1.0][INFO] Loading env from encrypted .env.vault ``` Great! Next, set the `DOTENV_KEY` on your server. For example in heroku: ```basic $ heroku config:set DOTENV_KEY= ``` Commit your `.env.vault` file safely to code and deploy. Your `.env.vault` is decrypted on boot, its environment variables injected, and your app works as expected. Congratulations, your secrets are now much safer than scattered across multiple servers and cloud providers!