Rugbyclaw 🏉

A CLI tool for rugby scores, fixtures, and results powered by API-Sports Rugby API.

Clean architecture, reliable data, Rugby Union focus.

Features

• Live scores — Today's matches across your favorite leagues
• Fixtures — Upcoming matches with dates and times
• Results — Recent results with personality-driven summaries
• Team tracking — Follow specific teams across competitions
• Calendar export — Add matches to your calendar (ICS format)
• News — Rugby news right in your terminal
• Smart follow-ups — After commands, suggests the best next action (calendar, team tracking, diagnostics)

Documentation

📖 Full Documentation - Command reference, guides, and troubleshooting

• Getting Started - Install and configure in 5 minutes
• Commands Reference - Detailed command documentation
• Troubleshooting - Common issues and solutions
• AI & Agent Docs - machine-readable contracts and feeds

Agent-Friendly Endpoints

• https://rugbyclaw.com/llms.txt — compact LLM index
• https://rugbyclaw.com/llms-full.txt — expanded machine context
• https://rugbyclaw.com/docs/agent.json — JSON capability manifest
• https://rugbyclaw.com/docs/updates.xml — docs updates RSS
• https://github.com/pocarles/rugbyclaw/releases.atom — canonical releases feed
• https://github.com/pocarles/rugbyclaw/commits/main.atom — canonical commits feed

Installation

npm install -g rugbyclaw

Quick Start

# Beginner setup (recommended)
rugbyclaw start

# Check today's scores
rugbyclaw scores

# Upcoming Top 14 fixtures
rugbyclaw fixtures top14

# Toulouse's next match
rugbyclaw team toulouse next

# Recent Champions Cup results
rugbyclaw results champions_cup

Setup

Run rugbyclaw start for the fastest setup:

• No API key required (free mode)
• Uses recommended leagues automatically
• Skips optional team picking
• Confirms timezone from a menu
• Runs a quick post-setup health check

Need full control? Run rugbyclaw config --guided.

rugbyclaw config also supports advanced setup:

• No API key required (free mode uses a proxy with limits)
• (Optional) add your API-Sports Rugby API key (get yours at api-sports.io)
• Select favorite leagues (free mode is limited to default leagues)
• (Optional) pick favorite teams
• Set your timezone (IANA name like America/New_York)

Tip (automation/agents): override timezone per command:

rugbyclaw --tz America/New_York fixtures

Disable follow-up command hints when needed:

rugbyclaw fixtures --no-followups

API key is stored securely in ~/.config/rugbyclaw/secrets.json (mode 600).

Commands

rugbyclaw start

Beginner-first setup wizard:

• Quick mode by default (few prompts)
• Use --guided for full customization

rugbyclaw start
rugbyclaw start --guided
# non-interactive (for agents/OpenClaw)
rugbyclaw start --yes --tz America/New_York --mode proxy
# machine-safe JSON for agents
rugbyclaw start --yes --tz America/New_York --mode proxy --agent

rugbyclaw config

Interactive setup wizard:

• Choose free mode (default) or add an API key (optional)
• Select favorite leagues
• (Optional) add favorite teams
• Set your timezone

rugbyclaw scores

Show today's matches across your favorite leagues.

rugbyclaw scores
rugbyclaw scores --json  # JSON output for scripts

rugbyclaw fixtures [league]

List upcoming matches.

rugbyclaw fixtures              # All favorites
rugbyclaw fixtures top14        # Specific league
rugbyclaw fixtures -n 10        # Limit to 10 matches

rugbyclaw results [league]

Show recent results with personality-driven summaries.

rugbyclaw results
rugbyclaw results premiership

rugbyclaw standings [league]

Show standings table for one league or across your effective leagues.

rugbyclaw standings
rugbyclaw standings top14
rugbyclaw standings --json

rugbyclaw team <name> <action>

Query a specific team.

rugbyclaw team toulouse next    # Next match
rugbyclaw team toulouse last    # Last result
rugbyclaw team search racing    # Find team ID

rugbyclaw calendar <match_id>

Export a match to ICS calendar format.

rugbyclaw calendar 123456 --stdout > match.ics
rugbyclaw calendar 123456 --out ~/Desktop/match.ics

rugbyclaw notify

Generate notifications for cron/OpenClaw integration.

rugbyclaw notify --weekly   # Weekly digest
rugbyclaw notify --daily    # Day/hour reminders
rugbyclaw notify --live     # Live score updates

rugbyclaw news

Rugby news right in your terminal.

rugbyclaw news                # Today's confirmed stories
rugbyclaw news --since 4h     # Stories from the last 4 hours
rugbyclaw news --since 48h    # Stories from the last 2 days
rugbyclaw news -n 5           # Limit to 5 stories
rugbyclaw news --quiet        # Headlines only
rugbyclaw news --json         # JSON output for scripts

rugbyclaw status

Show current mode (free vs API key), timezone, and effective leagues.

rugbyclaw status
rugbyclaw status --json
rugbyclaw status --agent

rugbyclaw openclaw init

Emit copy/paste-safe bootstrap instructions for OpenClaw agents.

rugbyclaw openclaw init
rugbyclaw openclaw init --json
rugbyclaw openclaw init --agent

Coming Soon

• Additional competitions listed below are planned but not selectable yet.

Supported Leagues

8 competitions covered:

Club Competitions (5)

| Slug | League | |------|--------| | top14 | Top 14 (France) | | premiership | Premiership Rugby (England) | | urc | United Rugby Championship (Multi-nation) | | pro_d2 | Pro D2 (France) | | super_rugby | Super Rugby Pacific (Southern Hemisphere) |

European Cups (2)

| Slug | League | |------|--------| | champions_cup | European Rugby Champions Cup | | challenge_cup | European Rugby Challenge Cup |

International (1)

| Slug | League | |------|--------| | six_nations | Six Nations |

Planned Competitions (Coming Soon)

• Women's Six Nations
• Rugby Championship
• Currie Cup
• NPC
• MLR
• Rugby World Cup

OpenClaw Integration

Rugbyclaw includes an OpenClaw skill for AI-powered natural language queries and proactive notifications.

See skill/SKILL.md for integration details.

JSON / Agent Output

All commands support --json for machine-readable output:

rugbyclaw scores --json | jq '.matches[0]'

For strict automation/OpenClaw, use --agent:

rugbyclaw scores --agent

Agent mode always returns one-line envelopes:

• schema_version
• ok
• exit_code
• error_type
• data
• trace_id

Configuration Files

• ~/.config/rugbyclaw/config.json — User preferences (leagues, teams, timezone)
• ~/.config/rugbyclaw/secrets.json — API key (mode 600)
• ~/.cache/rugbyclaw/ — Response cache (SWR caching for performance)

Technical Details

• Data Provider: API-Sports Rugby API (sole provider)
• Architecture: TypeScript, ES modules, Commander.js CLI
• Caching: SWR (stale-while-revalidate) for performance
• Season Detection: Smart season detection per competition type
• Focus: Rugby Union only

License

MIT