Metadata-Version: 2.4
Name: travelmaxx
Version: 0.1.7
Summary: Search award flights across 14 mileage programs from your terminal
License-Expression: MIT
Project-URL: Homepage, https://travelmaxx.app
Project-URL: Documentation, https://travelmaxx.app/cli/docs
Keywords: awards,flights,miles,points,travel
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"

# travelmaxx

Search award flights across 28 airline mileage programs from your terminal,
powered by [TravelMaxx](https://travelmaxx.app).

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

## Install

Any of:

```sh
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

```sh
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

```sh
# 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:

```sh
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

```sh
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:

```json
{
  "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

```sh
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`).
