Skip to main content

​
Run History CLI

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

​
Quick Start

# 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. 
praisonai recipe runs list [options]
Options:
OptionDescription
--recipe <name>Filter by recipe name
--session <id>Filter by session ID
--limit <n>Maximum results (default: 20)
--jsonOutput JSON format
Examples: 
# 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. 
praisonai recipe runs stats [--json]
Output: 
Run History Stats:
  Total runs: 42
  Storage size: 1.5 MB
  Path: ~/.praison/runs

​
runs cleanup

Clean up old runs based on retention policy. 
praisonai recipe runs cleanup [--json]

​
export

Export a run for replay or debugging. 
praisonai recipe export <run_id> [options]
Options:
OptionDescription
-o, --output <path>Output file path
--jsonOutput JSON format
Examples: 
# 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. 
praisonai recipe replay <bundle> [options]
Options:
OptionDescription
--compareCompare output with original
--jsonOutput JSON format
Examples: 
# Simple replay
praisonai recipe replay export.json

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

​
Export Format

{
  "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 ~/.praison/runs/. 
~/.praison/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: 
# In TEMPLATE.yaml
data_policy:
  retention_days: 30
  export_allowed: true
  pii:
    mode: redact

​
Python API

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