Cloud sync

How it protects your values

• Values are encrypted on your device with a key derived from your password and a 128-bit Secret Key. The server only ever stores ciphertext and can’t decrypt it.
• Secret names are stored in plaintext so you can see and audit them; values and descriptions are not.
• New devices join only after you compare a fingerprint on both screens, so the server can’t slip in a device of its own.
• Losing your password and your Secret Key means the data can’t be recovered, by anyone, including us.

Set up the first device

uv tool install 'keygrant[cloud]'     # adds the crypto dependency (PyNaCl)
keygrant cloud init                   # choose a password; prints your Emergency Kit

cloud init prints your Emergency Kit: the Account ID and the Secret Key. Write it down and keep it offline, on paper and not in a synced notes app. With the kit and your password you can recover even if every device is gone. Print it again later with keygrant cloud kit.

Upload secrets

Nothing leaves the machine until you push it:

keygrant push STRIPE_KEY OPENAI_KEY        # upload these

Day to day

echo "sk-..." | keygrant set STRIPE_KEY && keygrant push STRIPE_KEY   # add or change
keygrant push --delete STRIPE_KEY                                     # remove everywhere
keygrant sync                                                          # pull now
keygrant cloud status                                                  # account, devices, sync state

keygrant list and keygrant exec pull changes on their own, at most once a minute, and silently skip it when you’re offline, so you rarely need sync.

Conflicts

• If two devices change the same secret, the later push is refused until you sync. Nothing is merged automatically.
• A local edit you haven’t pushed yet is never overwritten by sync.
• A local-only secret with the same name as a synced one is left alone, with a warning.

More devices

Add a second machine by pairing it from one you already have, or with the Emergency Kit alone if no old device is at hand.

Leaving

keygrant cloud delete

This permanently deletes the account, all ciphertext and every paired device. Secrets stay on each machine as local-only entries and keep working. You’ll be asked to type the Account ID to confirm.