FlightAware

Connecting

There is nothing for the user to connect and no key to enter. Run flightaware status to check it is reachable, or flightaware status --verify to also confirm a live read works. If status comes back unavailable, tell the user FlightAware is not reachable from this device right now and try again later. Never ask the user for a FlightAware API key.

Command syntax

Identifiers are positional arguments, not flags. Output is always JSON; add --compact for single-line JSON.

• flightaware flight <IDENT> [--date YYYY-MM-DD] for a flight number, registration, or fa_flight_id. --date is the local departure date and must be within two days from now; use --start/--end with ISO timestamps for another window.
• flightaware position <FA_FLIGHT_ID> and flightaware track <FA_FLIGHT_ID> for a leg returned by flight.
• flightaware schedules <DATE_START> <DATE_END> [--origin <ICAO>] [--destination <ICAO>] [--airline <ICAO>] [--flight-number <N>] for flights more than two days out.

Common flows

Track a flight

Run flight with the airline flight number to get its current status, then use the returned fa_flight_id with position for where it is now or track for its recent path. For a picture, run map with --save <path> to write a static image of the flight.

Monitor a tracked trip

Use this flow when the user directly asks for ongoing monitoring of an upcoming booked flight. Use this flow when the runtime hands off a validated automatic booking source for an upcoming flight. Treat either trigger as authorization to create the watch after the required flight facts are present. Do not ask whether to start monitoring after the runtime handoff. Do not require a connected email account. Ask the user only for flight facts that the requested monitoring needs and that the current context does not supply. Resolve each exact dated leg before scheduling a job.

Search user goals and Tracking items for the trip. Use a matching user goal as the canonical owner. Otherwise, reuse a matching active Tracking item. If neither exists, create one Tracking item. Resolve the canonical owner before scheduling a job. Do not create a FlightAware-specific database or a duplicate Tracking item.

Store the minimum operational state in ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json. Use ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json only as goal-owned job state. Do not create a separate travel database.

List the canonical owner's cron jobs before creating an operational job. Reuse an equivalent goal-owned operational job when one exists. If no equivalent job exists, add one operational job for the trip. Use flight-status-<goal-slug> as its identifier. Set its owner to goal:<goal-slug>. Schedule the operational job at creation with the actual cron schedule for the next active leg's current cadence band. Use a daily cron schedule while the next active leg departs more than 48 hours from now. Use an hourly cron schedule from 48 hours before departure until 6 hours before departure. Use a 10 to 15 minute cron schedule from 6 hours before departure through landing. Do not create or retain a high-frequency cron schedule that relies on ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json to skip source calls. Write a self-contained cron body because the cron worker receives neither this skill nor the surrounding conversation. Include the Tracking goal, ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json, exact leg identity, and booked baseline. Include the deduplication rule, failure policy, cadence transitions, and stop conditions. Include the exact FlightAware command lines each run needs, written with the syntax above.

At the start of each operational run, compare the existing cron schedule with the next active leg's current cadence band. Update the same cron job before any FlightAware source call when the existing cron schedule differs from the current cadence band. Repair an existing high-frequency cron schedule before any FlightAware source call when the next active leg is outside the high-frequency band. Keep the current cadence until the active leg lands or a connection risk remains unresolved. Advance the same job to the next active leg, then stop it after the final landing.

