cloudstic cat

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

boolean

default:"false"

Write a JSON array of fetched objects to stdout. Each item includes the object key and decoded data.

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

cloudstic list: List all snapshots to get snapshot hashes
cloudstic ls: List files within a snapshot
cloudstic check: Verify repository integrity

Onboarding

Interactive Mode

Repository Management

Backup & Restore

Maintenance

Key Management

Configuration

Utilities

Usage

Object Key Patterns

Options

Global Options

Examples

Display repository configuration

Inspect the latest snapshot pointer

View a specific snapshot

Inspect multiple objects at once

Output clean JSON for scripting

View file metadata

Inspect encryption key slots

Use Cases

Debugging

Understanding Repository Structure

Scripting and Automation

Verify object hash

Notes

​Usage

​Object Key Patterns

​Options

​Global Options

​Examples

​Display repository configuration

​Inspect the latest snapshot pointer

​View a specific snapshot

​Inspect multiple objects at once

​Output clean JSON for scripting

​View file metadata

​Inspect encryption key slots

​Use Cases

​Debugging

​Understanding Repository Structure

​Scripting and Automation

​Verify object hash

​Notes

​Related Commands

Usage

Object Key Patterns

Options

Global Options

Examples

Display repository configuration

Inspect the latest snapshot pointer

View a specific snapshot

Inspect multiple objects at once

Output clean JSON for scripting

View file metadata

Inspect encryption key slots

Use Cases

Debugging

Understanding Repository Structure

Scripting and Automation

Verify object hash

Notes

Related Commands