datalab-cli 0.1.0

# cache

Cache management operations.

## Synopsis

```
datalab cache <COMMAND>
```

## Description

Manage the local response cache. The CLI caches API responses to reduce costs on repeated requests.

---

## Commands

| Command | Description |
|---------|-------------|
| [`stats`](#stats) | Show cache statistics |
| [`clear`](#clear) | Clear cached responses |

---

## stats

Show cache statistics.

### Synopsis

```
datalab cache stats
```

### Example

```bash
datalab cache stats
```

### Output

```json
{
  "cache_dir": "/home/user/.cache/datalab",
  "response_count": 150,
  "response_size": 52428800,
  "file_count": 10,
  "file_size": 314572800
}
```

### Fields

| Field | Description |
|-------|-------------|
| `cache_dir` | Location of the cache directory |
| `response_count` | Number of cached API responses |
| `response_size` | Total size of response cache (bytes) |
| `file_count` | Number of cached files |
| `file_size` | Total size of file cache (bytes) |

---

## clear

Clear cached responses.

### Synopsis

```
datalab cache clear [OPTIONS]
```

### Options

| Option | Description |
|--------|-------------|
| `--older-than <N>` | Only clear entries older than N days |

### Examples

```bash
# Clear all cache
datalab cache clear

# Clear entries older than 7 days
datalab cache clear --older-than 7

# Clear entries older than 30 days
datalab cache clear --older-than 30
```

### Output

```json
{
  "cleared": true,
  "responses_deleted": 50,
  "files_deleted": 5,
  "bytes_freed": 157286400
}
```

---

## Cache Location

The cache is stored in the system cache directory:

| OS | Path |
|----|------|
| Linux | `~/.cache/datalab/` |
| macOS | `~/Library/Caches/datalab/` |
| Windows | `%LOCALAPPDATA%\datalab\cache\` |

### Cache Structure

```
~/.cache/datalab/
├── responses/           # JSON response cache
│   ├── abc123.json
│   ├── def456.json
│   └── ...
└── files/              # Binary file cache
    ├── xyz789.pdf
    └── ...
```

---

## Bypassing Cache

Use these flags to bypass caching:

| Flag | Scope | Description |
|------|-------|-------------|
| `--skip-cache` | Local | Skip local cache lookup |
| `--force` | API | Skip API-side caching (reprocess) |

### Examples

```bash
# Skip local cache, use API cache
datalab convert document.pdf --skip-cache

# Use local cache, force API reprocessing
datalab convert document.pdf --force

# Skip both caches
datalab convert document.pdf --skip-cache --force
```

---

## Cache Key Generation

Cache keys are generated from:

1. **File hash** - SHA256 of file contents (for local files)
2. **URL** - For remote files
3. **Endpoint** - API endpoint name (e.g., "convert", "extract")
4. **Parameters** - Request parameters hash

This ensures that:
- Same file + same options = cache hit
- Same file + different options = cache miss
- Modified file = cache miss

---

## Best Practices

### During Development

Keep caching enabled to reduce costs:

```bash
# First run: API call
datalab convert document.pdf

# Subsequent runs: cached
datalab convert document.pdf
```

### For Production

Consider periodic cache cleanup:

```bash
# Weekly cleanup of old entries
datalab cache clear --older-than 7
```

### For Testing

Bypass cache to ensure fresh results:

```bash
datalab convert document.pdf --skip-cache --force
```

---

## Related Commands

- [`convert`](convert.md) - Document conversion (cached)
- [`extract`](extract.md) - Data extraction (cached)

---

## See Also

- [Caching Concept](../concepts/caching.md)