flightclaw-go

README

Flightclaw

Flightclaw is a pure-Go command-line client for comparing live Google Flights headline fares. It supports airport and city codes, multiple dates, independent one-way return searches (including open-jaw trips), filtering, complete segment details, and stable JSON output.

Requirements and installation

Flightclaw requires Go 1.25 or later and has no additional language runtime dependency.

Build in the repository:

go build -o flightclaw ./cmd/flightclaw
./flightclaw --help

Or install it as flightclaw on your GOBIN/GOPATH:

go install github.com/dhruvkelawala/flightclaw-go/cmd/flightclaw@latest

Usage

At least one outbound date is required:

flightclaw --from CODE --to CODE (--date YYYY-MM-DD | --dates DATE,DATE) [flags]

Airport and city codes are case-insensitive three-letter IATA-style codes.

Flags

Flag	Shorthand	Description	Default
--from	-f	Outbound airport or city code	LGW
--to	-t	Outbound destination airport or city code	FNC
--date	-d	One outbound date (YYYY-MM-DD)	required unless --dates
--dates		Comma-separated alternative outbound dates
--return	-r	One independent return date
--return-dates		Comma-separated alternative return dates
--return-from		Return origin (for open-jaw trips)	outbound destination
--return-to		Return destination (for open-jaw trips)	outbound origin
--results		Maximum itineraries to print	5
--adults		Adult travelers	1
--direct		Nonstop journeys only	false
--max-duration		Maximum duration for each one-way journey (Go duration, e.g. 4h)	none
--outbound-depart-after		Earliest local outbound departure (HH:MM)	none
--outbound-arrive-after		Earliest local outbound arrival (HH:MM)	none
--outbound-arrive-before		Latest local outbound arrival (HH:MM)	none
--return-depart-after		Earliest local return departure (HH:MM)	none
--return-arrive-before		Latest local return arrival (HH:MM)	none
--json		Emit only structured JSON; warnings are embedded in it	false
--timeout		Overall search timeout (Go duration)	45s

--date and --dates are mutually exclusive, as are --return and --return-dates.

Examples

One-way airport search:

flightclaw --from LTN --to FCO --date 2026-09-13 --results 3

Multiple outbound dates:

flightclaw --from LON --to ROM --dates 2026-09-13,2026-09-14 --results 10

Independent return search:

flightclaw -f LHR -t JFK -d 2026-09-13 -r 2026-09-26 --adults 2

Open-jaw trip with alternative return dates:

flightclaw --from LON --to ROM --date 2026-09-13 \
  --return-from NAP --return-to LON \
  --return-dates 2026-09-26,2026-09-27 --results 5

Direct flight with local-time and duration filters:

flightclaw --from LON --to ROM --date 2026-09-13 --direct \
  --outbound-depart-after 08:00 --outbound-arrive-after 15:00 \
  --outbound-arrive-before 22:00 --max-duration 4h

Automation-safe JSON:

flightclaw --from LTN --to FCO --date 2026-09-13 --results 1 --json | jq .

City aliases

Flightclaw expands each city alias into one provider query per date:

• LON: LHR, LGW, STN, LTN, LCY, SEN
• NYC: JFK, LGA, EWR
• PAR: CDG, ORY, BVA
• ROM: FCO, CIA
• MIL: MXP, LIN, BGY
• TYO: HND, NRT
• OSA: KIX, ITM, UKB
• SEL: ICN, GMP
• BJS: PEK, PKX
• SHA: PVG, SHA
• CHI: ORD, MDW
• WAS: IAD, DCA, BWI
• BUE: EZE, AEP

Fare and search caveats

• Results are live headline fares and can change between searches. They may exclude checked or cabin baggage, seat selection, payment, or other airline fees.
• Return and open-jaw totals are the sum of two independently searched one-way headline fares. They can differ from an airline's round-trip price.
• Flightclaw links to Google Flights for booking/search continuation; it does not book or purchase travel.
• Google Flights uses an undocumented internal endpoint, so availability can occasionally fail or change.

A separate scheduled live smoke test searches a high-availability route each day. It is intentionally kept out of pull-request CI: its purpose is to detect breakage in the undocumented Google Flights payload without making upstream availability a merge gate.

License

Flightclaw is available under the MIT License.