Skip to main content
The cat command displays the raw JSON content of repository objects. This is useful for inspecting the internal structure of your backup repository, debugging issues, or understanding how data is stored.

​
Usage

cloudstic cat [options] <object_key> [object_key...]

​
Object Key Patterns

You can inspect any repository object by its key pattern:
  • config: Repository configuration (encryption status, version, creation date)
  • index/latest: Mutable pointer to the most recent snapshot
  • index/snapshots: Snapshot catalog with lightweight summaries
  • snapshot/<hash>: Point-in-time backup snapshot metadata
  • filemeta/<hash>: File metadata (name, type, parents, content hash)
  • content/<hash>: Chunk manifests (list of chunk refs, or inline data for small files)
  • node/<hash>: HAMT internal/leaf nodes
  • chunk/<hash>: Raw file data chunks
  • keys/<slot>: Encryption key slots (stored unencrypted)
Use cloudstic list to get snapshot hashes, then inspect them with cloudstic cat snapshot/<hash>

​
Options

​
-json
boolean
default:"false"
Write a JSON array of fetched objects to stdout. Each item includes the object key and decoded data.
​
-raw
boolean
default:"false"
Output raw, unformatted data. This is useful for verifying the integrity of objects by piping them directly into hashing tools like sha256. It disables JSON pretty-printing and does not append a trailing newline.

​
Global Options

​
Examples

​
Display repository configuration

cloudstic cat config
Output: 
{
  "version": 1,
  "created": "2024-03-15T10:30:00Z",
  "encrypted": true
}

​
Inspect the latest snapshot pointer

cloudstic cat index/latest
Output: 
{
  "ref": "snapshot/a1b2c3d4e5f6789...",
  "updated": "2024-03-20T14:22:10Z"
}

​
View a specific snapshot

First, list snapshots to get the hash: 
cloudstic list
Then inspect the snapshot: 
cloudstic cat snapshot/a1b2c3d4e5f6789...
Output: 
{
  "seq": 42,
  "created": "2024-03-20T14:22:10Z",
  "root": "node/f1e2d3c4b5a6...",
  "source": {
    "type": "local",
    "path": "/home/user/documents"
  },
  "tags": ["daily", "documents"],
  "stats": {
    "files": 1234,
    "bytes": 5368709120
  }
}

​
Inspect multiple objects at once

cloudstic cat config index/latest index/snapshots
When multiple objects are requested, headers are printed to separate the output: 
==> config <==
{
  "version": 1,
  "created": "2024-03-15T10:30:00Z",
  "encrypted": true
}

==> index/latest <==
{
  "ref": "snapshot/a1b2c3d4e5f6789...",
  "updated": "2024-03-20T14:22:10Z"
}

==> index/snapshots <==
{
  "snapshots": [
    {
      "ref": "snapshot/a1b2c3d4e5f6789...",
      "seq": 42,
      "created": "2024-03-20T14:22:10Z"
    }
  ]
}

​
Output clean JSON for scripting

Use -json to emit a single JSON array: 
cloudstic cat -json config | jq '.[0].data.encrypted'
Output: 
true

​
View file metadata

cloudstic cat filemeta/d4e5f6a1b2c3...
Output: 
{
  "name": "report.pdf",
  "type": "file",
  "size": 2097152,
  "mode": 420,
  "mtime": "2024-03-19T08:15:30Z",
  "content": "content/e6f7a8b9c0d1...",
  "parents": [
    "filemeta/b2c3d4e5f6a7..."
  ]
}

​
Inspect encryption key slots

cloudstic cat keys/password-1
Output: 
{
  "slot_type": "password",
  "label": "Default password slot",
  "wrapped_key": "...",
  "kdf_params": {
    "algorithm": "scrypt",
    "n": 32768,
    "r": 8,
    "p": 1,
    "salt": "..."
  }
}

​
Use Cases

​
Debugging

When troubleshooting repository issues, inspect the object hierarchy: 
# Check repository initialization
cloudstic cat config

# Verify latest snapshot exists
cloudstic cat index/latest

# Inspect snapshot metadata
cloudstic cat snapshot/<hash>

​
Understanding Repository Structure

Explore how Cloudstic stores data internally: 
# View snapshot catalog
cloudstic cat index/snapshots

# Follow the reference chain
cloudstic cat snapshot/<hash> | jq '.root'
cloudstic cat node/<root-hash>

​
Scripting and Automation

Extract specific fields using jq or other JSON tools: 
# Get the latest snapshot hash
cloudstic cat -json index/latest | jq -r '.[0].data.ref'

# Count total files in a snapshot
cloudstic cat -json snapshot/<hash> | jq '.[0].data.stats.files'

# Check encryption status
cloudstic cat -json config | jq -r '.[0].data.encrypted'

​
Verify object hash

Calculate the SHA-256 hash of a repository object to verify its key matches its content: 
# Calculate hash of a filemeta object
cloudstic cat -raw filemeta/5a9ff... | sha256sum

​
Notes

  • Read-only operation: This command only reads from the repository and never modifies data
  • Encrypted content: Content objects (content/*, chunk/*, filemeta/*, node/*, snapshot/*) are encrypted in encrypted repositories. The cat command automatically decrypts them.
  • Unencrypted objects: config, keys/*, and index/* objects are always stored unencrypted
  • JSON formatting: Default output pretty-prints object content. With -json, the command emits one structured JSON array for all requested objects.
  • Hash prefixes: Object keys use full SHA-256 hashes. You can use the full hash from other commands like list