---
name: "bupstash-list-contents"
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-list-contents"
---

# bupstash-list-contents(1)

## SYNOPSIS

List snapshot contents.

**bupstash list-contents \[OPTIONS\] QUERY...**

## DESCRIPTION

**bupstash list-contents** lists the contents of the item matching the given query.

Items created by using **bupstash put** on a directory will have an associated index, other items are not listable.

## OUTPUT FORMATS

### Human

When **--format** is set to **human**, **bupstash list-contents** outputs aligned rows consisting of:

-

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

-

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

Prefer using one of the versioned machine readable formats when writing scripts.

### JSONl1

When **--format** is set to **jsonl1**, **bupstash list-contents** outputs one json object per line.

Each line has the following 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
  }
  ```

-

  ## QUERY LANGUAGE

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

## QUERY CACHING

The list-contents 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.

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

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

- \--pick PATH

  List a sub-directory of the query.

- \--utc-timestamps

  Display and search against timestamps in utc time instead of local time.

- \-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 a primary 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 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
```

## SEE ALSO

[bupstash(1)](/bupstash/1.md), [bupstash-put(1)](/bupstash-put/1.md), [bupstash-diff(1)](/bupstash-diff/1.md), [bupstash-keyfiles(7)](/bupstash-keyfiles/7.md), [bupstash-query-language(7)](/bupstash-query-language/7.md)