🏏 Cricket Scores v1.0.0

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 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 — 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

export CRICKET_API_KEY="your-api-key-here"
# Add to your shell profile or ~/.openclaw/.env for persistence

3. Run Any Script

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 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 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 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 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 scripts/match-details.sh <match-id>

Get match IDs from live-scores or search results.

Search Matches

bash scripts/search-match.sh "India vs Australia"
bash scripts/search-match.sh "MI vs CSK"

Cricket Alerts (Cron)

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).

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:

# 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
• python3 — used by helper/parsing scripts
• CricketData.org API key (free) — sign up at 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