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

# Run History

> Store, query, and export recipe run history

# Run History CLI

Store and manage recipe run history for debugging, auditing, and replay.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List recent runs
praisonai recipe runs list

# Export a run
praisonai recipe export run-abc123 -o export.json

# Replay a run
praisonai recipe replay export.json --compare
```

## Commands

### runs list

List runs from history.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe runs list [options]
```

**Options:**

| Option            | Description                   |
| ----------------- | ----------------------------- |
| `--recipe <name>` | Filter by recipe name         |
| `--session <id>`  | Filter by session ID          |
| `--limit <n>`     | Maximum results (default: 20) |
| `--json`          | Output JSON format            |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all recent runs
praisonai recipe runs list

# Filter by recipe
praisonai recipe runs list --recipe support-reply

# Filter by session
praisonai recipe runs list --session session-abc123

# JSON output
praisonai recipe runs list --json
```

### runs stats

Get storage statistics.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe runs stats [--json]
```

**Output:**

```
Run History Stats:
  Total runs: 42
  Storage size: 1.5 MB
  Path: ~/.praisonai/runs
```

### runs cleanup

Clean up old runs based on retention policy.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe runs cleanup [--json]
```

### export

Export a run for replay or debugging.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe export <run_id> [options]
```

**Options:**

| Option                | Description        |
| --------------------- | ------------------ |
| `-o, --output <path>` | Output file path   |
| `--json`              | Output JSON format |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Export to default filename
praisonai recipe export run-abc123

# Export to specific file
praisonai recipe export run-abc123 -o my-export.json
```

### replay

Replay a run from an export bundle.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe replay <bundle> [options]
```

**Options:**

| Option      | Description                  |
| ----------- | ---------------------------- |
| `--compare` | Compare output with original |
| `--json`    | Output JSON format           |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple replay
praisonai recipe replay export.json

# Replay with drift detection
praisonai recipe replay export.json --compare
```

## Export Format

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "format": "praison-run-export",
  "version": "1.0",
  "exported_at": "2024-12-29T12:00:00Z",
  "run": {
    "run_id": "run-abc123",
    "recipe": "support-reply",
    "version": "1.0.0",
    "status": "success",
    "input": {"ticket_id": "T-123"},
    "output": {"reply": "..."},
    "metrics": {"duration_sec": 2.5},
    "trace": {"session_id": "session-001"}
  }
}
```

## Storage Location

Run history is stored at `~/.praisonai/runs/`.

```
~/.praisonai/runs/
├── index.json
└── run-abc123/
    ├── run.json      # Metadata
    ├── input.json    # Input data
    ├── output.json   # Output data
    └── events.jsonl  # Event stream
```

## Data Policy

Runs respect the recipe's data policy:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# In TEMPLATE.yaml
data_policy:
  retention_days: 30
  export_allowed: true
  pii:
    mode: redact
```

## Python API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.history import RunHistory, get_history

# Get default history
history = get_history()

# Store a run
from praisonai.recipe.models import RecipeResult, RecipeStatus

result = RecipeResult(
    run_id="run-abc123",
    recipe="my-recipe",
    version="1.0.0",
    status=RecipeStatus.SUCCESS,
    output={"result": "hello"},
)

history.store(result, input_data={"query": "test"})

# List runs
runs = history.list_runs(recipe="my-recipe", limit=10)

# Get specific run
run_data = history.get("run-abc123")

# Export
export_path = history.export("run-abc123")

# Stats
stats = history.get_stats()
print(f"Total runs: {stats['total_runs']}")

# Cleanup
deleted = history.cleanup(retention_days=30)
```

## Next Steps

* [Recipe Registry](/docs/cli/recipe-registry) - Publish and pull recipes
* [Security Features](/docs/cli/recipe-security) - SBOM, signing, auditing
* [Policy Packs](/docs/cli/recipe-policy) - Manage tool permissions