---
name: "bupstash-get"
section: "1"
platform: "linux"
package: "bupstash"
version: "0.12.0-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/bupstash-get"
---

# bupstash-get(1)

## SYNOPSIS

Get data from a bupstash repository.

**bupstash get \[OPTIONS\] QUERY...**

## DESCRIPTION

**bupstash get** fetches and decrypts data stored in a bupstash repository, sending it to stdout. If the requested item was saved as a directory, the command converts it into a tar stream.

The item that is fetched is chosen based on a simple query against the tags specified when saving data with **bupstash put**.

## QUERY LANGUAGE

For full documentation on the query language, see [bupstash-query-language(7)](/bupstash-query-language/7.md).

## QUERY CACHING

The get command uses the same query caching mechanisms as [bupstash-list(1)](/bupstash-list/1.md), check that page for more information on the query cache.

## SPARSE FILES

When getting a directory as a tarball sparse files are not treated specially, to restore sparse files while preserving the file holes use **bupstash restore** instead.

## 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**.

- \-k, --key KEY

  Key that will be used to decrypt data and metadata. If not set, defaults to **BUPSTASH\_KEY**.

- \--pick PATH

  Fetch an individual file or sub-directory from a snapshot.

- \--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).

- \-q, --quiet

  Be quiet, implies --no-progress.

## 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)](/bupstash-serve/1.md). This allows more complex connections to the repository for less common use cases.

- 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.

- 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.

-

  ```
  # 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/1.md), [bupstash-put(1)](/bupstash-put/1.md), [bupstash-list(1)](/bupstash-list/1.md), [bupstash-restore(1)](/bupstash-restore/1.md), [bupstash-rm(1)](/bupstash-rm/1.md), [bupstash-keyfiles(7)](/bupstash-keyfiles/7.md), [bupstash-query-language(7)](/bupstash-query-language/7.md)