Skip to main content
List files and directories within a specific snapshot, displaying the full directory tree with file sizes.

​
Usage

If no snapshot ID is provided, the latest snapshot is used.

​
Options

​
string
default:"latest"
Snapshot ID to list files from. Can be:
  • Full snapshot hash (e.g., a3f8d2e1...)
  • Short prefix (e.g., a3f8d2)
  • latest (default): lists files from the most recent snapshot

​
Global Options

  • Storage backend configuration (-store URI, etc.)
  • Encryption credentials (-password, -encryption-key, etc.)
  • Verbosity and machine-readable output flags (-verbose, -quiet, -json, -debug)
​
boolean
default:"false"
Enable verbose output showing detailed progress while loading file metadata.

​
Examples

​
Output

The command displays a hierarchical tree of all files and directories in the snapshot:

​
Tree Structure

  • Directories are shown without a size
  • Files are shown with their uncompressed size in parentheses
  • Files and directories are sorted alphabetically within each level
  • Indentation shows the directory hierarchy
File sizes shown are the original uncompressed sizes, not the deduplicated/compressed size in the repository.

​
Snapshot Selection

You can specify snapshots in multiple ways:

​
By Full Hash

​
By Short Prefix

Cloudstic accepts any prefix that identifies exactly one snapshot. If multiple snapshots match, the command fails instead of choosing one.

​
By “latest”

Lists files from the most recent snapshot based on creation time.
Use cloudstic list to view all available snapshots with their IDs and creation times.

​
Use Cases

​
Finding Files

Browse the snapshot tree to find specific files before restoring:

​
Verifying Backups

Confirm that expected files were included in a backup:

​
Comparing Snapshots

List files from different snapshots to see what changed:
Or use the built-in cloudstic diff command for structured comparison:

​
Performance

The ls command must load all file metadata from the snapshot to build the tree. Performance depends on:
  • File count: More files take longer to load
  • Storage backend: Cloud storage (S3/B2) is slower than local storage
  • HAMT depth: Deeper trees require more object fetches
Typical performance:
  • 1,000 files: less than 1 second (local storage)
  • 10,000 files: 2-5 seconds (cloud storage)
  • 100,000 files: 20-60 seconds (cloud storage)
For large snapshots, use -verbose to see progress as metadata is loaded. The HAMT tree structure ensures logarithmic scaling even for millions of files.

​
HAMT Tree Structure

Cloudstic stores file metadata in a persistent Hash Array Mapped Trie (HAMT):
  • Files are indexed by their path (e.g., documents/report.pdf)
  • Each HAMT node is a separate object in the repository
  • The tree structure provides efficient lookups and updates
  • Only changed subtrees are rewritten during backups (structural sharing)
The ls command recursively walks the HAMT tree from the snapshot’s root node to build the full file listing.

​
Encryption

If your repository is encrypted, you must provide valid credentials:
Or using environment variables:
All file metadata is encrypted at rest. The ls command decrypts objects as needed to build the tree.
Without valid encryption credentials, the command will fail with an authentication error.

​
Machine-Readable Output

For scripting and automation, the tree output can be parsed, but consider using the raw snapshot object for structured data:
For more complex operations, consider using the Cloudstic Go library directly.

​
Size Formatting

File sizes are displayed in human-readable format:
  • B: Bytes (< 1 KiB)
  • KiB: Kibibytes (1024 bytes)
  • MiB: Mebibytes (1024 KiB)
  • GiB: Gibibytes (1024 MiB)
  • TiB: Tebibytes (1024 GiB)
Sizes use binary prefixes (base 1024) following IEC 60027-2 standard.

​
See Also