KeyEnv Rotate - Credential Rotation

KeyEnv can automatically rotate database credentials (PostgreSQL, MySQL) on a schedule. The CLI provides commands to inspect and manually trigger rotations.

Rotation configs are created via the web app or API. The CLI is used to monitor and trigger them.

Prerequisites

Requires keyenv CLI with an initialized project (keyenv init).

Commands

All rotation commands accept -e <env> for environment (default: development).

# List all rotation configurations
keyenv rotations list
keyenv rotations list -e production

# Show details for a specific rotation
keyenv rotations show main_db
keyenv rotations show main_db -e production

# Manually trigger a rotation
keyenv rotations trigger main_db
keyenv rotations trigger main_db -e production --yes

# View rotation history
keyenv rotations history main_db
keyenv rotations history main_db --limit 5

What Rotation Does

When a rotation triggers (scheduled or manual):

1. Connects to the database with admin credentials
2. Creates a new set of credentials (username + password)
3. Updates the corresponding KeyEnv secrets:
   • <NAME>_HOST, <NAME>_PORT, <NAME>_DATABASE
   • <NAME>_USERNAME, <NAME>_PASSWORD, <NAME>_URL
4. Keeps old credentials valid briefly for graceful transition
5. Revokes old credentials after the grace period

Rotation Status

The show command displays:

| Field | Meaning | |-------|---------| | status | active, paused, disabled, or error | | integration_type | postgresql or mysql | | rotation_interval_days | How often rotation runs | | last_rotation_at | When it last rotated | | next_rotation_at | When it will next rotate | | error_message | If status is error, what went wrong |

JSON Output

All commands support --json:

keyenv rotations list --json
keyenv rotations show main_db --json
keyenv rotations history main_db --json

Common Workflows

Check rotation health:

keyenv rotations list -e production --json
# Look for status: "error" or upcoming next_rotation_at

Emergency credential rotation:

keyenv rotations trigger main_db -e production --yes

Audit rotation history:

keyenv rotations history main_db -e production --limit 20