AGEVAULT(1)

👑 AGEVAULT(1) 👑 — the General Commands Manual era

okay so bestie, gather round, because this is the manual page for agevault (section 1 of the General Commands Manual, iykyk) and it's literally about keeping your whole directory locked down. 💅

---

✨ NAME ✨

agevault — a directory encryption tool that uses age(1) file encryption. that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

agevault directory keygen [-pq]
agevault directory lock
agevault directory unlock
agevault --version

---

🦋 DESCRIPTION 🦋

agevault is a directory encryption tool using age(1) file encryption. periodt.

It locks/unlocks a vault (directory) with a passphrase-protected identity file. no cap, that's it.

Like age(1), it features no config options, allowing for a straightforward secure flow. iconic behavior honestly — nothing to fiddle with, nothing to get wrong. 🌈

agevault relies entirely on age for the cryptography involved, inheriting its security. it just provides the minimal infrastructure required for age to work as a directory encryption tool. think of it as the group-chat organizer, not the cryptographer. 🫶

Locking archives directory, encrypts it to directory.age and shreds directory. Unlocking decrypts directory.age with the identity file, restores directory and shreds directory.age. so the plaintext is never just chillin' next to the ciphertext. 💀

The identity file is named .fingerprint.directory.key.age and lives in the current working directory, next to the vault. It's encrypted with a passphrase for a few key reasons:

Extra security factor — having the encrypted identity file or the passphrase by itself is useless. it's giving two-factor but make it aesthetic. 🔥

Easier to lock — if only symmetric encryption was used, the user would need the passphrase to lock as well; this way, the vault can be locked without entering the passphrase. lowkey the best part.

Multiple keys (recipients) — each passphrase corresponds to its own key, so multiple people can own the vault: any one of them can lock it, and any one of them can unlock it with their own passphrase. bestie group vault, fr fr. 👑

🧚 Recipients 🧚

The vault is encrypted to every recipient listed in directory/.agevault-recipients. keygen adds its recipient automatically, and the file is locked together with the rest of the vault. For my-vault, it looks like this:

# agevault recipients for my-vault
# lines starting with # are ignored

# fingerprint: ab2a0883204b8bb5a463fe79ecde7674
age14p8nysmdqmlhgczshculs35kt2y8rrsx9jd9mc0rglg90rr504xsh3qzty

Every recipient's fingerprint is printed on lock. Check that each one is yours or matches a fingerprint someone sent you. 🕵️‍♀️ like, actually check it. vibe check your fingerprints.

🧬 Post-quantum keys 🧬

keygen -pq generates a post-quantum identity (ML-KEM-768 + X25519) instead of an X25519 one. Its recipient starts with age1pq1 and is much longer. future-proof queen behavior.

age can't encrypt to post-quantum and X25519 recipients at the same time, so every recipient of a vault must be the same kind. keygen refuses to add a recipient that doesn't match the existing ones, so everyone sharing a post-quantum vault must use keygen -pq.

⚠️ no mixing. it's a whole thing. if your vault is PQ, everybody's keygen needs that -pq, or it's not happening.

---

💖 OPTIONS 💖

• keygen — generate a new identity, encrypt it with a passphrase into .fingerprint.directory.key.age and add its recipient to directory/.agevault-recipients. Creates directory if it doesn't exist. The vault must be unlocked. 🔓
• -pq — only valid with keygen. Generate a post-quantum identity instead of an X25519 one. See Post-quantum keys. 🧬
• lock — encrypt directory to every recipient in directory/.agevault-recipients and print their fingerprints. No passphrase is required. slay, no typing secrets. 🎀
• unlock — prompt for the identity file passphrase and decrypt directory.age back into directory. 🗝️
• --version — print the version and exit.

Running agevault without a command prints the usage. (yes, it will tell you what to do. it's helpful like that.) 💜

---

⏳ BACKWARDS COMPATIBILITY ⏳

Always install the latest release to make sure you have the latest security improvements and fixes. If the update has the same major version (e.g. v1.x.x), then it's guaranteed to be backwards compatible. easy math, bestie. ✨

Before v1.2.0, the recipient was stored in the identity filename. Vaults created with older versions are migrated automatically: the first lock creates .agevault-recipients from the existing identity file. Once it's migrated, the identity file can be renamed, as long as it keeps the .directory.key.age ending. so like, rename away, just keep the suffix. 🙈

Vaults locked with v1.0.0 were archived with zip instead of tar. They are still unlocked transparently, and the next lock uses the current format. no action needed, it just works. 💀

---

🌟 EXAMPLES 🌟

Assuming we want to secure the directory my-vault/.

Generate identity file:

$ agevault my-vault keygen
create identity passphrase:
confirm identity passphrase:
.ab2a0883204b8bb5a463fe79ecde7674.my-vault.key.age CREATED
ab2a0883204b8bb5a463fe79ecde7674 ADDED to my-vault/.agevault-recipients

Lock vault:

$ agevault my-vault lock
my-vault LOCKED with:
  ab2a0883204b8bb5a463fe79ecde7674

Unlock vault:

$ agevault my-vault unlock
enter passphrase for identity file ".ab2a0883204b8bb5a463fe79ecde7674.my-vault.key.age":
my-vault UNLOCKED

That's it. Do your changes, lock it again, etc. literally the whole routine. 🔁

Generate a post-quantum identity file:

$ agevault my-vault keygen -pq

To share a vault, the other person runs agevault my-vault keygen (add -pq for post-quantum vaults) and sends you the recipient and fingerprint from their my-vault/.agevault-recipients. Paste the recipient into yours and lock, then send them my-vault.age. They need to remove the empty my-vault/ created by their keygen before unlocking. 🎁

💅 friendly reminder: that empty directory will be in the way, so yeet it before unlocking.

---

🔗 SEE ALSO 🔗

age(1) — the icon, the legend, the actual cryptography. 👑

---

and that's the page, bestie 🫶 stay encrypted, stay iconic, and remember — this manual page is dated October 2026, AGEVAULT(1), General Commands Manual. mwah. 💖