Flight Weather Briefing

Generate a comprehensive aviation weather briefing by running the FlightWeatherWatch CLI tool.

Project Location

The project root is the directory containing flightweather.py. All commands must be run from this directory.

Command

python3 flightweather.py <ORIGIN> [WAYPOINTS...] <DESTINATION> <DATE> <TIME_UTC> <ALTITUDE_FT> [options]

Positional Arguments (in order)

• ORIGIN: Departure ICAO airport code (e.g., KSQL, KMQY)
• WAYPOINTS (optional): Intermediate stops — fuel stops, diversions, or routing waypoints
• DESTINATION: Arrival ICAO airport code
• DATE: Departure date as YYYY-MM-DD
• TIME_UTC: Departure time as HH:MM in UTC (Zulu)
• ALTITUDE_FT: Cruise altitude in feet MSL (integer)

Options

Interpreting User Requests

Airport Codes

Convert names/cities to 4-letter ICAO codes (K-prefixed in the US). The user's commonly used airports:

• Nashville area → KMQY (Smyrna/Rutherford County — the user's preferred Nashville airport)
• Austin → KEDC (Austin Executive)
• San Carlos → KSQL
• Las Vegas → KVGT (North Las Vegas)
• Denver metro → KBJC (Rocky Mountain Metropolitan)

For unfamiliar airports, look up the ICAO code before running.

Local Time → UTC

The user gives departure in local time at the departure airport. Convert to UTC based on the airport's timezone. DST is active from the second Sunday of March through the first Sunday of November.

Fuel Stops / Waypoints

If the user mentions a fuel stop or intermediate point, insert it as a waypoint between origin and destination. Example: "stop at Amarillo" → add KAMA between origin and destination.

Always Use --cache

Always include --cache so the briefing can be re-rendered from cache without re-fetching charts or calling the API.

Re-running from Cache

To rebuild a briefing from cached data (no API cost):

1. Find the cache file: ls cache_*.json — files are named cache_ORIGIN_DEST_DATE_charts.json
2. Run with --from-cache using the prefix (without _charts.json or _llm.json):

python3 flightweather.py --from-cache cache_KMQY_KEDC_2026-03-16 KMQY KEDC 2026-03-16 15:00 12000 --tas 170

Note: --from-cache still requires the positional arguments (origin, destination, date, time, altitude) because they're used for the HTML header and route overlay. The --from-cache flag bypasses the past-departure-time check, so old briefings can be regenerated.

Output

The tool produces a self-contained HTML file and opens it in the default browser. Contents:

• Weather chart images with the flight route overlaid in magenta
• Claude's analysis with GO / MARGINAL GO / NO-GO recommendation
• Significant charts highlighted separately from reference charts
• FAA A/FD data (tower status, elevation, runways, ILS/VGSI, operational remarks)
• TAF data for departure, enroute, and arrival airports
• Winds/temps aloft along the route
• Area Forecast Discussion (AFD) aviation sections
• Route leg ETAs and distances

The FAA airport data is auto-downloaded from the NASR 28-day subscription and cached locally (faa_data/). It refreshes automatically when >30 days old.

Error Handling

• "Could not fetch any charts": Network issue — check internet connection and retry.
• "Departure time is more than 2 hours in the past": Use --from-cache to rebuild old briefings, or update the departure time.
• TAF "not yet valid": Normal for flights >24 hours out — TAFs only cover ~24-30 hours ahead.
• Route resolution fails: The AWC API may be temporarily down. The tool continues without route overlay.

Requirements

• ANTHROPIC_API_KEY environment variable (or .env file in the project directory)
• Python 3.9+
• Dependencies: anthropic httpx Pillow numpy scipy pyproj opencv-python pyshp