Skip to content
kovrakovra

Backup & recovery

The master key is the root of trust for your whole vault: every entry is encrypted under it. If you lose it — a wiped Keychain, a dead machine — the encrypted records are unrecoverable. kovra key makes a portable, encrypted backup so that never becomes a catastrophe.

Export a backup

Section titled “Export a backup”

kovra key export asks you to bioProve (the key is the vault’s root of trust — on a Mac with Touch ID only the fingerprint approves it, not the login password, and the dialog says it exports the key that opens every secret), then a recovery passphrase (twice), and writes a standard ASCII-armored age blob — encrypted under that passphrase. The plaintext key never lands in a file.

Terminal window
kovra key export --out kovra-master.age

The blob is portable: restore it with kovra key import, or decrypt it with any age implementation in a real disaster. Handy variants:

  • --clipboard — copy the (encrypted) blob to paste into a password manager.
  • --op — store it directly in 1Password via the op CLI; kovra generates the recovery passphrase and saves it alongside the blob, so there’s nothing to memorize.

Store the backup somewhere independent of the machine it came from — a password manager, not the same disk.

Restore

Section titled “Restore”

kovra key import reads the blob, asks for the recovery passphrase, and puts the key back into the OS keyring:

Terminal window
kovra key import kovra-master.age

Once restored, the vault unlocks exactly as before.

kovra restores only the vault’s own key: a backup whose key does not open the vault’s records is refused (“this backup’s key does not open the vault”), so a blob someone else built can’t install a key its author knows. Replacing a key that is already in the keyring takes --force and your approval.

This is also the fix when kovra reports that the master key in the keyring does not open this vault. Any program running as you can rewrite or delete the Keychain item with no prompt; kovra can’t prevent that, but the vault’s key check (keycheck.sec) detects it, and kovra stops instead of sealing new secrets under the wrong key. Restore the right key from your backup.