BUPSTASH-LIST-CONTENTS(1)

💅 bupstash-list-contents(1) — the manual, but make it make sense ✨

okay bestie, so bupstash-list-contents is a whole mood. it lives in the General Commands section of the manual, and it's here to show you what's inside a snapshot. no cap, it's lowkey iconic.

✨ SYNOPSIS ✨

list the contents of a snapshot, bestie:

bupstash list-contents [OPTIONS] QUERY...

🎀 DESCRIPTION 🎀

bupstash list-contents lists what's inside the item that matches your query. simple as that, fr fr.

here's the tea though: items created by using bupstash put on a directory get an associated index. other items? not listable. sorry bestie, it's giving "no index, no entry" 💀.

🌈 OUTPUT FORMATS 🌈

🌸 Human

when --format is set to human, bupstash list-contents outputs aligned rows that look like this, periodt:

PERMS SIZE YYYY/MM/DD HH:MM:SS PATH...

the date included is the time of the last change to a given file, as reported by the operating system at the time of the snapshot. iykyk.

bestie, prefer using one of the versioned machine readable formats when writing scripts. the human format is cute for eyeballs, not for parsing 💅

🦋 JSONl1

when --format is set to jsonl1, bupstash list-contents outputs one json object per line. each line is giving main character energy and has this exact json schema:

{
  "path": string | [ bytes... ],
  "mode": number,
  "size": number,
  "uid": number,
  "gid": number,
  "mtime": number,
  "mtime_nsec": number,
  "ctime": number,
  "ctime_nsec": number,
  "norm_dev": number,
  "ino": number,
  "nlink": number,
  "link_target": string | null,
  "dev_major": number | null,
  "dev_minor": number | null,
  "xattrs": {string : string | [bytes...] ...} | null,
  "sparse": boolean,
  "data_hash": "$KIND[:$HEXBYTE]" | null
}

like, look at all those fields, we love a detailed queen 👑.

🔥 QUERY LANGUAGE 🔥

for the full documentation on the query language, see bupstash-query-language(7). no need to reinvent the wheel, bestie.

👑 QUERY CACHING 👑

the list-contents command uses the same query caching mechanisms as bupstash-list(1). check that page for more info on the query cache — it's literally the same vibe.

💖 OPTIONS 💖

• -r, --repository REPO — the repository to connect to, may be of the form ssh://$SERVER/$PATH for remote repositories if ssh access is configured. if not specified, is set to BUPSTASH_REPOSITORY. (yes, there's a little typo in the original with the double comma, but we're keeping it exactly as is, bestie — character for character, no cap.)
• -k, --key KEY — key used to decrypt data and metadata. if not set, defaults to BUPSTASH_KEY. 💅
• --format FORMAT — set output format to one of the following: 'human', 'jsonl'. pick your fighter 🥊
• --query-cache PATH — path to the query-cache file, defaults to one of the following, in order, provided the appropriate environment variables are set: $BUPSTASH_QUERY_CACHE, $XDG_CACHE_HOME/.cache/bupstash/bupstash.qcache or $HOME/.cache/bupstash/bupstash.qcache. it's giving "we have options" ✨
• --pick PATH — list a sub-directory of the query. like zooming in on the main character 🎀
• --utc-timestamps — display and search against timestamps in utc time instead of local time. for when you're feeling global 🌍
• -q, --quiet — be quiet, implies --no-progress. shhh 🤫

🌟 ENVIRONMENT 🌟

• BUPSTASH_REPOSITORY — the repository to connect to. may be of the form ssh://$SERVER/$PATH for remote repositories if ssh access is configured. your go-to connection bestie.
• BUPSTASH_REPOSITORY_COMMAND — a command to run to connect to an instance of bupstash-serve(1). this allows more complex connections to the repository for less common use cases. fancy, we love 💅
• BUPSTASH_KEY — path to a primary key that will be used for decrypting data and metadata. the key to the kingdom 🔑
• BUPSTASH_KEY_COMMAND — a command to run that must print the key data. can be used instead of BUPSTASH_KEY to fetch the key from arbitrary locations such as the network or other secret storage. spy kid vibes 🕵️‍♀️
• BUPSTASH_QUERY_CACHE — path to the query cache file to use. cache me outside, how bout dat 💾

🍓 EXAMPLES 🍓

🧚 get an item with a specific id from the repository

$ bupstash list-contents id="14eb*"
drwxr-xr-x 0     2020/10/30 13:32:04 .
-rw-r--r-- 1967  2020/10/30 13:32:04 data.txt

look at that beautiful output — data.txt is living its best life with 1967 bytes, and the directory is just vibing. slay 💅✨

🫶 SEE ALSO 🫶

bupstash(1), bupstash-put(1), bupstash-diff(1), bupstash-keyfiles(7), bupstash-query-language(7)

---

okay that's the whole page, bestie. go forth and list those contents like the icon you are 💖. this was the BUPSTASH-LIST-CONTENTS(1) manual from May 2025, and honestly? she ate. periodt. 🌈💅🎀