Cricket Live

# 🏏 Cricket Live

**Live cricket scores, IPL tracking, and match alerts for OpenClaw.**

Get real-time scores, upcoming schedules, detailed scorecards, and IPL standings — all from your OpenClaw agent. Powered by [CricketData.org](https://cricketdata.org) API (endpoint: `api.cricapi.com`).

---

## ✨ Features

- 🔴 **Live Scores** — All currently live matches with real-time scores, overs, and status
- 📋 **Match Details** — Full scorecards with batting and bowling stats
- 📅 **Upcoming Matches** — Next 7 days of scheduled matches, filterable by team
- ✅ **Recent Results** — Completed matches from the last 3 days
- 🏆 **IPL Hub** — Standings, upcoming IPL matches, live scores, and results
- 🔍 **Match Search** — Find any match by team name (supports aliases like "MI", "CSK", "AUS")
- 🔔 **Alerts** — Cron-ready script for wicket, century, and result notifications
- 💾 **Smart Caching** — Respects API quota with configurable TTL per endpoint
- 🇮🇳 **IST by Default** — All times displayed in Indian Standard Time

---

## 🚀 Quick Start

### 1. Get a Free API Key
Sign up at [cricketdata.org](https://cricketdata.org) — the free tier gives you **100 API calls/day**. (CricketData.org's API is served at `api.cricapi.com` — they are the same service.)

### 2. Set the Environment Variable
```bash
export CRICKET_API_KEY="your-api-key-here"
# Add to your shell profile or ~/.openclaw/.env for persistence
```

### 3. Run Any Script
```bash
bash scripts/live-scores.sh              # What's happening right now?
bash scripts/upcoming-matches.sh         # What's coming up?
bash scripts/ipl.sh standings            # IPL points table
```

---

## 📖 Usage

### Live Scores
```bash
bash scripts/live-scores.sh
```
Shows all currently live matches with scores, overs, and match status.

**Example output:**
```
🏏 LIVE CRICKET SCORES
━━━━━━━━━━━━━━━━━━━━━

🔴 India vs England — 3rd Test, Day 2
🇮🇳 India: 285/6 (78.2 ov)
🏴 England: 312 (98.4 ov)
📊 India trail by 27 runs

🔴 Australia vs South Africa — 1st ODI
🇦🇺 Australia: 156/3 (28.1 ov)
📊 In Progress
```

### Upcoming Matches
```bash
bash scripts/upcoming-matches.sh              # All upcoming
bash scripts/upcoming-matches.sh --team India  # Filter by team
bash scripts/upcoming-matches.sh MI            # Works with aliases
```

**Example output:**
```
📅 UPCOMING MATCHES (Next 7 Days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🇮🇳 India vs England — 4th Test
📍 Ranchi
🕐 16 Feb 2026, 09:30 AM IST

🏏 Mumbai Indians vs Chennai Super Kings — IPL 2026
📍 Wankhede Stadium, Mumbai
🕐 18 Feb 2026, 07:30 PM IST
```

### Recent Results
```bash
bash scripts/recent-results.sh
```

**Example output:**
```
✅ RECENT RESULTS
━━━━━━━━━━━━━━━━━

🏆 India won by 5 wickets
India vs England — 2nd Test
📍 Visakhapatnam

🏆 Australia won by 73 runs
Australia vs Sri Lanka — 3rd ODI
📍 Melbourne
```

### IPL Hub
```bash
bash scripts/ipl.sh standings   # Points table
bash scripts/ipl.sh upcoming    # Upcoming IPL matches
bash scripts/ipl.sh live        # Live IPL scores
bash scripts/ipl.sh results     # Recent IPL results
```

### Match Details (Scorecard)
```bash
bash scripts/match-details.sh <match-id>
```
Get match IDs from live-scores or search results.

### Search Matches
```bash
bash scripts/search-match.sh "India vs Australia"
bash scripts/search-match.sh "MI vs CSK"
```

### Cricket Alerts (Cron)
```bash
bash scripts/cricket-alert.sh
```
Detects wickets, centuries, and match completions since last check. Outputs only when something notable happens — perfect for cron.

---

## 🗣️ Natural Language Mapping

| User says | Script |
|-----------|--------|
| "What's the score?" / "Live scores" | `live-scores.sh` |
| "Show me the scorecard for match X" | `match-details.sh <id>` |
| "Upcoming matches" / "What's coming up?" | `upcoming-matches.sh` |
| "Recent results" / "Who won?" | `recent-results.sh` |
| "IPL table" / "IPL standings" | `ipl.sh standings` |
| "IPL matches today" | `ipl.sh live` |
| "India vs Australia" | `search-match.sh "India vs Australia"` |

---

## ⚙️ Configuration

### `config/cricket.yaml`
Main configuration file. API key can be set here or via `CRICKET_API_KEY` env var (env var takes priority).

```yaml
api_key: ""                    # Set via env var recommended
favorite_teams:                # Teams for alert filtering
  - India
  - Mumbai Indians
alert_events:                  # Events that trigger alerts
  - wicket
  - century
  - match_end
cache_dir: /tmp/cricket-cache  # Cache directory
cache_ttl:                     # Cache TTL in seconds per endpoint
  live: 120
  upcoming: 1800
  results: 1800
  series: 86400
  scorecard: 300
```

### `config/teams.yaml`
Team name aliases for fuzzy matching. Maps shorthand names (MI, CSK, IND, AUS) to canonical API names. See `config/README.md` for details.

---

## ⏰ Cron Integration

Set up periodic match alerts:

```bash
# Check for notable events every 5 minutes during match hours
*/5 9-23 * * * CRICKET_API_KEY="your-key" bash /path/to/skills/cricket-scores/scripts/cricket-alert.sh

# Or use OpenClaw cron:
# Schedule cricket-alert.sh to run during IPL match times (7-11 PM IST)
```

The alert script tracks state in `/tmp/cricket-alert-state.json` and only outputs when something new happens (wicket, century, match result).

---

## 📊 API Quota Management

| Tier | Calls/Day | Cost |
|------|-----------|------|
| Free | 100 | $0 |
| Pro | 2,000 | $5.99/mo |

### How Caching Helps
All scripts cache API responses locally in `/tmp/cricket-cache/`:
- **Live scores:** 2 min TTL (fresh during matches)
- **Upcoming/Results:** 30 min TTL
- **Series info:** 24 hour TTL
- **Scorecards:** 5 min TTL

### Budget During a Match Day
~10 list calls + ~50 score checks + 40 ad-hoc = **100 calls** (fits free tier)

### When Quota is Exhausted
Scripts show a clear message: *"API quota exhausted (100 calls/day limit reached). Try again tomorrow or upgrade."*

---

## 📂 Output Format

All output is messaging-friendly:
- No markdown tables (works on WhatsApp, Discord, Telegram)
- Bullet point lists with emoji
- Times converted to IST
- Match IDs included for drill-down

---

## 📋 Requirements

- **bash** 4.0+
- **curl** (usually pre-installed)
- **jq** — `apt install jq` or `brew install jq`
- **CricketData.org API key** (free) — sign up at [cricketdata.org](https://cricketdata.org)

---

## 🔒 Security Notes

- **API key in URL query parameter:** The CricketData.org API (`api.cricapi.com`) requires the API key to be passed as a URL query parameter (`?apikey=...`). This means the key may appear in shell history, process listings, server access logs, and any HTTP proxy/inspection logs. Mitigations:
  - Set the key via the `CRICKET_API_KEY` environment variable (not hardcoded in config files).
  - Use the **free tier key** for this skill — it has limited scope and can be rotated easily.
  - Avoid running scripts in shared/multi-tenant environments where process arguments are visible to other users.
  - The CricketData.org API does **not** support header-based authentication, so query-param passing is unavoidable.

---

## 📄 License

MIT — see [LICENSE](LICENSE)