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

# Cache CLI

> CLI commands for cache management with file-based persistence

The `praisonai-ts` CLI provides the `cache` command for managing cached values with file-based persistence.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User([User]) --> CLI[CLI]
    CLI --> Cache[Cache]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class Cache agent
    class User,CLI tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-ts cache set my_key "value"
    ```
  </Step>

  <Step title="With Configuration">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-ts cache set my_key "value" --ttl 3600
    ```
  </Step>
</Steps>

***

## Commands Overview

| Command                   | Description             |
| ------------------------- | ----------------------- |
| `cache set <key> <value>` | Cache a value           |
| `cache get <key>`         | Get cached value        |
| `cache delete <key>`      | Delete cached entry     |
| `cache list`              | List all cached entries |
| `cache stats`             | Show cache statistics   |
| `cache clear`             | Clear all cache entries |
| `cache help`              | Show help               |

## Set a Value

Cache a key-value pair:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic caching
praisonai-ts cache set api_response "Hello from API"

# With TTL (time-to-live in seconds)
praisonai-ts cache set token "abc123xyz" --ttl 3600

# JSON output
praisonai-ts cache set mykey "value" --json
```

**Example Output:**

```
✓ Cached: api_response
  TTL: 3600 seconds
```

## Get a Value

Retrieve a cached value:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get cached value
praisonai-ts cache get api_response

# JSON output
praisonai-ts cache get mykey --json
```

**Example Output:**

```
✓ Cache hit: api_response
Hello from API
```

**Cache Miss Output:**

```
ℹ Cache miss: unknown_key
```

**JSON Output:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "success": true,
  "data": {
    "key": "api_response",
    "value": "Hello from API",
    "found": true
  }
}
```

## Delete a Value

Remove a cached entry:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts cache delete api_response
praisonai-ts cache delete mykey --json
```

## List All Entries

View all cached items:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts cache list
praisonai-ts cache list --json
```

**Example Output:**

```
Cache Entries

  • api_response (15 chars)
    Created: 2026-01-17T22:30:00.000Z
  • token (9 chars)
    Created: 2026-01-17T22:31:00.000Z

ℹ Total: 2 entries
```

## Cache Statistics

View cache stats:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts cache stats
praisonai-ts cache stats --json
```

**Example Output:**

```
Cache Statistics

  Entries: 5
  Total Size: 1234 characters
  Expired: 0
  Location: ~/.praisonai/cache
```

**JSON Output:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "success": true,
  "data": {
    "entries": 5,
    "totalSize": 1234,
    "expired": 0,
    "cacheDir": "/Users/you/.praisonai/cache"
  }
}
```

## Clear All

Remove all cached entries:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-ts cache clear
praisonai-ts cache clear --json
```

**Example Output:**

```
✓ Cleared 5 cache entries
```

## Options

| Option            | Description                  | Default       |
| ----------------- | ---------------------------- | ------------- |
| `--ttl <seconds>` | Time-to-live for cache entry | No expiration |
| `--json`          | JSON output                  | `false`       |

## Cache Location

Cache files are stored in:

```
~/.praisonai/cache/<key>.json
```

Each file contains:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "value": "cached content",
  "createdAt": 1705123456789,
  "expiresAt": 1705127056789
}
```

## Use Cases

### API Response Caching

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Cache an API response
praisonai-ts cache set weather_data "sunny, 72F" --ttl 1800

# Retrieve later
praisonai-ts cache get weather_data
```

### Session Tokens

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Cache authentication token with 1-hour TTL
praisonai-ts cache set auth_token "eyJhbGciOiJIUzI..." --ttl 3600
```

### Config Values

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Cache configuration that changes infrequently
praisonai-ts cache set feature_flags '{"darkMode":true,"beta":false}'
```

## Related

<CardGroup cols={2}>
  <Card title="Cache" icon="book" href="/docs/js/memory">
    SDK cache module
  </Card>

  <Card title="Database CLI" icon="terminal" href="/docs/js/database-cli">
    Persistent storage
  </Card>

  <Card title="Memory CLI" icon="terminal" href="/docs/js/memory-cli">
    Agent memory
  </Card>
</CardGroup>