BUPSTASH(1)

💖 BUPSTASH(1) — General Commands Manual 💖

okay bestie, this is the BUPSTASH(1) page from the General Commands Manual, and it is literally all about encrypted, deduplicated backups. iconic behavior.

---

✨ SYNOPSIS ✨

bupstash = encrypted and deduplicated backups. Run one of the following bupstash subcommands, k?

bupstash init ...
bupstash new-key ...
bupstash new-sub-key ...
bupstash put ...
bupstash list ...
bupstash list-contents ...
bupstash diff ...
bupstash get ...
bupstash restore ...
bupstash rm ...
bupstash recover-removed ...
bupstash gc ...
bupstash sync ...
bupstash exec-with-locks ...
bupstash serve ...
bupstash help ...
bupstash version ...

---

🌸 DESCRIPTION 🌸

okay so bupstash is a tool for storing (and retrieving) files and data in an encrypted bupstash-repostory(7). yes bestie, that spelling is right there in the original — iykyk.

Some notable features of bupstash include:

• 💖 Automatic deduplication of stored data.
• 🔐 Client side encryption of data.
• 🚀 Incremental file uploads.
• 🏷️ A tag based query language.
• 🔑 Optional role based encryption and decryption key separation.
• 🌐 Remote repositories over ssh ssh.
• 🛡️ Optional, per ssh key access repository controls.
• 🧅 A multi layered approach to security.

The bupstash tool itself is divided into subcommands that each have their own documentation. so yes, there is lore, and yes, you should read it.

---

🎀 SUBCOMMANDS 🎀

• bupstash-init(1) — initializes a bupstash repository. starting point energy.
• bupstash-new-key(1) — creates a new primary key for creating/reading repository items. key main character.
• bupstash-new-sub-key(1) — derives a sub key for a subset of operations. delegation slay.
• bupstash-put(1) — adds data to a bupstash repository. uploading vibes.
• bupstash-get(1) — fetches data from the bupstash repository matching a query. retrieval moment.
• bupstash-restore(1) — restores a snapshot into a local directory. putting it back where it belongs.
• bupstash-list(1) — lists repository items matching a given query. query and chill.
• bupstash-list-contents(1) — lists directory snapshot contents. peeking inside the snapshot.
• bupstash-diff(1) — diffs snapshot contents. spot the difference, backup edition.
• bupstash-rm(1) — removes repository items matching a given query. bye-bye, but make it query-based.
• bupstash-recover-removed(1) — recovers removed items that are pending garbage collection. resurrection arc.
• bupstash-gc(1) — reclaims diskspace in a repository. cleanup queen.
• bupstash-sync(1) — syncs items between repositories. sharing is caring.
• bupstash-exec-with-locks(1) — execs a command with exclusive locks held on the repository. locked in, literally.
• bupstash-serve(1) — serves a repository over stdin/stdout using the bupstash-protocol(7). server serve.

---

🔥 EXAMPLES 🔥

🗂️ Initialize a repository and create keys 🗂️

$ bupstash init -r ssh://$SERVER/home/me/backups
$ bupstash new-key -o backups.key

🧸 Tell bupstash to use our repository and key by default 🧸

$ export BUPSTASH_REPOSITORY=ssh://$SERVER/home/me/backups
$ export BUPSTASH_KEY=backups.key

📁 Directory snapshots 📁

$ bupstash put ./some-data
ebb66f3baa5d432e9f9a28934888a23d

$ bupstash list-contents id=ebb66f3baa5d432e9f9a28934888a23d
drwxr-xr-x 0    2020/11/05 10:42:48 .
-rw-r--r-- 177B 2020/07/12 17:13:42 data.txt

🔎 List items matching a query 🔎

$ bupstash list hostname=$(hostname)
id="bcb8684e6bf5cb453e77486decf61685" name="some-file.txt" hostname="my-server" timestamp="2020-07-27 11:26:16"
...

⚡ Incremental uploads ⚡

$ bupstash put --send-log /var/backup.sendlog ./some-data
ebb66f3baa5d432e9f9a28934888a23d

# Second backup is much faster when it reads the send log.
$ bupstash put --send-log /var/backup.sendlog ./some-data
ebb66f3baa5d432e9f9a28934888a23d

🎬 Capture and save command output 🎬

# Checks for errors before saving new item.
$ bupstash put --exec name=database.sql pgdump mydatabase
14ebd2073b258b1f55c5bbc889c49db4

🫶 Get an item matching a query 🫶

$ bupstash get id=bcb8684e6bf5cb453e77486decf61685
some data.

🧚 Restore a directory to a previous snapshot 🧚

$ bupstash restore --to ./dir name=dir.tar

💅 Remove items matching a query. 💅

$ bupstash rm name=some-data.txt

🧹 Wipe a repository 🧹

$ bupstash rm --allow-many id=*

🗑️ Reclaim disk space 🗑️

$ bupstash gc

🔐 Offline decryption keys 🔐

# Create a key, a put only key, and a metadata (list/rm only) key.
$ bupstash new-key -o backups.key
$ bupstash new-sub-key --put -k backups.key -o backups-put.key
$ bupstash new-sub-key --list -k backups.key -o backups-metadata.key

... Copy backups.key to secure offline storage ...

# Remove primary key
$ shred backups.key

$ bupstash put -k backups-put.key ./data
14ebd2073b258b1f55c5bbc889c49db4

... When you need to list or remove backups, you may use the metadata key ...

$ bupstash list -k backups-metadata.key
...
$ bupstash rm -k backups-metadata.key

... After emergency, get decryption key from offline storage ...

# Restore by getting an item and decrypting it using the decryption key.
$ bupstash get -k backups.key id=14ebd2073b258b1f55c5bbc889c49db4 | tar -C ./restore -xf -

---

🌈 SEE ALSO 🌈

bupstash-repository(7), bupstash-keyfiles(7)

---

okay that’s the whole BUPSTASH(1) moment, bestie — cute sign-off from the May 2025 edition of BUPSTASH(1), General Commands Manual energy, now go encrypt something and slay 💜✨