keyshroud

Move a project off .env

A .env file keeps the values where an agent can read them. This guide moves them into the vault and leaves a .env.refs file of names and references that you can commit. It takes about five minutes and nothing is written until you say so.

1. See what would move

cd my-project
keyshroud import
import plan for .env (item prefix "my-project")
  STRIPE_KEY    secret    new      -> keyshroud://my-project STRIPE_KEY
  PORT          literal   kept
  DATABASE_URL  secret    new      -> keyshroud://my-project DATABASE_URL
2 secret(s): 2 new, 0 already in the vault, 0 conflict(s); 1 literal(s), 0 reference(s)
Dry run: nothing written. Re-run with --yes to create 2 item(s) and write .env.refs

import decides which lines are secrets by name (*_TOKEN, *_KEY, …) or by value (sk-…, a URL with a password). The plan shows names only. If it got one wrong, --only A,B moves just those names and --skip A,B leaves some where they are. --from FILE reads another file, --prefix P names the vault items differently.

2. Move them

keyshroud import --yes

Each secret becomes one vault item, is read back to check it, and .env.refs is written with your comments and non-secret lines kept:

STRIPE_KEY=keyshroud://my-project STRIPE_KEY
PORT=3000
# comment
DATABASE_URL=keyshroud://my-project DATABASE_URL

3. Run with the references

keyshroud run --refs .env.refs -- npm test
keyshroud run --refs .env.refs -- npm run dev

The command gets the real values. Whatever it prints is masked when the output goes to an agent, a pipe or CI. If your package.json scripts load .env themselves (dotenv, node --env-file=.env), remove that and let keyshroud run set the environment.

4. Delete the plaintext

.env still holds the values until you remove it. Check step 3 works first, then:

rm .env
keyshroud scan .          # any copy of a vault value left in the working tree?
git add .env.refs

keyshroud import --yes --replace does steps 2 and 4 in one go: it rewrites .env in place into references, with no backup copy.

If .env was ever committed, the values are in the git history: treat them as leaked and rotate them.

For your teammates

.env.refs names items, and each person's vault holds their own values. A teammate runs keyshroud add --env STRIPE_KEY --item "my-project STRIPE_KEY" once per name, or you keep the shared values in Vaultwarden or in the secret manager your team runs and write those references (bw://…, vault://…) into .env.refs instead.

Good to know

  • Multiline values, ${VAR} expansion and duplicate keys are rejected with the line number, never the value.
  • Running import again reuses items that already hold the same value and stops on one that differs.
  • To give an agent in this project only this project's names, add a project scope: keyshroud scope --only 'STRIPE_*,DATABASE_URL'.

Edit this page on GitHub · Markdown