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
Point the repository at a project
From the repository root:
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.
See what would be imported
enveil import --dry-runEvery .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.
Import
enveil importOnly 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:
enveil push --file .env.local --dry-run
enveil push --file .env.local -e devMany repositories at once:
for d in ~/projects/*/; do (cd "$d" && [ -f .env ] && \
enveil init --project "$(basename "$d")" --create && enveil import); doneSwitch the scripts
Anything that read .env now gets its variables from enveil run:
"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.
.env
.env.*
!.env.exampleIf 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:
enveil example # writes .env.example: KEY= lines, no valuesexample 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:
enveil example --check # exit 1 if a stored key is missing from .env.exampleA 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:
enveil pull # writes .env with mode 0600
enveil pull --out .env.local --forceIt 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.
push and import compare against the values currently stored, so they fetch them, even with --dry-run. That fetch is recorded in the audit log and charged to the read budget like any other export.