american-airlines
Check American Airlines AAdvantage balance, elite status, and loyalty points via Patchright. Handles email 2FA with 6-box code entry. Uses persistent browser profiles to skip 2FA on subsequent runs.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 978
- Forks
- 120
01 前言 Front Matter
- name
- american-airlines
- api_key
- None (requires Patchright)
- summary
- AAdvantage balance and elite status. AwardWallet does not support AA.
- category
- loyalty
- description
- Check American Airlines AAdvantage balance, elite status, and loyalty points via Patchright. Handles email 2FA with 6-box code entry. Uses persistent browser profiles to skip 2FA on subsequent runs.
- docker_image
- ghcr.io/borski/aa-miles-check
02 资源文件 2
- 其他Dockerfile328 B
- 脚本scripts/check_balance.py21.7 KB
03 SKILL.md 正文
American Airlines AAdvantage
Check AAdvantage award miles balance, elite status (Gold/Platinum/Platinum Pro/Executive Platinum), loyalty points, and million miler status. Uses Patchright (undetected Playwright fork) because AA blocks standard browser automation.
Requires Patchright. AA.com blocks vanilla Playwright and agent-browser.
Prerequisites
pip install patchright && patchright install chromium
Or use Docker (no local install needed):
docker pull ghcr.io/borski/aa-miles-check:latest
# or build locally:
docker build -t aa-check skills/american-airlines/
Usage
Pass credentials via environment variables or flags. If you use a secrets manager (1Password, Vault, etc.), inject them however you normally would.
# Environment variables
AA_USERNAME=your_aa_number AA_PASSWORD=your_password \
python3 scripts/check_balance.py --json
# Flags
python3 scripts/check_balance.py --username YOUR_AA_NUMBER --password YOUR_PASSWORD --json
# Docker
docker run --rm -e AA_USERNAME=your_aa_number -e AA_PASSWORD=your_password aa-check --json
2FA Handling
AA requires email verification on first login from a new device. The script waits up to 120 seconds for the code.
You (the agent) do NOT have access to the user's email. AA sends the 2FA code to the account holder's email address. When the script hits 2FA, you MUST ask the user for the 6-digit code. This is not optional. Do not try to read their email. Do not guess. Do not skip. Ask them, wait for the answer, then write it to the code file.
Agent workflow
- Run the script in the background (
nohup ... &,disown) - Poll stderr for
"2FA REQUIRED"to confirm the code was sent - Ask the user for the 6-digit code AA emailed them
- Write the code to the code file:
echo "123456" > /tmp/aa-2fa-code.txt - Wait for the script to complete and read stdout for the JSON result
Persistent profiles (skip 2FA on repeat runs)
Use --profile name to save browser cookies. After the first successful 2FA, subsequent runs with the same profile skip 2FA entirely. Profiles are stored at ~/.aa-browser-profiles/{name}/. Sessions last hours, not days.
# First run: will need 2FA
python3 scripts/check_balance.py --profile user1 --json
# Later runs: same profile, no 2FA
python3 scripts/check_balance.py --profile user1 --json
Code input methods
- Command hook: Set
AA_2FA_COMMANDto a command that blocks until it has the code, then prints it to stdout. The script runs this first before falling back to file polling. - File (default): Script polls
/tmp/aa-2fa-code.txtevery 2 seconds. Write the 6-digit code there. - Direct flag:
--code 123456if you already have the code before running. - Custom file path:
--code-file /path/to/code.txt
Output
{
"username": "XXXXXXX",
"status": "completed",
"miles": 123425,
"elite_status": "Platinum Pro",
"loyalty_points": 180,
"name": "John Doe",
"aadvantage_number": "XXXXXXX",
"million_miler": 19328,
"member_since": "Aug 23, 2011"
}
| Field | Description |
|---|---|
miles |
Award miles balance (redeemable) |
elite_status |
Gold, Platinum, Platinum Pro, or Executive Platinum (null if none) |
loyalty_points |
Current year loyalty points (reset March 1) |
million_miler |
Lifetime miles toward Million Miler status |
member_since |
Account creation date |
When to Use
- Checking AA miles balance (AwardWallet doesn't support AA)
- Verifying elite status tier and expiration
- Tracking loyalty points toward next status level
- Comparing AA award availability against balance (combine with seats-aero)
When NOT to Use
- Booking flights. Read-only. Does not modify anything.
- Other airlines. Use AwardWallet for airlines it supports.
Implementation Notes
- AA uses 6 separate input boxes for 2FA codes (one digit per box). The script types each digit individually with auto-advance.
- Cookie consent banners are removed via JS before interacting with the Verify button.
- The Verify button requires Tab+Enter to submit (neither JS
.click()nor Playwright.click()produce a trusted pointer event that AA's React app accepts). headless=Falseis required. AA detects headless browsers even with Patchright. Docker uses xvfb for a virtual display.
Limitations
- 2FA on first use per profile. No way around it. AA sends an email code. Set
AA_2FA_COMMANDto automate code retrieval. - Session expiry. Persistent profiles last hours, not days. Long gaps between runs may require 2FA again.
- Headed mode required. Opens a Chrome window locally. Use Docker for no popup.
04 同仓库更多 Skills
wikipedia-airports
Discover destinations served from any airport via Wikipedia. Sanity-check whether an airline flies a specific route, find regional service that fare tools miss, identify late-split-return airport options.
wheretocredit
Mileage earning rates by airline and booking class via wheretocredit.com. Redeemable and qualifying miles across 50+ programs. Use when deciding where to credit a flight or comparing earning rates.
vrbo
Search VRBO (Vrbo / Expedia Group) vacation rentals including entire homes, condos, and cabins via Patchright browser automation. VRBO sits behind Akamai Bot Manager so plain HTTP and standard Playwright get a 429 bot wall. Use for whole-home or group stays, multi-bedroom rentals, and Airbnb-vs-VRBO comparisons. Trigger phrases include search VRBO, Vrbo rentals, vacation rental, cabin rental, whole house, condo for the group.
tripadvisor
TripAdvisor Content API for hotel ratings, restaurant search, attraction reviews, rankings, and nearby locations. Use when evaluating hotels or researching destinations. 5K calls/month.
trip-planner
Full trip planning orchestration. Combines flight search, hotel search, and points optimization into one cost analysis. Use when the user says "plan a trip" or wants the complete picture for a destination.
trip-log
Save flight searches, itineraries, and booked trips to the trips/logs/ directory for future reference. OPT-IN — use when the user asks to log a trip or look up past searches, or on every search only if the user has said they want automatic logging. Also use to update status when a trip is booked or completed.