Migrating from .env files

Move a repository's .env files into enveil and stop keeping them on disk

A .env file is a copy of your credentials that outlives every process that needed it, sits in backups, and gets committed by accident. Moving a repository onto enveil takes a few minutes: import what is there, switch the scripts to enveil run, then delete the files.

Move the values in

1

Point the repository at a project

From the repository root:

sh
enveil login
enveil init --project acme-api --create --server https://enveil.oxidt.com

--create makes the project if this login cannot already see one called acme-api. init writes .enveil.toml, which names the server, project and default environment (dev unless you pass -e). Commit it; it holds no secrets.

2

See what would be imported

sh
enveil import --dry-run

Every .env* file next to .enveil.toml is matched to an environment:

File Environment
.env the default from .enveil.toml
.env.staging, .env.stage staging
.env.production prod
.env.development dev
.env.<name> the environment named <name>, if the project has one
.env.example, .env.sample, .env.template, .env.dist skipped: templates, not values

A file with no matching environment is skipped and says so. The output lists keys as create or update, never values, so it is safe to paste into a ticket.

3

Import

sh
enveil import

Only keys whose value differs are written. Keys already stored but missing from a file are left alone and listed at the end; nothing is deleted on the server.

To bring in a single file, or one whose name does not match an environment, use push:

sh
enveil push --file .env.local --dry-run
enveil push --file .env.local -e dev

Many repositories at once:

sh
for d in ~/projects/*/; do (cd "$d" && [ -f .env ] && \
  enveil init --project "$(basename "$d")" --create && enveil import); done

Switch the scripts

Anything that read .env now gets its variables from enveil run:

json
"scripts": {
  "dev": "enveil run -- vite",
  "test": "enveil run -- vitest",
  "migrate": "enveil run -e staging -- sqlx migrate run"
}

The values exist only in the child process's environment. A library such as dotenv that looks for a file finds none; the variables are already in the process environment.

For secrets that are only ever sent to known APIs, consider giving them allowed hosts and using enveil run --proxy, so the process sees placeholders instead of values. See Proxy mode.

Delete the old files

Once enveil run -- <your dev command> works, delete the .env files. They are now a second, unaudited copy of what enveil holds. Make sure .gitignore covers them, with an exception for the example. Avoid a bare .env*: it also matches .enveil.toml, which should be committed.

gitignore
.env
.env.*
!.env.example

If a .env file was ever committed, its values are in the repository history. Deleting the file does not remove them: rotate those credentials with enveil set.

Keep a list of the variables

Newcomers still need to know which variables exist. Generate the list rather than maintaining it by hand:

sh
enveil example          # writes .env.example: KEY= lines, no values

example fetches key names only, so it discloses nothing and costs no read budget. Commit the file and check it in CI, so a key added in enveil but not documented fails the build:

sh
enveil example --check  # exit 1 if a stored key is missing from .env.example

A key listed in the file but not stored only warns, since it is usually optional.

When a tool needs a real file

Some tooling reads .env and nothing else. For that, pull is the escape hatch:

sh
enveil pull                         # writes .env with mode 0600
enveil pull --out .env.local --force

It refuses to overwrite an existing file without --force and warns if git does not ignore the file it wrote. Fix .gitignore before anything else. Every pulled value is recorded as a read.