nz-trains
Query Wellington Metlink train lines through a lightweight read-only CLI using GTFS and GTFS-RT data. Use when the task involves Johnsonville, Kapiti, Hutt Valley, Melling, or Wairarapa Line stations,
SKILL.mdskills/nz-trains/SKILL.md
GitHubNZ Trains
Goal
Query live Wellington train data from Metlink GTFS and GTFS-RT endpoints through a small deterministic CLI with human-readable and JSON output.
Use this when
- A user asks about Wellington Metlink train lines: JVL, KPL, HVL, MEL, or WRL
- A user wants next train arrivals from a Wellington region station
- A user asks about live train delays, cancellations, or vehicle positions
- A user asks about train-specific Metlink service alerts
- A workflow needs machine-readable Wellington train status data
Do not use this for
- Wellington buses; use
nz-buses - Auckland public transport; use
at-transport - KiwiRail long-distance services such as Northern Explorer, Coastal Pacific, or TranzAlpine
- Fares, ticketing, journey planning, or historical performance analysis
- Mutating bookings, accounts, cards, alerts, or Metlink data
Preferred workflow
- Set
METLINK_API_KEYin the environment before running data commands - Run
scripts/cli.pywith the narrowest subcommand that answers the task - Use
linesfor a quick network snapshot - Use
arrivalsorstationfor stop-specific next trains - Use
delays,vehicles, andalertsfor operational status - Use
--jsonfor agent chaining, comparisons, or structured reports
Setup
Requires a Metlink Open Data API key.
export METLINK_API_KEY=your_key_here
The CLI reads os.environ["METLINK_API_KEY"]. There is no fallback key.
CLI
Run with:
python3 skills/nz-trains/scripts/cli.py <command> [flags]
Commands
lines [--json]- list Wellington train lines with current delay, alert, and vehicle countsline <name> [--json]- detail for one line; accepts codes likeWRLor names likeWairarapastations [--line <name>] [--json]- train stations, optionally filtered to one linestation <stop-id-or-name> [--limit N] [--json]- station detail with next train arrivalsarrivals <station> [--limit N] [--json]- next live train arrivals at a station; accepts stop ID or namedelays [--line <name>] [--limit N] [--json]- current late or cancelled train tripsvehicles [--line <name>] [--limit N] [--json]- live train positions with lat/lonalerts [--line <name>] [--limit N] [--json]- active train-specific service alerts
Examples:
python3 skills/nz-trains/scripts/cli.py lines
python3 skills/nz-trains/scripts/cli.py line WRL --json
python3 skills/nz-trains/scripts/cli.py stations --line KPL
python3 skills/nz-trains/scripts/cli.py arrivals WELL --limit 8
python3 skills/nz-trains/scripts/cli.py station Masterton --json
python3 skills/nz-trains/scripts/cli.py delays --line Wairarapa
python3 skills/nz-trains/scripts/cli.py vehicles --line KPL --json
python3 skills/nz-trains/scripts/cli.py alerts --line HVL
Resources
- CLI entrypoint:
scripts/cli.py - API and stability notes:
references/api-notes.md
Notes
- Upstream source: Metlink Open Data API
- API key required - set
METLINK_API_KEY; never commit keys or.envfiles - Python stdlib only; no package install, browser automation, account login, or write actions
- Filters routes to GTFS
route_type=2and the five Wellington train route codes only WELLis the Wellington Station parent stop ID; numeric city bus stops such as5000are not train stations- Wairarapa Line (
WRL) covers the long-distance Metlink rail service to Masterton