airnz-flights
Search public Air New Zealand fare snapshots and timetable fallback data through a lightweight no-login CLI. Use when the task involves Air NZ route/date fare snapshots, fare products, flight numbers,
SKILL.mdskills/airnz-flights/SKILL.md
GitHubAir New Zealand Flights
Goal
Query live public Air New Zealand fare snapshots when the anonymous browser-style search is accepted, with a public timetable fallback when Air NZ returns request-auth/CAPTCHA.
Use this when
- A user asks to search current Air New Zealand flights by origin, destination, and date
- A user wants a public timetable snapshot for NZ domestic or Air NZ-served routes
- A workflow needs flight times, flight numbers, duration, stops, or booking-search handoff URLs
- An agent is comparing public airline availability without logging in or holding seats
Do not use this for
- Booking, payment, seat selection, fare holds, checkout, Airpoints login, manage-booking, refund/change actions, or passenger details
- Private/authenticated booking data
- High-volume scraping, fare-history warehousing, or bypassing Air NZ controls
- Claims about final payable totals; prices, when returned, are pre-checkout fare snapshots only
Preferred workflow
- Ask for or infer IATA airport codes and a specific departure date.
- Run
scripts/cli.py ORIGIN DESTINATION YYYY-MM-DDwith the narrowest useful query. - Prefer
--browseron headless servers or anti-bot-sensitive workflows when CloakBrowser is installed; if it is not installed, the CLI returnscloakbrowser_not_installedso the agent can recommend installation. - Use
--directif only direct services are useful. - Use
--limitfor concise human output or--jsonfor agent chaining. - Treat results as live snapshots: fares/schedules can change without notice.
- If JSON includes
fare_search_blocked: true, Air NZ returned request-auth/CAPTCHA and the CLI has fallen back to schedules only. - Send users to the returned booking search URL if they want to complete a booking themselves.
CLI
Run from the repository root:
python3 skills/airnz-flights/scripts/cli.py <origin> <destination> <date> [flags]
Examples:
python3 skills/airnz-flights/scripts/cli.py AKL WLG 2026-07-13 --limit 5
python3 skills/airnz-flights/scripts/cli.py AKL WLG 2026-07-13 --browser --limit 5
python3 skills/airnz-flights/scripts/cli.py AKL CHC 2026-07-13 --browser --json
python3 skills/airnz-flights/scripts/cli.py WLG ZQN 2026-08-04 --direct
Flags
--direct— direct flights only--adults N— adult passenger count for the fare-search attempt--browser— use optional CloakBrowser headless mode; if unavailable, returnscloakbrowser_not_installedfor agents to surface as an installation recommendation--limit N— max rows in human output--json— emit machine-readable JSON
Resources
- CLI entrypoint:
scripts/cli.py - Live smoke test:
scripts/smoke_test.sh - API/source notes:
references/api-notes.md
Notes
- Python Playwright is required for the timetable fallback because Air NZ's same public timetable feed can return empty results to bare non-browser clients while returning the public schedule in a normal browser context.
- The CLI first attempts the browser-sniffed anonymous fare-search flow (
/vbook/ajax/bui/flights/search→selectitinerary) and parses embeddedlegOptionsprices when Air NZ accepts the request. - If Air NZ returns request-auth/CAPTCHA, the CLI falls back to
/feeds/flight-timetablesand marksfare_search_blocked: true. --browseris optional, not mandatory. It imports CloakBrowser only when requested, so normal validation/smoke runs still work on clean hosts.- If
--browser --jsonis requested and CloakBrowser is missing, the CLI returns a machine-readablecloakbrowser_not_installederror plus an installation recommendation instead of pretending the browser path ran. - The CLI deliberately stops before fare selection; it does not create a booking session, hold seats, or progress to checkout.
- Keep usage narrow and respectful.