American Airlines

# 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

1. Run the script in the background (nohup ... &, disown)
2. Poll stderr for "2FA REQUIRED" to confirm the code was sent
3. Ask the user for the 6-digit code AA emailed them
4. Write the code to the code file: echo "123456" > /tmp/aa-2fa-code.txt
5. 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_COMMAND to 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.txt every 2 seconds. Write the 6-digit code there.
• Direct flag: --code 123456 if 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"
}

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=False is 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_COMMAND to 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.