Quickstart

1. Sign in

   envi auth
   

   This opens your browser to approve the device — no password, ever. Prefer email codes instead? Use envi auth --email you@company.com.

2. Create a project and an environment

   envi project create acme-api
   envi origin create development --project acme-api
   

   A project needs at least one environment before a directory can be linked to it. The dashboard provisions a first one for you the moment you open a project; from the CLI you create it yourself.

3. Link your repo to it

   From the root of the repo you want to manage secrets for:

   envi init
   

   You'll be asked to pick one of your projects, then one of its environments. This writes an envi.toml linking the current directory to that pair — commit it, it holds no secrets, just IDs.

   envi init --project acme-api --env development skips both prompts.

4. Push your existing .env

   Already have a .env file here? Send it up:

   envi push
   

   Envi encrypts every value before it's stored. Pushing again later only succeeds if your local copy is still based on the latest remote revision.

5. Run your app without a .env

   Instead of writing secrets to disk at all, hand them straight to the process that needs them:

   envi run -- npm start
   

   The secrets exist in that process's environment and nowhere else. Nothing is written, so there is no file to leak, to forget, or to let go stale. envi run exits with your command's own exit status, so it drops into scripts and CI unchanged.

6. Pull it somewhere else

   On another machine, or a fresh clone:

   envi init
   envi pull
   

   pull writes the environment's current secrets straight to .env, at 0600 permissions.

Keeping things in sync

Two people editing the same environment is the normal case, not an edge case. Before pushing, check what's actually changed:

envi diff

This compares your local .env against the remote without changing either side — it prints added, removed, and changed keys. If someone else pushed since you last pulled, envi push fails with a conflict rather than silently overwriting their changes:

remote secrets have changed since your last pull; run envi pull to take them,
or envi push --force to overwrite them with your local file

Run envi pull to catch up, resolve any overlap by hand, then push again. If the remote holds nothing you want, envi push --force writes over it instead.

More than one environment

Projects hold as many environments as you need — the CLI calls them origins, and a directory is linked to one at a time:

envi origin create staging
envi origin list
envi origin switch staging

Switching pulls that origin's secrets into .env, and refuses if .env has changes you haven't pushed yet. To send a file to another origin without leaving the one you're on:

envi push .env.staging origin staging

Inviting a collaborator

envi share teammate@company.com --permission write

They get an email with a link. If they don't have an Envi account yet, that link creates one — see Invitations for the full flow.

What's next