Docs CLI devsafe rotate-key

Rotate your encryption key

Replace your current encryption key with a new one and re-encrypt every backup in place. The old key is destroyed. This is a paid feature. Paid

Overview

Key rotation means generating a fresh AES-256 encryption key, re-encrypting all of your existing git bundles with that new key, and securely destroying the old key. Once rotation completes, only the new key can decrypt your backups.

DevSafe follows NIST SP 800-57 key management guidelines, which recommend rotating encryption keys on a regular schedule. The standard recommends rotation at least once per year for keys protecting sensitive data. DevSafe tracks your key age and warns you when rotation is due.

During rotation, DevSafe uses nonce-unique AEAD for every re-encrypted git bundle. Each bundle gets a fresh nonce, so no two encryptions ever share the same nonce and key combination.

Rotation is atomic.

If rotation is interrupted (power loss, cancelled), DevSafe rolls back to the previous key. Your backups are never left in a partially re-encrypted state.

Usage

terminal

$ devsafe rotate-key

This command does the following:

Generates a new AES-256 key using HKDF-SHA256 derivation
Downloads each encrypted git bundle from your user-owned storage
Decrypts with the old key, re-encrypts with the new key (nonce-unique AEAD)
Uploads the re-encrypted bundle, replacing the old version
Destroys the old key material from your machine
Updates your recovery phrase

Flags

flags

--dry-run       Show what would be re-encrypted without doing it
--confirm       Skip the confirmation prompt
--name <name>   Name for the new key (default: auto-generated)

Example

terminal

$ devsafe rotate-key --name "prod-2026-q3"
Current key: prod-2026 (age: 187 days)
Backups to re-encrypt: 14 repos, 342 bundles (12.8 GB)

This will:
  1. Generate a new AES-256 key (prod-2026-q3)
  2. Re-encrypt all 342 bundles with the new key
  3. Destroy the old key (prod-2026)
  4. Save a new recovery phrase

Continue? [y/N] y

✓ generated key prod-2026-q3
  re-encrypting api-server (24 bundles)...
✓ api-server complete
  re-encrypting design-tokens (18 bundles)...
✓ design-tokens complete
  re-encrypting marketing-site (31 bundles)...
✓ marketing-site complete
  ... 11 more repos

✓ 342/342 bundles re-encrypted
✓ old key (prod-2026) destroyed
✓ new recovery phrase saved to ~/.devsafe/recovery

Back up your new recovery phrase immediately.

The old recovery phrase no longer works after rotation. Store the new phrase in a password manager or print it. DevSafe cannot recover lost keys.

Check rotation status

Use devsafe rotation-status to see whether a rotation is in progress, completed, or failed.

terminal

$ devsafe rotation-status
Status:         idle
Active key:     prod-2026-q3
Last rotation:  2026-06-15 09:41:22 UTC
Bundles total:  342
Bundles on new key: 342/342
✓ all backups use the current key

If a rotation was interrupted, you will see a different output:

terminal

$ devsafe rotation-status
Status:         interrupted
Active key:     prod-2026 (rollback complete)
Bundles total:  342
Bundles on old key: 342/342
Reason:         connection lost at bundle 198/342

Run "devsafe rotate-key" to try again.

Check key age

Use devsafe key-age to see how old your current key is and when NIST guidelines recommend rotating it.

terminal

$ devsafe key-age
Key:            prod-2026-q3
Created:        2026-06-15
Age:            16 days
NIST schedule:  rotate by 2027-06-15 (364 days remaining)
✓ key is within recommended age

When your key is approaching the NIST rotation deadline, you will see a warning:

terminal

$ devsafe key-age
Key:            prod-2026
Created:        2025-12-01
Age:            213 days
NIST schedule:  rotate by 2026-12-01 (152 days remaining)
⚠ key age exceeds 180 days, rotation recommended

How rotation works

Key rotation is a re-encryption delta. That means DevSafe does not create new git bundles. It only changes the encryption layer around each existing bundle. Here is the process step by step:

Generate new key

A new AES-256 key is derived using HKDF-SHA256. The key is generated on your machine and never leaves it.

Re-encrypt each bundle

For each git bundle in your user-owned storage, DevSafe downloads the encrypted blob, decrypts it with the old key, re-encrypts it with the new key using nonce-unique AEAD (fresh nonce per bundle), and uploads the result. This happens one repo at a time.

Verify round-trip

After re-encryption, DevSafe verifies that every bundle can be decrypted with the new key. If any bundle fails verification, the entire rotation rolls back.

Destroy old key

Once all bundles are verified on the new key, the old key material is securely wiped from your machine. The old recovery phrase is invalidated. A new recovery phrase is generated and saved.

NIST SP 800-57 guidelines

NIST Special Publication 800-57 provides recommendations for cryptographic key management. DevSafe follows these guidelines:

Crypto period: AES-256 keys used for data encryption should be rotated at least annually.
Key destruction: Old key material must be securely destroyed after rotation, not just archived.
Key separation: Each key has a single purpose. Rotation generates a completely new key rather than modifying the existing one.
Key tracking: DevSafe records key creation time, rotation history, and current age. Use devsafe key-age to view this data.

DevSafe warns you at 180 days and again at 330 days. If your key exceeds 365 days without rotation, devsafe status will report a degraded health score.

Dry run

Before committing to a rotation, run a dry run to see what will happen:

terminal

$ devsafe rotate-key --dry-run
Dry run (no changes will be made)

Current key: prod-2026 (age: 187 days)
Repos: 14
Bundles: 342
Total size: 12.8 GB
Estimated time: ~4 minutes

No changes made.