better-flight-cli

Flight search should optimize for more than price. This CLI explores fare class, loyalty miles, and booking channel risk as first-class decision factors, built for agentic workflows.

Note: This was a brief exploration into CLI-based flight data. It is no longer actively maintained. The Amadeus Self-Service portal will be decommissioned on July 17, 2026, which means the fare class, miles, and booking channel features will stop working after that date. Treat this as a reference, not a dependency.

Google Flights mode (no API key)

$ flights search --to NRT --date 2026-05-01 --airline CX --top 3

              Flights HKG → NRT | 2026-05-01 | Price level: Low
┌──────────────────────┬───────────┬─────────────────────┬──────────┬─────────┬──────────┐
│ Flight               │ Route     │ Schedule            │ Duration │ Stops   │    Price │
├──────────────────────┼───────────┼─────────────────────┼──────────┼─────────┼──────────┤
│ Cathay Pacific CX520 │ HKG → NRT │ 08:15 → 13:30      │ 4h 15m   │ nonstop │  HK$2,180│
│ Cathay Pacific CX524 │ HKG → NRT │ 14:45 → 19:55      │ 4h 10m   │ nonstop │  HK$2,340│
│ Cathay Pacific CX500 │ HKG → NRT │ 00:05 → 05:25      │ 4h 20m   │ nonstop │  HK$2,580│
└──────────────────────┴───────────┴─────────────────────┴──────────┴─────────┴──────────┘

Amadeus mode (fare class + miles + booking channel)

$ flights search --to NRT --date 2026-05-01 --airline CX --amadeus --top 3

          Flights HKG → NRT | 2026-05-01 | Amadeus
┌──────────────────────┬───────────┬────────────────┬──────────┬─────────┬──────────┬───────┬───────┬───────┬───────────────┐
│ Flight               │ Route     │ Schedule       │ Duration │ Stops   │    Price │ Class │ Miles │ Seats │ Channel       │
├──────────────────────┼───────────┼────────────────┼──────────┼─────────┼──────────┼───────┼───────┼───────┼───────────────┤
│ Cathay Pacific CX520 │ HKG → NRT │ 08:15 → 13:30 │ 4h 15m   │ nonstop │ HKD 2,180│   K   │   720 │     9 │ CX direct ✓   │
│ Cathay Pacific CX520 │ HKG → NRT │ 08:15 → 13:30 │ 4h 15m   │ nonstop │ HKD 2,050│   K   │   720 │     9 │ OTA ⚠         │
│ Cathay Pacific CX524 │ HKG → NRT │ 14:45 → 19:55 │ 4h 10m   │ nonstop │ HKD 2,340│   Y   │ 1,800 │     4 │ CX direct ✓   │
└──────────────────────┴───────────┴────────────────┴──────────┴─────────┴──────────┴───────┴───────┴───────┴───────────────┘
Amadeus: 42/2000 calls used this month

The Amadeus output shows the same CX520 flight twice: once via direct booking (HKD 2,180) and once via OTA (HKD 2,050). The OTA is cheaper, but the direct booking gives you better protection if things go wrong. The Y-class CX524 costs more but earns 2.5x the status miles.

Install

git clone https://github.com/patrick-yip/better-flight-cli.git
cd better-flight-cli
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

For the full experience (fare class, miles, booking channel), you need an Amadeus API key (free tier: 2,000 requests/month):

export AMADEUS_CLIENT_ID="your_client_id"
export AMADEUS_CLIENT_SECRET="your_client_secret"

Without Amadeus credentials, only the basic Google Flights mode works (price + schedule, no fare class or miles data).

Quickstart

# Quick price check — no API key needed
flights search --to NRT --date 2026-05-01

# Amadeus mode — fare class, miles, booking risk
flights search --to NRT --date 2026-05-01 --airline CX --amadeus

# Direct bookings only, skip OTAs
flights search --to LHR --date 2026-05-01 --amadeus --channel direct

# Compare prices across a date range
flights search --to ICN --date-range 2026-04-01:2026-04-14 --weekday sat

What this explores

Flight search today optimizes for one thing: cheapest price. But for frequent flyers, price is often the least important factor. Fare class determines how many status miles you earn. Booking channel determines whether the airline will help you when things go wrong. Neither is surfaced by Google Flights or Skyscanner.

As flight search moves into agentic workflows (CLI tools, LLM agents, automated pipelines), there's an opportunity to encode these decision factors programmatically:

• Loyalty value over sticker price. A K-class ticket at HKD 720 and a Y-class at HKD 850 look similar in price but earn completely different status miles.
• Booking channel risk. When an airline cancels your OTA-booked flight, the airline's obligation is to the OTA, not you. Direct bookings carry lower risk.
• Structured output for agents. JSON output with fare class, miles, and channel risk lets downstream tools make informed decisions beyond price sorting.

This CLI was an attempt to surface all three in one command, and to explore what flight search looks like when the consumer is an agent, not a human clicking through tabs.

Features

• Two data sources: Google Flights via fast-flights (instant, no key) or Amadeus API (fare class, miles, channel)
• Booking channel flags: CX direct ✓ vs OTA ⚠ at a glance
• Status miles estimates: Marco Polo and KrisFlyer earn rates for CX and SQ
• Multi-date comparison: scan a date range filtered by weekday
• JSON output: --json for scripting and agent workflows

Usage

Flag	Default	Description
--from	HKG	Origin IATA code
--to	required	Destination IATA code
--date	—	Departure date (YYYY-MM-DD)
--return	—	Return date for round-trip
--airline	—	Filter by airline code (CX / SQ)
--class	economy	economy / premium-economy / business / first
--top	5	Show top N results
--amadeus	—	Use Amadeus API for fare class + miles + channel
--channel	all	Filter: direct / ota / all (requires --amadeus)
--json	—	Structured JSON to stdout
--dates	—	Comma-separated dates for comparison
--date-range	—	Range YYYY-MM-DD:YYYY-MM-DD (max 30 days)
--weekday	—	Filter date-range by weekday: mon,tue,sat,...
--book	—	Fetch booking URL via Playwright
--open	—	Open Google Flights in browser

Limitations

• Amadeus API shutdown. The Amadeus Self-Service portal shuts down July 17, 2026. Fare class, miles, and channel features will stop working after that date.
• Two airlines only. CX (Cathay Pacific) and SQ (Singapore Airlines). Adding more requires per-airline adapter work.
• Miles tables are static. Earn rates are hardcoded snapshots; airlines update these periodically.
• Google Flights mode has no fare class. fast-flights scrapes Google Flights, which only exposes cabin type (Economy/Business/First), not fare class codes.
• Rate limits apply. Google Flights may throttle or block automated requests. Amadeus free tier caps at 2,000 calls/month.

Supported airlines

Code	Airline	Direct booking (--book)
CX	Cathay Pacific	Yes
SQ	Singapore Airlines	Yes

License

MIT © 2026 Patrick Yip