BUPSTASH-GET(1)

📦
version 0.12.0 · 3 versions
, in alpine 3.24

💅 BUPSTASH-GET(1) — like, the get page, bestie 🎀

okay so this is bupstash-get(1) from the General Commands Manual and honestly? she's a whole vibe. sit down, grab a strawberry drink 🍓, and let's get into it.

✨ SYNOPSIS ✨

Get data from a bupstash repository. that's it. that's the whole point.

bupstash get [OPTIONS] QUERY...

🌸 DESCRIPTION 🌸

bupstash get fetches and decrypts data that's stored in a bupstash repository, and sends it straight to stdout. slay. if the thing you asked for was saved as a directory, the command converts it into a tar stream for you. cute, right? 🧚

the item that gets fetched is chosen based on a simple query against the tags you specified back when you saved the data with bupstash put. so like, the query is the main character here 👑

🦋 QUERY LANGUAGE 🦋

for the full documentation on the query language, see bupstash-query-language(7). iykyk, but also go read it.

💜 QUERY CACHING 💜

the get command uses the same query caching mechanisms as bupstash-list(1). check that page for more info on the query cache — she explains it better than i could ngl.

🌈 SPARSE FILES 🌈

⚠️ okay bestie, listen. when you get a directory as a tarball, sparse files are not treated specially. no special treatment, no exceptions. 😭

if you actually want to restore sparse files while preserving the file holes, use bupstash restore instead. periodt.

✨ 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 you don't specify it, it's set to BUPSTASH_REPOSITORY. 🫶
  • -k, --key KEY — the key that will be used to decrypt data and metadata. if it's not set, it defaults to BUPSTASH_KEY. 💖
  • --pick PATH — fetch an individual file or sub-directory from a snapshot. very "i just want this one thing" of you. 🎀
  • --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. ✨
  • --utc-timestamps — display and search against timestamps in utc time instead of local time. 🌍
  • --no-progress — suppress progress indicators. (progress indicators are also suppressed when stderr is not an interactive terminal, so like, she already knows. 💅)
  • -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. 🦋
  • 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. 👑
  • BUPSTASH_KEY — path to the key that will be used for decrypting data and metadata. 🔑
  • 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. main character energy fr fr. 🧚
  • BUPSTASH_QUERY_CACHE — path to the query cache file to use. 💜

🎀 EXAMPLES 🎀

💫 Get an item with a specific id

$ bupstash get id=14ebd2073b258b1f55c5bbc889c49db4 > ./data.file

💫 Get an item by name and timestamp

$ bupstash get name=backup.tar and timestamp=2020/19/* > ./restore.tar

💫 Get a file or sub-tar from a directory snapshot

$ bupstash get --pick=path/to/file.txt id=$id
$ bupstash get --pick=path/to/dir id=$id | tar ...

💫 Get a tarball

the builtin directory put creates a tarball from a directory, so to extract it we use tar. iconic teamwork honestly 🤝

# Snapshot a directory.
$ id=$(bupstash put ./data)

# Fetch the contents of a snapshot and extract the contents with tar
$ mkdir restore
$ bupstash get id=$id | tar -C ./restore -xvf -

⭐ SEE ALSO ⭐

bupstash(1), bupstash-put(1), bupstash-list(1), bupstash-restore(1), bupstash-rm(1), bupstash-keyfiles(7), bupstash-query-language(7) — go read the whole friend group, they all ate 💅✨

and that's the page! brought to you by May 2025, BUPSTASH-GET(1), no cap. go get your data bestie, you're gonna slay 🫶💖

📦 where this page comes from