🛫 wayfinder — Travel search for your terminal and your AI agents.

Install

Primary install method:

brew install tksohishi/tap/wayfinder

Secondary fallback method (requires Bun runtime):

bun install -g @tks/wayfinder

Install from source:

git clone https://github.com/tksohishi/wayfinder.git
cd wayfinder
bun install
bun link

Setup

First run:

wayfinder setup

This interactive command explains why the key is needed, where to get it, and saves it to your local config. SerpApi is the API provider wayfinder uses to fetch Google Flights and Google Hotels results.

Advanced alternatives:

Set API key by environment variable:

export SERPAPI_API_KEY="your_key"

Or store it in ~/.config/wayfinder/config.json:

{
  "serpApiKey": "your_key"
}

Usage examples

Search one way flights:

wayfinder flights --from SFO --to JFK --date 2026-04-10

Search up to 3 departure dates in one command:

wayfinder flights --from SFO --to JFK --date 2026-04-10 --date 2026-04-11 --date 2026-04-13

Search with filters:

wayfinder flights --from LAX --to SEA --date 2026-04-10 --airline AS --max-stops 0 --max-price 250 --depart-after 06:00 --depart-before 12:00

Exclude basic economy fares:

wayfinder flights --from SFO --to JFK --date 2026-04-10 --exclude-basic

Structured output for scripting:

wayfinder flights --from SFO --to JFK --date 2026-04-10 --json | jq '.results[] | {price,airline,stops}'

Get booking links from selected flight tokens:

wayfinder flights booking --from LAS --to JFK --date 2026-05-29 --token "<TOKEN_1>" --token "<TOKEN_2>" --json

Search hotels:

wayfinder hotels --where "New York, NY" --check-in 2026-04-10 --check-out 2026-04-12

Search hotels with price and rating filters:

wayfinder hotels --where "Tokyo" --check-in 2026-04-10 --check-out 2026-04-13 --adults 2 --min-price 120 --max-price 300 --rating 4

Search family-friendly hotels with cancellation and class filters:

wayfinder hotels --where "Tokyo" --check-in 2026-04-10 --check-out 2026-04-13 --adults 2 --children 2 --children-ages 4,7 --free-cancellation --hotel-class 4,5

Structured hotel output for scripting:

wayfinder hotels --where "Paris" --check-in 2026-04-10 --check-out 2026-04-12 --json | jq '.results[] | {name,nightlyPrice,rating}'

Search nearby restaurants from a location:

wayfinder places --near "Shinjuku, Tokyo"

Use a specific location name for better relevance:

wayfinder places --near "Domino Park, Brooklyn, NY"

Search nearby coffee spots:

wayfinder places --near "Shinjuku, Tokyo" --type coffee --limit 5

Narrow results to walking-distance intent:

wayfinder places --near "Domino Park, Brooklyn, NY" --range walk

Structured places output for scripting:

wayfinder places --near "Shinjuku, Tokyo" --type coffee --json | jq '.results[] | {name,rating,reviews,googleMapsUrl}'