travelmaxx 0.1.8

Search award flights across 14 mileage programs from your terminal

travelmaxx

Search award flights across 28 airline mileage programs from your terminal, powered by TravelMaxx.

curl -fsSL https://travelmaxx.app/cli | sh
travelmaxx login
travelmaxx search SFO NRT --date 2026-10-05 --programs ALASKA

Install

Any of:

curl -fsSL https://travelmaxx.app/cli | sh        # auto-detects uv/pipx/pip
uv tool install travelmaxx
pipx install travelmaxx
brew install travelmaxx/travelmaxx/travelmaxx     # once the tap is live

Requires Python 3.10+ (macOS or Linux), an active TravelMaxx subscription, and Roame credentials linked at https://travelmaxx.app/dashboard/settings.

Sign in

travelmaxx login              # opens your browser; click Approve
travelmaxx login --no-browser # headless/SSH: 6-digit code at travelmaxx.app/activate
travelmaxx whoami
travelmaxx logout

Tokens are stored in ~/.config/travelmaxx/credentials.json (chmod 600) and refresh automatically for 30 days. Your Roame credentials never touch this machine — searches run through the TravelMaxx server.

Search

# Single date (always pass --programs when you know them: 40-50x faster)
travelmaxx search SFO NRT --date 2026-10-05 --programs ALASKA

# Business class, 2 passengers, flexible ±2 days
travelmaxx search SFO CDG --date 2026-09-12 --class BUSINESS \
  --programs ALASKA,UNITED --pax 2 --days-around 2

# A whole month in parallel, with a live progress bar
travelmaxx search SFO NRT --date-range november --programs ALASKA

# Explicit range / year / "next year"
travelmaxx search SFO HEL --date-range 2026-09-12:2026-10-18 --programs ALASKA

Options: --sort points|duration, --limit N, --max-wait SECONDS (5–120; results are marked partial if the search returns early), --min-results N, --max-workers N (range searches), --json, --output-file FILE.

Programs

Pass canonical program codes to --programs (common aliases like AVIANCA → LIFEMILES or BA → BRITISH_AIRWAYS are normalized automatically):

• oneworld: ALASKA, AMERICAN, BRITISH_AIRWAYS, CATHAY, FINNAIR, IBERIA, QANTAS, QATAR
• Star Alliance: AEROPLAN, ANA, LIFEMILES, LUFTHANSA, SINGAPORE, TAP, TURKISH, UNITED
• SkyTeam: CLUB_PREMIER, DELTA, FLYING_BLUE, SAS, VIRGIN_ATLANTIC
• Non-alliance: AER_LINGUS, EMIRATES, ETIHAD, GOL, JETBLUE, SPIRIT, VIRGIN_AUSTRALIA

Fastest programs: ALASKA, UNITED, DELTA, JETBLUE, LIFEMILES (1–5 s).

An alliance member program's awards often include flights operated by other airlines in that alliance — searching AMERICAN can surface JAL, Qantas, or British Airways metal. To search a whole alliance, pass the shortcut and it expands to the member programs:

travelmaxx search SFO NRT --date 2026-10-05 --programs ONEWORLD
travelmaxx search JFK CDG --date-range november --programs SKYTEAM
# Shortcuts: ONEWORLD, STAR_ALLIANCE, SKYTEAM

Alerts & discovery

travelmaxx alerts create SFO NRT --class BUSINESS --max-points 75000
travelmaxx alerts list
travelmaxx alerts delete <uuid>
travelmaxx discover --limit 10

JSON output

--json prints the full API response. Single-date searches return {"fares": [...], "percent_completed": 100, "partial": false}; job-based searches return {"status", "percent", "fares_count", "fares", ...}. Each fare:

{
  "departure_date": "2026-10-05",
  "origin": "SFO", "destination": "NRT",
  "mileage_program": "ALASKA",
  "award_points": 75000, "surcharge_usd": 18.1,
  "num_stops": 0, "duration_minutes": 630,
  "cabin_classes": ["BUSINESS"], "operating_airlines": ["JL"],
  "equipment_types": ["77W"], "available_seats": 2, "roame_score": 1684
}

Configuration

Env var	Purpose
TRAVELMAXX_API_URL	Point at a different server (also --server URL)
XDG_CONFIG_HOME	Relocate the config dir (default ~/.config/travelmaxx)

Development

cd cli
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/travelmaxx --server http://localhost:8000 login

Design doc: ../CLI.md. Releases: tag cli-vX.Y.Z (see .github/workflows/release-cli.yml).