Env files and secrets in local development

An environment variable is a named string that a process receives from the process that started it. It is a copy, so changing it later does not reach a process that is already running. A .env file is a plain text list of KEY=value lines that a library or tool loads into that environment at startup. There is no .env standard. Each loader decides what quotes, comments, and $ references mean, so one file can give different values in Node.js, python-dotenv, and Docker Compose.

Three habits cover most teams. Commit a .env.example that lists every variable the code reads, with safe local values and empty secrets. Keep real env files out of Git with an ignore rule that does not hide the example. Check for drift, because the example and the real file move apart as keys are added. The .env and .env.example checklist covers ignore rules that work, onboarding a teammate, and what to do in order when a secret leaks. The env file diff checker compares two pasted files for missing, extra, duplicate, empty, and malformed keys, by name and emptiness only, in your browser.

1. Read the environment variable and .env file entries for the vocabulary.
2. Work through the checklist, then run the diff checker on your own files.
3. If an editor or agent config holds a token, read MCP config file locations, because those files are credentials too.

It is plain text that anything running as your user can read. It has no audit trail and no revocation, so you cannot see who holds a copy. Every value is text, and a typo in a name stays silent until the code reads it. For anything shared, audited, or rotated on a schedule, use the secret store your platform or team already runs. Deleting a leaked file does not rotate the key: a later commit that untracks .env leaves the earlier value readable in history.

Rig keeps env profiles as plain files in <project>/.rig/env/, adds an ignore rule for that folder, and masks secret-looking values in its interface. Its env_diff MCP tool compares key names only, and list_env_profiles masks secret-named values, so an agent can see which keys are missing without reading a secret. Profiles are local only. Syncing secrets is a separate step that encrypts them locally and uploads ciphertext. Masked env manager, Secrets vault basics, and Env profiles: client vs personal explain the details.

The diff checker cannot tell you that a value is correct, current, or a placeholder. The loader comparison in the checklist covers only Node.js 22.22.0, python-dotenv 1.2.3, and Docker Compose v5.6.0, so test your own loader with a file that contains # and $.