Versions and rollback

Writes append, history shows no values, and rollback never decrypts

Writes append

Each value carries a version number. Writing a new value does not overwrite the old one: the old ciphertext moves to an archive, and the new value takes the next number.

sh
enveil set DATABASE_URL          # v1
enveil set DATABASE_URL          # v2; v1 is archived

Versions count per key and environment, so DATABASE_URL in dev and in prod have separate histories. enveil push and enveil import write only the keys whose values differ, so an unchanged key gets no new version.

The point is recovery. A rotation that broke production can be undone, and an audit entry can name the exact version that was read.

History fetches no values

sh
enveil history DATABASE_URL
text
v3	2026-10-08T11:40:19.220871+00:00	machine 2d94e1c7-…	(current)
v2	2026-10-07T16:05:52.913407+00:00	user 6f1c2a90-…
v1	2026-09-30T08:12:44.051236+00:00	user 6f1c2a90-…

Newest first: the version, when it was written, and whether a person (user) or a machine identity (machine) wrote it. --json prints the same as one JSON document.

No value is fetched, so history is not a disclosure: it is not recorded as a read and costs no read budget. An agent can call it freely.

Rollback copies forward without decrypting

sh
enveil rollback DATABASE_URL 2
text
Restored DATABASE_URL in my-app/prod from v2 as v4.

The server copies v2's ciphertext into a new version, v4, and archives v3 the same way an ordinary write would. Nothing is deleted and nothing is rewritten in place, so the history stays an append-only account of what was in effect and when.

The value is never decrypted on the way. Undoing a bad rotation does not require anyone, person or agent, to see the credential. That is why a rollback counts as a write, not a read:

history rollback Reading an archived value
Needs Read access Write access Read access
Decrypts No No Yes
Recorded in the audit trail No Yes, as an update naming the new version Yes, as a read naming the version
Costs read budget No No Yes

Rolling back to the version that is already current is refused.

Reading an archived value

An old credential may still be live on some system nobody rotated, so reading one is a disclosure like any other. The HTTP API and the dashboard can return an archived value; each such read is recorded against the version it concerns and charged to the read budget. The CLI has no command for it.

Expiry

A key can carry the date its credential lapses, for API keys and certificates that expire upstream:

sh
enveil set STRIPE_SECRET_KEY --expires 90d
enveil set STRIPE_SECRET_KEY --expires 2027-01-31T00:00:00Z
enveil set STRIPE_SECRET_KEY --no-expiry
Form Meaning
30d, 12w, 1y Days, weeks or years from now (a year is 365 days)
RFC 3339 timestamp That instant
--no-expiry Clear the date

A daily job emails the organization's owners and admins a week before the date, and once more after it has passed. The emails name the project and key, never the value. Setting a new date starts the reminders over; writing the same date again does not.

The expiry belongs to the key, not to one environment's value, so it applies in every environment. Setting or clearing it therefore needs write access to the whole project; a token scoped to one environment is refused, and the value is not written either.

enveil list shows the date next to the key, as expires 2027-01-31 or expired 2027-01-31.

Delete

sh
enveil delete DATABASE_URL -e staging

This removes the key's current value and its entire history in that one environment. Other environments keep theirs. Once no environment holds a value, the key itself is gone, along with its expiry and proxy hosts.

A deleted value cannot be rolled back: the archive went with it. To retire a credential while keeping the record, set a new value instead.