flt prime

Agent Guide

The complete reference that flt prime outputs for AI coding agents. Everything an agent needs to search flights, build itineraries, and deliver results.

$ flt prime

Rules

Constraints the agent must follow during every session.

⚠ Rate limits

  • Built-in 3s throttle between requests. Never add manual sleeps.
  • Never run search/matrix in parallel.
  • Prefer flt matrix for date comparisons (max 21 combos, 5-7 is safer).
  • On {"err":"BLOCKED"}: stop all requests, sleep 60, retry with smaller scope.

↻ Caching

  • Cached by full query shape (dep/ret date, cabin, pax, stops, currency).
  • Fresh for 6 hours. --refresh bypasses.
  • Flight IDs (e.g. Fa3b7) are stable SHA-1 hashes from legs.
  • Plain IDs resolve across all session searches (latest first). REF:ID for explicit lookups.
  • Read-only commands (inspect, itinerary, takeout, airports, favs) never hit Google.

▶ Sessions

  • Auto-start on first search (named after route).
  • flt takeout auto-closes the session. Use --keep-session to prevent.
  • Start every response with: session: name (id).

Workflow

Five phases, in order. Each has a gate that must be met before proceeding.

1

Resolve

Gate: All airports are confirmed IATA codes
  • Resolve ambiguous cities/airports with flt airports <query>, confirm IATA codes with user.
  • For multi-stop routes (5+ legs): run flt connections <from> <to> to discover viable paths.
  • Compare transit hubs if needed: flt compare KUL,BKK,IST AMS 2026-03-22.
▼
2

Search

Gate: All legs have search results
  • One search per leg. Flexible dates: flt matrix (max 7 combos). Fixed dates: flt search.
  • Refine with filters (--carrier, --max-stops, --dep-after, etc.). Prefer filtering one search over running many.
  • Present top 3-5 per leg with price, duration, stops, carrier, times.
▼
3

Shortlist

Gate: User has approved favorites for every leg
  • flt fav <ID> promising offers. They survive cache expiry and are the basis for itineraries.
  • Use flt inspect <ID> for detail. Use flt favs to review the full shortlist.
  • Ask the user to confirm their preferred offer per leg. Do not proceed until each leg has a user-approved fav.
▼
4

Compose

Gate: Itinerary previewed and user-approved
  • Build itinerary: flt itinerary <REF:ID> [REF:ID...] --title "...".
  • Use full REF:ID format for precision, or plain IDs which search all session results.
  • Check connection times (min 2h domestic, 3h international), total price, travel time.
  • If connections are too tight, go back to Phase 2/3 for that leg.
▼
5

Deliver

Gate: Export complete
  • flt takeout --itin "Label" REF:ID REF:ID --title "Trip Title".
  • For PDF export: add --pdf.
  • Warn user: takeout auto-closes the session unless --keep-session is passed.

Commands

Full command reference with syntax and options.

Session

flt session start ["name"] Start named session (closes active one)
flt session close Close active session
flt session list List all sessions
flt session reopen [id] Re-open last closed (or specific) session
flt session refs [--id s1] List search refs with query and offer count
flt session rename "new name" Rename active (or --id) session
flt session nuke Delete ALL data (irreversible)

Search

flt AMS NRT 2026-04-10 One-way search
flt AMS NRT 2026-04-10 2026-04-18 Round-trip search
Options (17)
--seat economy | premium-economy | business | first
--pax 1ad | 2ad1ch | 1ad1in
--max-stops 0 | 1 | 2
--currency EUR | USD | ...
--direct Non-stop only
--limit Max results
--carrier Include carrier substring
--exclude-carrier Exclude carriers (comma-separated)
--exclude-hub Exclude hubs (comma-separated IATA)
--exclude-region Exclude region shorthand
--dep-after/before HH:MM departure window
--arr-after/before HH:MM arrival window
--max-dur Max duration in minutes
--sort price | dur | stops | dep
--fmt jsonl | tsv | table | brief
--view min | std | full
--fields Custom field CSV

Matrix

flt matrix AMS NRT 2026-04-01 2026-04-14 One-way date range
flt matrix AMS NRT 04-01 04-07 04-08 04-14 Round-trip date range

Compare

flt compare KUL,BKK,MNL AMS 2026-03-22 Cheapest from each origin
flt compare CEB KUL,BKK,ICN 2026-03-19 Cheapest to each destination

Inspect

flt inspect Fa3b7 Inspect by flight ID
flt Fa3b7 Shorthand (auto-detected)

Itinerary

flt itinerary REF:ID [REF:ID...] --title "..." Compose multi-leg itinerary

Takeout

flt takeout --itin "Label" REF:ID REF:ID --title "..." Export session data

Airports

flt airports tokyo Fuzzy search by city, name, or IATA
flt tokyo Shorthand (auto-detected)

Favorites

flt fav O1 Bookmark an offer
flt unfav O1 Remove bookmark
flt favs List all favorites

Connections

flt connections AMS SYD Find routing options between two airports
Options (8)
--min-stops Minimum stops (default 5)
--max-stops Maximum stops (default 10)
--max-results Limit results (default 50)
--max-detour Max detour ratio (default 3.0)
--via Force waypoints (comma-separated IATA)
--exclude Exclude hubs (comma-separated IATA)
--exclude-region Exclude region shorthand
--names Show city names alongside IATA codes

Region Shorthands

Use with --exclude-region. Mixable with IATA codes.

gulf DXB, DOH, AUH, BAH, MCT, KWI
middleeast DXB, DOH, AUH, BAH, MCT, KWI, RUH, JED, AMM, TLV, CAI, BGW, IKA, THR
russia SVO, DME, LED, VKO
belarus MSQ

Error Codes

JSON format: {"err":"CODE","hint":"..."}

NO_RESULTS Relax filters (wider date range, allow stops, remove carrier constraint)
TOO_MANY Fewer date combos in matrix
NO_SESSION Run a search first to auto-start a session
BLOCKED Stop all requests, sleep 60, retry with smaller scope

Output guidelines

How the agent should present results to the user.

Lead with context: route(s), dates, constraints, currency.
Top 3-5 options: ID, price, stops, duration, carrier, dep-arr (+day).
Matrix: summarize cheapest dates first, then detail-search best 1-2.
Multi-leg: show itineraries with total price + connection notes.
Next steps: offer only if useful ("I can widen time window / allow 1 stop / extend dates").
Formats: --fmt brief for readable pulls, --fmt tsv for compact parsing. Default --limit 100.
Limitations: no fare rules, baggage, seat maps, booking classes, or loyalty info. Mention only when relevant.