NZ TV Guide

Goal

Answer live New Zealand TV guide questions through a small deterministic CLI with human-readable and JSON output, focused on "when is this sport on, what channel, what time?" workflows.

Use this when

• A user asks what is on Sky Sport, ESPN, Trackside, or another Sky channel
• A user asks when rugby, cricket, Formula 1, football, netball, basketball, NFL, or tennis is on TV in NZ
• A user wants tonight's sport or movie schedule
• A user wants to search current EPG listings by programme, team, sport, or channel name
• A workflow needs lightweight machine-readable NZ TV schedule data

Do not use this for

• Streaming playback, Sky Sport Now account access, subscriptions, purchases, My Sky recording, reminders, or login-gated actions
• Channels outside New Zealand
• Historical TV listings beyond what the live guide sources currently expose
• Republishing EPG listings as a dataset or high-volume scraping
• Claiming a fixture is official if it is not present in the live EPG snapshot

Preferred workflow

1. Run scripts/cli.py with the narrowest subcommand that answers the task
2. Use sport for "what sport is on?" questions and tonight --type sport for the 7pm-late sports window
3. Use now --channel <name> for current channel checks
4. Use search <query> for team, competition, sport, or show lookups across upcoming guide days
5. Use schedule <channel> --date YYYY-MM-DD for a full-day channel listing
6. Use --json for agent chaining, comparisons, or structured reports
7. Mention that listings are live unofficial EPG snapshots and can change at the source

CLI

Run with:

python3 skills/nz-tv-guide/scripts/cli.py <command> [flags]

Commands

• channels [--provider sky|freeview|tvnz] [--type sport|entertainment|news] [--json] - list channels
• now [--channel <name>] [--provider sky|freeview|tvnz] [--json] - show what is on now
• next [--channel <name>] [--provider sky|freeview|tvnz] [--limit N] [--json] - upcoming programmes
• schedule <channel> [--date YYYY-MM-DD] [--provider sky|freeview|tvnz] [--json] - full day schedule for a channel
• search <query> [--date YYYY-MM-DD] [--provider sky|freeview|tvnz] [--limit N] [--json] - find matching programmes
• sport [--code rugby|cricket|football|f1|netball|basketball|nfl|tennis] [--date YYYY-MM-DD] [--from HH:MM] [--to HH:MM] [--provider sky|freeview|tvnz] [--limit N] [--json] - sport programmes, defaulting to Sky Sport
• tonight [--provider sky|freeview|tvnz] [--type sport|movies] [--json] - tonight's 7pm-late sport or movie listings

Examples

python3 skills/nz-tv-guide/scripts/cli.py now --channel "Sky Sport 1"
python3 skills/nz-tv-guide/scripts/cli.py sport --code rugby --date 2026-05-24 --json
python3 skills/nz-tv-guide/scripts/cli.py sport --from 19:00 --to 22:00
python3 skills/nz-tv-guide/scripts/cli.py tonight --type sport
python3 skills/nz-tv-guide/scripts/cli.py search "All Blacks" --limit 10
python3 skills/nz-tv-guide/scripts/cli.py search "Coronation Street" --provider freeview --json
python3 skills/nz-tv-guide/scripts/cli.py schedule "Sky Sport 1" --date 2026-05-24
python3 skills/nz-tv-guide/scripts/cli.py schedule "TVNZ 1" --provider freeview --date 2026-05-24
python3 skills/nz-tv-guide/scripts/cli.py channels --provider sky --type sport --json

Notes

• Detailed endpoint, schema, freshness, and time-zone notes are in references/api-notes.md
• Sky listings come from Sky NZ's public TV Guide at https://tvguide.sky.co.nz/, backed by the no-login https://api.skyone.co.nz/exp/graph EPG GraphQL endpoint used by the website
• Free-to-air listings come from the public Freeview TV Guide page at https://freeviewnz.tv/whats-on/tv-guide/
• --provider tvnz is a convenience filter over Freeview's public TVNZ linear-channel listings; it does not call a separate TVNZ account or streaming API
• Sky Sport, Sky Sport Select, ESPN, Trackside, Sky Arena, and Sky movie/entertainment/news groups are available through Sky channel groups
• Sky Sport NOW streaming-only account or entitlement schedules are not implemented; use Sky linear EPG results as the no-login source of truth
• All displayed times are converted to Pacific/Auckland; human output intentionally does not show UTC
• EPGs are live snapshots and typically refresh at least daily, but programmes can move or be corrected by providers during the day
• No username, password, account cookie, HAR, browser storage, streaming URL, recording, purchase, or mutation endpoint is required or used