> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cloudstic cat

> Display raw JSON content of repository objects for inspection and debugging

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

```bash theme={null}
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)

<Tip>
  Use `cloudstic list` to get snapshot hashes, then inspect them with `cloudstic cat snapshot/<hash>`
</Tip>

## Options

<ParamField path="-json" type="boolean" default="false">
  Write a JSON array of fetched objects to stdout. Each item includes the object key and decoded data.
</ParamField>

<ParamField path="-raw" type="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.
</ParamField>

### Global Options

## Examples

### Display repository configuration

```bash theme={null}
cloudstic cat config
```

**Output:**

```json theme={null}
{
  "version": 1,
  "created": "2024-03-15T10:30:00Z",
  "encrypted": true
}
```

### Inspect the latest snapshot pointer

```bash theme={null}
cloudstic cat index/latest
```

**Output:**

```json theme={null}
{
  "ref": "snapshot/a1b2c3d4e5f6789...",
  "updated": "2024-03-20T14:22:10Z"
}
```

### View a specific snapshot

First, list snapshots to get the hash:

```bash theme={null}
cloudstic list
```

Then inspect the snapshot:

```bash theme={null}
cloudstic cat snapshot/a1b2c3d4e5f6789...
```

**Output:**

```json theme={null}
{
  "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

```bash theme={null}
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:

```bash theme={null}
cloudstic cat -json config | jq '.[0].data.encrypted'
```

**Output:**

```
true
```

### View file metadata

```bash theme={null}
cloudstic cat filemeta/d4e5f6a1b2c3...
```

**Output:**

```json theme={null}
{
  "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

```bash theme={null}
cloudstic cat keys/password-1
```

**Output:**

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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`

## Related Commands

* [`cloudstic list`](/commands/list): List all snapshots to get snapshot hashes
* [`cloudstic ls`](/commands/ls): List files within a snapshot
* [`cloudstic check`](/commands/check): Verify repository integrity