Rotate a value

Write your new value as the next version with penv set or Set New Version in the console, then retire the old one at its issuer.

A rotation writes the next version of a value; we keep every earlier version in the history. penv has no rotate command.

Command line

printf %s "$NEW_VALUE" | penv set STRIPE_SECRET_KEY --env production

set version 4 STRIPE_SECRET_KEY in acme/api-gateway/production

Behaviour	Detail
Input	stdin, or a no-echo prompt at a terminal
`--value` flag	Refused with `value_on_the_command_line`, because the shell keeps history
Undeclared key	penv appends a block to `.env.schema` with the inferred type and no value.

penv set prints the version we created. Without a @penv header it writes .env or .env.<env> instead. penv unset KEY removes a value and keeps its schema block.

Console

In the environment, open the row menu, choose Set New Version, then Save New Version. The address is locked, and the value field starts empty: we never fill it from storage.

Details & History on the same menu lists every version with its number and date. See parameters.

A new version does not revoke the old value at its issuer. Your payment processor or database accepts the previous value until you retire it there. Rotate at the issuer and in Penv Cloud, then retire the old value.

Permissions

Action	Needs
Write a version	`secret:write` at the environment
Read a value back	`secret:reveal` at the environment, plus step-up in the console

We record both in the audit log with the actor and version.

`@rotate`

.env.schema

# @type=string(startsWith=sk_) @rotate=90d
STRIPE_SECRET_KEY=

Where	Effect
`penv check`	Names keys due, overdue or with no recorded write; exits 0
No `@penv` header	`penv set` records each write in `[rotation]` in `.penv/config.toml`
Console	We track the due date there and in a weekly email to the members chosen for security alerts: rotation state

Nothing replaces a value automatically.

Cloud-minted keys

A write to a key minted by an engine answers 409 dynamic (CLI exit 3, dynamic). Rotation means changing the engine: short-lived values.

Procedure

Mint the new value at the issuer. Leave the old one working.

printf %s "$NEW_VALUE" | penv set KEY --env production, or Set New Version in the console.

Confirm the printed version is one higher than before.

Redeploy or restart every process that reads the key, and watch for failures until the slowest one restarts.

Retire the old value at the issuer. Until then, both work.

Confirm the write in the audit log under your name.