Metadata-Version: 2.4
Name: avios-cli
Version: 0.4.3
Summary: A CLI and TUI for Avios balances, transactions, and BA reward-flight availability.
Project-URL: Homepage, https://github.com/alexechoi/avios-cli
Project-URL: Repository, https://github.com/alexechoi/avios-cli
Project-URL: Issues, https://github.com/alexechoi/avios-cli/issues
Author: Alex Choi
License-Expression: MIT
License-File: LICENSE
Keywords: avios,british-airways,cli,loyalty,terminal,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: browser-cookie3>=0.19
Requires-Dist: httpx>=0.27
Requires-Dist: playwright>=1.44
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: textual>=0.80
Requires-Dist: typer>=0.12
Provides-Extra: login
Description-Content-Type: text/markdown

# avios-cli

[![CI](https://github.com/alexechoi/avios-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/alexechoi/avios-cli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

A **CLI and TUI for your Avios programmes** — check balances, browse transactions,
and search British Airways reward-flight availability without leaving the terminal.
British Airways, Iberia, and Aer Lingus use avios.com; Finnair Plus uses Finnair's
own OAuth and loyalty API.

> ⚠️ **Unofficial.** This project is not affiliated with, authorised by, or endorsed by
> Avios, British Airways, Finnair or IAG Loyalty. It drives the same private endpoints
> the providers' websites use, with your own logged-in session. Use at your own risk;
> it may break at any time and may be against the provider's terms of service.

![avios TUI dashboard](docs/dashboard.svg)

<sub>The <code>avios tui</code> dashboard (demo data). Regenerate with <code>uv run python scripts/screenshot.py</code>.</sub>

![avios reward-flight search](docs/reward-flights.svg)

<sub>Direct BA reward-seat availability by date and cabin (synthetic demo data).</sub>

## Status

Early alpha, built in the open. See the [roadmap](#roadmap).

## Install

Requires Python 3.10+.

```bash
uvx avios-cli --help     # run without installing
# or install it, then use the `avios` command:
pip install avios-cli
avios --help
```

Or from source, for development:

```bash
git clone https://github.com/alexechoi/avios-cli
cd avios-cli
uv sync
uv run avios --help
```

## Log in

avios.com has no credential API — login is Auth0 Universal Login behind hCaptcha and
SMS/passkey MFA — so `avios login` opens a real browser, **waits while you finish
logging in** (password, captcha, SMS code), and captures the session once you land
on the dashboard:

```bash
uvx avios-cli login
uvx avios-cli login iberia
uvx avios-cli login finnair
```

It launches your installed **Google Chrome** (no download). If you don't have
Chrome, it fetches Playwright's Chromium automatically on first login (~150 MB,
one-time). No extra flags — browser support ships in the package.

> Tip: if you'll use it often, `uv tool install avios-cli` once, then just run
> `avios login`, `avios balance`, etc. directly.

Prefer not to open a browser? Import the cookie from a Chrome you're already logged
into avios.com with:

```bash
uvx avios-cli login --from-browser
```

This scans **all your Chrome profiles** and uses whichever one is actually logged
into avios.com (it tells you which). If you have several profiles, you can target
one directly:

```bash
uvx avios-cli login --from-browser --profile "Profile 1"
```

**Stuck in an endless captcha loop?** That's bot detection on the automated
browser. Use `--from-browser` instead: log into avios.com in your normal Chrome
(you'll get one normal captcha), then run `uvx avios-cli login --from-browser`.

Finnair uses a different CAS/OAuth flow. `avios login finnair` opens the Finnair Plus
balance page, lets you complete password and MFA in the real browser, and captures the
OAuth session from the authenticated loyalty request. `--from-browser` is not available
for Finnair because browser-cookie import cannot read that token.

Each programme session is stored at `~/.config/avios/accounts/<programme>.json`
(mode `600`). Sessions expire; just log in to that programme again. Use
`avios logout <programme>` for one account or `avios logout` for all accounts.
For BA, browser-assisted login also opens the separate reward-flight application.
British Airways may show a second login prompt; keep the browser open until the
CLI confirms success. Reward searches drive the site's own form in a background
Chrome window because the flight-search route rejects plain HTTP and automated
headless requests, so the `login` extra remains required when running
`avios flights` or the Reward Flights TUI tab.

## Usage

Commands span **all logged-in accounts** by default and show a combined total; add
`--account/-a <programme>` to focus on one.

```bash
avios accounts                 # every logged-in account: balance + status
avios balance                  # per-account balances + combined total
avios transactions --limit 20  # recent transactions, merged across accounts
avios pending                  # pending Avios, merged across accounts
avios balance --account iberia # just one programme
avios overview                 # dashboard summary
avios whoami                   # name, tier, membership, email
avios raw /shell/api/users/current/accounts   # hit any endpoint directly

# Direct British Airways reward-seat availability:
avios flights LON ABZ --date 2026-11-05
avios flights LON ABZ --date 2026-11-05 --return-date 2026-11-12
avios flights LON ABZ --month 2026-11 --cabin economy --cabin business
avios flights LON ABZ --month 2026-11 --return-month 2026-12 --json
```

Add `--json` to `accounts`, `balance`, `transactions`, `pending`, `whoami`, or
`flights` for scriptable output. With a single account, `balance` keeps the
individual/household breakdown.

## TUI

```bash
avios tui
```

A tabbed full-screen application:

- **Dashboard** — combined balance header and transactions across every account.
- **Reward Flights** — BA date/calendar search with optional reverse-route return,
  cabin/passenger controls, and independent outbound/inbound result tables.

Press `r` to refresh the dashboard and `q` to quit. Reward searches run only when
you press Search or Enter.

Reward search is an unofficial, availability-only view. It currently supports
direct BA flights, three-letter airport/city codes, and seat counts by cabin. It
does not price, book, or show taxes/fees or connecting flights. Return journeys
are two independent one-way searches.

## Roadmap

- [x] Project scaffolding, packaging and CI
- [x] Session + cookie storage layer
- [x] Typed API client (balance, transactions, accounts, profile)
- [x] Browser-assisted `avios login`
- [x] CLI commands
- [x] Textual TUI dashboard
- [x] Multiple accounts (BA, Iberia, Aer Lingus, Finnair) with combined views
- [x] British Airways reward-flight **availability** search (CLI + TUI)

## Development

```bash
uv sync            # installs the project + the `dev` dependency-group
uv run ruff check .
uv run mypy src
uv run pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and
[CHANGELOG.md](CHANGELOG.md) for release notes.

## Security

No passwords are handled or stored — only programme session cookies or OAuth tokens,
kept locally under `~/.config/avios/accounts/` (mode `600`). See
[SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)