Compare strategic schedule changes with the booked baseline. Compare operational changes with the last notified facts. Apply the cancellation corroboration and status interpretation rules in the Rules section. For a material movement, flight or carrier change, confirmed cancellation, diversion, terminal change, qualifying gate change, qualifying equipment change, qualifying delay, or credible connection risk, create one stable event fingerprint. Treat the first delay estimate at 30 minutes or more as a qualifying delay. Treat a later delay-only change as a qualifying delay only when it crosses from 30 minutes or more to less than 30 minutes, enters a worse band among 30 to 59 minutes, 60 to 119 minutes, and 120 minutes or more, or differs by 60 minutes or more from the last notified delay estimate. Do not include the exact delayed minute value in a delay-only fingerprint. Treat terminal changes, airport changes, confirmed cancellations, diversions, and credible connection risks as immediate alert candidates. Treat departure gate changes as alert candidates only inside 24 hours before departure. Treat arrival gate changes as alert candidates only when they affect a connection or pickup. Treat equipment changes as alert candidates only when they affect cabin, seat, or itinerary facts. Keep final landing silent unless the user asked for landing notification or a pickup or connection impact remains. Keep a first gate or terminal assignment, an on-time status, boarding, taxiing, departure, and in-flight progress silent; none of them is a change. Name only the current gate in a departure gate alert. From 90 minutes before departure, send each departure gate change on the run that finds it. Earlier, send at most one departure gate alert per leg per hour: record a newer gate that arrives within the hour in
~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json and send the then-current gate on the first run after the hour. Stay silent when the gate returns to the last notified gate, and fold a gate change into a concurrent delay or cancellation message instead of sending it separately. In a scheduled run, keep an unconfirmed cancellation silent: record it in ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json, recheck the exact dated leg, and seek confirmation from an airline or airport source. A cancellation is confirmed only when FlightAware's cancelled flag and status text agree, or an airline or airport source confirms it. Notify as soon as it is confirmed, and keep checking on later runs while it stays unconfirmed. Write these silence rules, including the gate timing and the cancellation confirmation test, into the cron body with the other alert rules; the cron worker does not receive this skill. Persist the fingerprint before sending a message. Add one Tracking activity before sending a message. Do not add another activity or message for the same fingerprint. Keep unchanged checks silent. After three consecutive expected source failures, add one degraded-coverage activity. Do not treat a failed read as evidence that nothing changed. Remove the operational job when the Tracking item is completed or retired.

Find flights in the air

Use search to find airborne flights by origin, destination, or area. Default to one page of results and ask before pulling more.

Airport activity

Use airport for an airport's details, airport-delays for current delays, airport-flights for arrivals and departures, and airport-weather for conditions. nearby-airports finds airports around a location.

Airline activity

Use operator for an airline's details and operator-flights for its recent and scheduled flights.

History

For past flights, use the history commands with an explicit date range. They cover flights, tracks, routes, airport activity, and an aircraft's last flight.

Predictions and schedules

Use foresight for FlightAware's predicted status and positions, schedules for scheduled flights between two dates, and disruptions for cancellation and delay counts.

Other commands

The flows above cover the common cases. For anything else, run flightaware --help for the full command list and flightaware <command> --help for a command's options. This includes aircraft owner and type lookups, route and count queries, and advanced search syntax.

Rules

• Use the airline's ICAO flight number when you can (UAL123, not UA123). If the user's flight number is ambiguous, resolve it with canonical-flight first.
• For "where is my flight", get the flight first, pick the right date and leg, then look up its position or track. Do not guess an fa_flight_id.
• A cancellation is a high-impact terminal claim. Never report it as confirmed or stop a flight watch from cancelled: true alone. If the flight carries muse_cancellation_evidence.classification: conflicting_provider_fields, recheck the exact dated leg. If the fields still conflict, seek confirmation from an airline or airport source. Without it, say the cancellation is unconfirmed when answering the user directly, and keep a scheduled monitoring run silent until it is confirmed; keep monitoring either way. Only treat the cancellation as confirmed when FlightAware's boolean and status text agree, or an independent source confirms it.
• If FlightAware says a flight or aircraft is blocked or has no data, tell the user plainly and do not try to work around it.
• Flight reads preserve AeroAPI's raw times and add semantic UTC/user-local fields such as scheduled_gate_departure_at, estimated_takeoff_at, actual_landing_at, and scheduled_gate_arrival_at. Prefer their user_local values in replies. Position samples similarly add position_observed_at.
• FlightAware does not cover airline policies, terminal maps, baggage, booking, or customer service. For those, use web search and make clear which details came from the web rather than FlightAware.
• Reply in plain language about the flight, not about how you looked it up. Do not show the user commands, ids, tokens, or raw status codes.

Limits

• You can't book travel, buy tickets, change a reservation, or contact an airline or airport.
• Filing a flight intent changes state in FlightAware, so only do it when the user clearly asks and the exact flight is unambiguous; no additional confirmation is required.