What happens if you lose the key

Most tools that encrypt a .env give you one way in. Lose it and the file is noise. envs lets you keep five more, and each one costs a few hundred bytes.

How it is arranged

value   --sealed under-->  a random data key
data key --wrapped under-->  your key
data key --wrapped under-->  recovery code 1
data key --wrapped under-->  recovery code 2  ...

Any single wrap opens the data key, and the data key opens every value. So losing your key costs nothing as long as one code survives, and adding another way in means writing one more wrap. No value is touched.

Codes are shown once and never stored

envs init prints them once. The catalog keeps only wrapped copies, so no query gets a code back out of it. It is the same arrangement as two-factor backup codes, and it wants the same habit: store them somewhere your key isn't.

printf '%s' "$CODE" | envs export --yes --recovery-code -

Written to be typed by a person

Codes use Crockford base32, which drops I, L, O and U because those are the characters people misread. Case does not matter, separators do not matter, and the letters Crockford treats as digits are read that way. The alphabet exists to absorb transcription slips, so the parser absorbs them too.

Rotation costs nothing

envs rotate --key                 # new key, old one stops working
envs rotate --recovery-codes 5    # new codes, old ones stop working

Rotation re-wraps the data key and re-encrypts no value, so it finishes in milliseconds whatever the catalog holds. New wraps are written before the old ones are retired. If it is interrupted you are left with an extra wrap, never with none.

Backups carry the wraps with them

envs backup writes an encrypted snapshot that carries the wrapped data key alongside it. Without that, the only thing able to open a backup would be the catalog it came from, which is exactly what may be gone. A recovery code restores it on its own.

envs backup --to ./vault
envs restore <name> --recovery-code -