Skip to main content
List all backup snapshots in the repository with their creation times, source information, and tags.

​
Usage

cloudstic list [options]
No additional flags are required beyond storage/encryption credentials. The command displays a table of all snapshots sorted by creation time.

​
Options

​
List Options

​
-group
boolean
default:"false"
Group snapshots by source identity. Displays a separate table for each unique source lineage, making it easier to review repositories with multiple backup sources.

​
Global Options

  • Storage backend configuration (-store URI, etc.)
  • Encryption credentials (-password, -encryption-key, etc.)
  • Verbosity and machine-readable output flags (-verbose, -quiet, -json, -debug)
​
-verbose
boolean
default:"false"
Enable verbose output with additional details about snapshot loading and catalog reconciliation.

​
Examples

cloudstic list

​
Output

The command displays a table with the following columns: 
12 snapshots
┌─────┬─────────────────────┬──────────────────────────────────┬─────────┬─────────────┬────────────────┬──────────┐
│ Seq │ Created             │ Snapshot Hash                     │ Source  │ Account     │ Path           │ Tags     │
├─────┼─────────────────────┼──────────────────────────────────┼─────────┼─────────────┼────────────────┼──────────┤
│ 1   │ 2024-03-15 10:23:15 │ a3f8d2e1c4b5a6f9                 │ local   │             │ ./documents    │          │
│ 2   │ 2024-03-15 14:45:32 │ b1e9c7d3f5a8b2d6                 │ gdrive  │ user@ex.com │                │ daily    │
│ 3   │ 2024-03-16 08:12:47 │ c2f1a9e4d7b3c8f5                 │ local   │             │ ./documents    │ prod,v2  │
└─────┴─────────────────────┴──────────────────────────────────┴─────────┴─────────────┴────────────────┴──────────┘

​
Column Descriptions

  • Seq: Snapshot sequence number (increments with each backup)
  • Created: Timestamp when the snapshot was created (UTC)
  • Snapshot Hash: Unique identifier for the snapshot (SHA-256 hash, first 16 hex chars shown)
  • Source: Source type with optional volume label (e.g. gdrive (My Drive), local (MyUSB))
  • Account: Account identifier (hostname for local, email for cloud sources)
  • Path: Display path within the source (portable drives are shown absolute from drive root, e.g. /Photos)
  • Tags: Comma-separated tags applied to the snapshot
Snapshot hashes are displayed as short prefixes for readability. Use the full hash or short prefix with other commands like cloudstic restore a3f8d2.

​
Snapshot Identity

Each snapshot is associated with a source identity consisting of:
  • Source type (local, gdrive, onedrive, sftp)
  • Identity (stable container ID)
  • Path ID (stable selected-root ID within the container)
  • Account (display label, e.g. hostname or email)
  • Drive Name (display container label, e.g. “My Drive”, “Team Photos”)
  • Path (display path)
Matching precedence is:
  1. type + identity + path_id
  2. type + identity + path (bridge fallback)
  3. type + volume_uuid + path (legacy fallback)
  4. type + account + path (legacy fallback)

​
Grouped Output

Use -group to display snapshots grouped by source identity. This is useful when a repository contains backups from multiple sources: 
21 snapshots

── gdrive-changes (My Drive) · loic@gmail.com · / (12 snapshots)
┌─────┬─────────────────────┬──────────────────┬─────┐
│ Seq │ Created             │ Snapshot Hash    │ ... │
├─────┼─────────────────────┼──────────────────┼─────┤
│  21 │ 2026-03-11 11:07:11 │ 76eaaf00...      │     │
│  20 │ 2026-03-11 11:07:03 │ 3f84bda4...      │     │
└─────┴─────────────────────┴──────────────────┴─────┘

── local (MyUSB) · macbook · Photos (9 snapshots)
┌─────┬─────────────────────┬──────────────────┬─────┐
│ Seq │ Created             │ Snapshot Hash    │ ... │
├─────┼─────────────────────┼──────────────────┼─────┤
│  19 │ 2026-03-08 13:45:17 │ 7959d22c...      │     │
└─────┴─────────────────────┴──────────────────┴─────┘

​
Snapshot Catalog

Cloudstic maintains a snapshot catalog (index/snapshots) that stores lightweight summaries of all snapshots. This allows the list command to display results quickly without fetching every individual snapshot object. The catalog automatically reconciles with the repository on load:
  • Missing snapshots found via LIST snapshot/ are added to the catalog
  • Orphaned catalog entries (snapshot object deleted) are removed
  • Self-healing ensures the catalog stays in sync
If you suspect the catalog is out of sync (e.g., after manual object store manipulation), the next list operation will automatically reconcile and repair it.

​
Filtering and Sorting

The list command displays all snapshots sorted by creation time (oldest first). For more advanced filtering and snapshot management, use:
  • cloudstic forget: Remove snapshots based on retention policies with filtering by tag, source, account, or path
  • cloudstic diff: Compare two snapshots to see what changed

​
Performance

The list command is fast because:
  • Reads from the snapshot catalog (single object fetch)
  • Does not load individual snapshot objects
  • Does not traverse HAMT trees or file metadata
Typical performance: less than 1 second for repositories with thousands of snapshots.

​
Empty Repository

If the repository has no snapshots yet: 
0 snapshots
┌─────┬─────────┬───────────────┬────────┬─────────┬──────┬──────┐
│ Seq │ Created │ Snapshot Hash │ Source │ Account │ Path │ Tags │
└─────┴─────────┴───────────────┴────────┴─────────┴──────┴──────┘
Run cloudstic backup to create your first snapshot.

​
Encryption

If your repository is encrypted, you must provide valid credentials: 
cloudstic list -password "my secret passphrase"
Or using environment variables: 
export CLOUDSTIC_PASSWORD="my secret passphrase"
cloudstic list
Snapshot metadata is encrypted at rest. The list command decrypts the catalog and individual snapshot objects as needed.
Without valid encryption credentials, the command will fail with an authentication error.

​
Machine-Readable Output

For scripting and automation, consider using:
  • cloudstic cat index/snapshots: Display raw JSON snapshot catalog
  • cloudstic cat index/latest: Display the latest snapshot reference
  • cloudstic cat snapshot/<hash>: Display a specific snapshot’s JSON
Example: 
cloudstic cat index/snapshots | jq '.snapshots[] | select(.tags | contains(["production"]))'

​
See Also