wego

Wego CLI

Translate the user's travel request into wego commands, parse their JSON output, retain the identifiers needed by later commands, and present human-readable choices. Drive the complete flight or hotel funnel from prompting; do not make the user learn CLI syntax or copy internal IDs.

Where things are. Read the operating contract first, then jump to the vertical the request needs:

• Operating contract – preflight, metering, currency, the rules that bind every command. Always applies.
• Gather inputs / Resolve places – turning a request into codes and dates.
• Reference lookups (wego info) – holidays, visa-free, timetables, nearby airports, and which backend this binary resolved. No search, no price, no expiring id.
• Settled snapshots and empty pages – what an empty result means, and what it never means. Both funnels depend on it; read it before you report a no-match.
• Search flights – the flights funnel, search to checkout link. Also Share a flight search.
• Search hotels – the hotels funnel, search to checkout link.
• Combine flights and hotels – trip requests that need both.
• Pricing preferences (wego config) / Send feedback – the two commands that touch the user's machine or the Wego team.
• Finish the answer – what a limit that refused a call owes the user, in the answer itself.
• Recover safely / Login environments / Exit codes – failure handling.
• Example prompt translations – worked examples from a user sentence to a command line.

Operating contract

1. Every command here is wego , installed from https://api.wego.com/install. Keep that one command for the whole workflow. It reads live inventory and prices, so quote what it returns rather than estimating, and never invent a figure it did not give you.

2. Check availability with wego version. If it is missing, offer the official installer; do not run a remote installer without the user's approval:

   curl -fsSL https://api.wego.com/install | bash
   

   When the CLI is already present but the user wants the latest, or its syntax looks out of date, wego update --check reports whether a newer build exists (read-only, no approval needed). Self-replacing the installed binary is a significant action, like install: get the user's approval before running the self-replacing wego update -y (add -y since an agent shell isn't a TTY). It verifies the download against the published checksums and needs no reinstall. A from-source run prints a "reinstall" hint instead (nothing to replace).

   Both forms follow the release ring the installer recorded, and name it in what they print. An install with no record – installed before the record existed, or with the record deleted – refuses both forms with exit code 6 and says to reinstall with the curl line above. If the user directly asked to update or check, that exit 6 means the requested action failed: state that result and offer the reinstall for their approval, do not report the update as done. Only when the check was an optional preflight for another task is it safe to note the refusal and carry on.

   An installed CLI also announces a new release itself: any command except update, uninstall, and skill may print one stderr line naming the available version and update -y, and only when that command succeeded – a failure still carries exactly one stderr line. When you see it, skip update --check – its presence already means a newer build exists – and do not interrupt work in progress. Finish the user's request, then mention it once at the end and offer update -y for their approval. Never parse the version out of that line; treat its presence as the whole signal.

3. Run wego whoami before the first authenticated travel command when session state is unknown. If login is required, run its login subcommand, tell the user to complete the browser flow, then resume the original request. Login only completes by itself when the user's browser is on the machine that runs the CLI, and your shell is not a TTY, so you can never complete the paste fallback yourself. When stderr says no browser is on this machine, or that this terminal cannot read a paste, treat login as the user's action: ask them to run login in their own interactive terminal on that machine, then re-check with whoami (see Login environments). Never ask for an access token, and never read or print the credentials file.

4. Treat successful stdout from whoami, places, info *, flights *, and hotels * as JSON. version and help intentionally print plain text; login and logout are status flows. Treat stderr as status or recovery guidance. Non-empty stderr is not by itself a failure: a successful command can carry a hint, or the new-version notice, alongside valid stdout JSON and an exit code of 0. On failure, stdout stays empty and stderr still carries a single actionable line – the error class and detail, a trace_id=… (quote it to Wego support), a Retry-After hint when present, and the next action (for example run \wego login``). Do not scrape identifiers from human-readable error text when the same value exists in JSON. Branch on the process exit code (see Exit codes), not on stderr wording, which is not a stable contract.

5. Quote free-text and identifiers passed to the shell. Do not use eval or compose executable shell fragments from user text.

6. Retain the user's original search inputs and the IDs returned by each command. Map follow-ups such as "option 2" back to the corresponding object in the most recent result.

7. Present a concise ranked comparison instead of raw JSON. Include only decision-relevant fields such as total price, duration, stops, baggage, rating, board, and refundability.

8. Ask only for missing user-facing inputs. Do not ask the user for searchId, tripId, fareId, fareOptionId, hotelId, or rateId when they appeared in earlier output.

9. Establish the pricing preferences BEFORE the first priced command. Run wego config list: it prints currency, site and locale, each with the layer that decided it – setting (the user's stored preference), account (the market on their Wego account, site only), or default (the API's USD / en / US floor). When currency or site reads default, ask the user once, in a single question, which currency to price in and which market they buy from – naming the account market if there is one. A request for answers in another language triggers that question on its own, even when currency and site are both already stored, and folds into it when they are not: name the language their results come back in, and persist it only if they agree. Then persist ONLY what they actually said:

   wego config list
   wego config set currency SAR
   wego config set site SA
   wego config set locale ar
   

   wego config set writes to the user's own machine, so it needs their word – the same rule as installing or updating the CLI. If they decline, say "just this once", or do not answer, write nothing and pass --currency / --site / --locale on each command for that session instead. Once the values are stored, later sessions read them from wego config list and ask nothing.

10. Preserve currency, market and locale throughout a funnel. With a stored setting, every command inherits it, so a read no longer reverts to USD – but an explicit flag still wins for that one command, and mixing the two inside one funnel is how a riyal price ends up compared against a dollar price. A searchId remembers no currency. So a search created with an explicit --currency must carry that same --currency on every later results / trip / fares read of it: omit it and the read is repriced into the stored preference, or into the API's USD when nothing is stored, and the two snapshots stop being comparable. Every read echoes the currencyCode it priced in – compare it against the one the search reported before you quote a number. Every priced read echoes a currencyCodeSource beside that currencyCode – both searches, both results reads, trip, fares, and both rooms forms – naming the layer that decided the unit: explicit (a --currency on that command), setting (the user's stored currency), or default (nobody chose one, so the API priced in USD). Read it before you quote the first number: on default, state the currency instead of letting the digits imply it, and offer contract item 9's one question; on setting, name the stored currency rather than presenting it as a choice made for this trip. It names the unit the command asked for, so when the top-level currencyCode differs from metadata.currencyCode, the price was not converted into the currency asked for: say that, rather than quoting the number as if it were in the requested currency. Every *Source field is top level and there is exactly one per knob – the CLI strips the API's own request-scoped copies from metadata before printing, so a payload never carries two answers to "who decided". There is no locale equivalent, by design: locale changes the language of the text, not the number, so no CLI output carries a localeSource. It still has to be asked for. When the user asks for their answers in another language, pass --locale on the reads whose text you will quote back to them, because the names in a Wego answer, the airlines, cities, airports, countries and holidays, come back in the language the read asked for. Translating them yourself puts your wording in front of someone who may be matching it against a booking page. Codes and keys do not move with the locale, so nothing you thread through the funnel changes: an English query still resolves RUH under --locale ar, and results[].key stays the same slug. Report the market when it was not explicit: flights search and hotels search echo a top-level siteCode beside a top-level siteCodeSource of explicit, setting, account, or default; info schedules reports the same top-level siteCodeSource, while its market value stays at metadata.siteCode – an echo only, since a published timetable does not vary by market. Confirm with the user when it reads default, or when the account market clearly mismatches the request (for example AED pricing against a US account). Do not infer a currency from the route, the destination, or a nationality. Market cannot change on results – a different market means a new search – and it must be re-supplied to the stateless booking-link.

11. Never claim that a booking, reservation, payment, cancellation, or modification occurred. This CLI searches and generates checkout links only.

12. Creating a search and reading a hotel's rooms are metered. This API is a research preview, so those limits are deliberate and fairly tight – say so whenever one is reached, including one you waited out and worked around (see Finish the answer). Plan inside that budget rather than discovering it: never open one search per airport, per date, or per hotel. When a request implies many, run a small first batch, present it, and ask the user which to expand – that is also a better conversation than a wall of options. Reads against an existing searchId (results, trip, fares) are far cheaper than a new search, so refine an existing search instead of creating another whenever the constraint can be expressed as a flag. hotels rooms is the one read that always mints a search of its own, one per hotel, so open it for the hotels the user actually picked rather than sweeping a results page with it.

wego --help is the authority on a flag. It lists every flag of the installed binary with its allowed values. Read it before you guess a value, and before you drop a user's request because you cannot see a flag for it here: a flag this file omits and a flag the CLI lacks look the same from here. wego --help lists the commands.

Gather inputs

Resolve relative dates against today's date and send YYYY-MM-DD. Ask a concise question when dates, destination, or route are genuinely missing or ambiguous. Let the CLI apply its occupancy defaults when the user gives no occupancy; pass explicit adults, children, infants, and rooms when supplied.

Do not silently choose among materially different options. It is acceptable to select the cheapest, fastest, or best-rated compatible result when the user explicitly requested that criterion. Otherwise present choices and wait.

Resolve places

Use place resolution before a search when the user supplied names rather than the codes or coordinates required downstream:

wego places "" [--types ] [--locale en] [--page N] [--page-size 10]

--types narrows the candidates; omit it to resolve every place type (city, airport, state, district, hotel). Match the filter to the vertical – do not carry a flights-only filter into a hotel lookup.

• For flights, resolve each endpoint to an airport or city IATA code; narrow with --types city,airport when you want only those. Record whether the selected result is a city or airport; the booking-link command needs --from-city or --to-city when the original flight search used a city code.
• For hotels, pass an uppercase three-letter city code, a numeric hotel ID, or lat,lng. Leave --types off (or pass city,district,hotel) so hotel, district, and landmark candidates are not filtered out. Use coordinates for a district, landmark, or nearby search when no suitable city code or hotel ID represents the request.
• If metadata.hasAmbiguity is true, use disambiguationHint and the candidates to clarify before proceeding.
• Reuse resolved values during the same conversation instead of resolving them repeatedly.

Reference lookups (wego info)

Four lookups that need no prior search, plus one purely local report. Every other command group is a chain whose IDs expire in five to seven minutes; these take only what the user already told you – a country, a date, a route, a place – so call them at any point, in any order, and reuse the answer for the rest of the conversation. None creates a search or a price.

wego info holidays  [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--locale en]
wego info visa-free  [--locale en] [--page N] [--page-size N]
wego info schedules   [--airline SQ] [--site SG] [--locale en] [--page N] [--page-size N]
wego info airports-near  [--types airport,city] [--locale en] [--page-size N]
wego info target [--json]

holidays – public holidays in one Wego market, for finding a long weekend before searching. Give both --from and --to or neither; one alone is rejected rather than half-guessed. Omitted, the API searches the next 90 days and tells you so: metadata.window is upcoming and metadata.from/to state the range it actually used, so read those before reasoning about which days you searched. results[].key is a stable slug (national_day), so the same holiday matches across locales.

visa-free – where a passport travels without a visa, as one complete list by default (the API walks every page for you; --page-size only narrows the answer). This is an inspiration list, not a visa rule. It carries no visa type, so eVisa, visa-on-arrival, and true visa-free are indistinguishable, and no permitted stay duration, so "seven days in Japan?" is unanswerable from it. A country's absence means absent from Wego's list – never that a visa is required, and you must not tell the user otherwise. If metadata.coverage is truncated, even the list is partial, so absence says still less. Use it for "where could I go without a visa"; for "do I need a visa for X", say you cannot confirm entry requirements and point the user at the destination's official source.

schedules – the published timetable for a route: times, duration, stops, aircraft, no prices. Answers "what does SQ fly SIN→BKK" for one read instead of a full priced search. Airport codes are accepted and resolved to their parent city, so metadata.from/to echo {requested, resolvedCityCode} – check it, because asking for LHR gets you London's timetable across all its airports, which is usually what the user meant but is not what they typed. Say so when it matters. An empty results for a resolved route means no scheduled service in this dataset, not a failure.

airports-near – the airports (and optionally cities) near a place code or a lat,lng pair, nearest first. Rows are the same shape wego places returns, so a code found here goes straight into flights search. metadata.origin echoes the point measured from and which place a code resolved to; confirm it before presenting alternatives. Use it for "anything cheaper from a nearby airport" – the user names one airport, and this finds the others serving the same trip.

target – which backend this binary resolved, and what decided it. Local only: no token, no network, so it answers even when nothing else does. stdout is the JSON object either way, like every other info command; the readable table is on stderr, and --json drops it. Read it before you quote a price if you did not start this session yourself. A telemetrySuppressed of true means the run is pointed at a test backend, and figures from a test backend are test data – describe them as such and never present them as a price the user can act on.

The four lookups compose, and the join is yours to make:

• "When is my next long weekend, and where could I go?" – wego info holidays SG → spot a Saturday–Monday span → wego flights search SIN .
• "Philippine passport, somewhere I don't need a visa – and when?" – the two calls answer different halves and are combined, not intersected: wego info visa-free PH gives the destinations (each with a keyCityCode to search on), and wego info holidays PH gives the dates you are free. Pair a long-weekend span with each candidate destination and search. Holiday rows carry name/key/startDate/endDate and no countryCode, so there is no key to join them on – and both calls take the same country anyway.
• "Flying from Heathrow – anything cheaper nearby?" – wego places "Heathrow" → LHR → wego info airports-near LON → search each returned results[].code and compare. Read the codes off the response rather than from a remembered list: the set is dynamic and paged, so a hard-coded one both misses airports the call returned and searches codes it did not. On a London call today that is LCY, LGW, LTN, STN, SEN, quoted only to show the shape.
• "What's the SQ schedule SIN→BKK?" – wego info schedules SIN BKK --airline SQ. Do not run a priced search for a timetable question.

Schedule rows carry no id at all – no tripId, nothing openable. So a timetable row cannot be handed to flights trip or priced directly: to price a flight you saw in a timetable, run a normal flights search for that route and date, then match a segment on all four of airlineCode (the marketing carrier), flightNumber, departureAirportCode/arrivalAirportCode, and the date you searched. Carrier plus departure time is not enough: on a codeshare two carriers market the same physical flight, so that pair can match the wrong marketed row or miss the right one. flightNumber is optional on a schedule row – when it or any other key is missing, present the match as approximate and confirm with the user before treating it as the same flight.

Settled snapshots and empty pages

Both funnels create a search that settles over time, so an empty page is a statement about when you looked, not about what exists. Getting this wrong is the most expensive mistake available here: it tells a user that no flight or no hotel exists, and it invites a duplicate metered search. These rules govern every results read in both verticals, and each funnel section below adds only what is specific to it.

A search blocks to settled; a bare read does not. flights search and hotels search both settle before they print, and stamp the JSON with settled: "converged" or "budget_exhausted" – branch on that stamp instead of re-implementing polling. A bare flights results / hotels results is a single snapshot stamped settled: "unsettled", and --wait runs the same settle and stamps it the same way. So re-read with --wait when you want a fresher or deeper page, or to re-settle a "budget_exhausted" snapshot, and never hand-roll a re-read loop.

A page is not a census. Before calling anything a no-match, read the three counters:

• metadata.hasMore: true means unread candidates remain. hasMore: false on its own proves nothing.
• metadata.totalCandidates is how many candidates the active filters matched across all pages. Above 0 with an empty page in your hand means you paged past the last page: go back to page 1, the filters are fine.
• metadata.totalBeforeFilters is how many existed before your filters ran. Above 0 with totalCandidates: 0 means your own filters emptied the page, so name the filter that did it rather than reporting scarcity.

A zero is only an answer on a settled snapshot (settled: "converged", from a search or a results --wait). On an unsettled read a zero is aggregation in progress, so re-settle before drawing any conclusion.

What a settled zero lets you say differs by vertical, because only one of them can tell you it finished:

• Flights carry no completion flag at all, so even "converged" is a heuristic and no snapshot ever proves a flight does not exist. Report a settled zero as "no candidates matched these filters" for that date, never as "no such flight exists".
• Hotels carry searchComplete, and true is authoritative about Book-on-Wego bookable inventory only: searchComplete: true with metadata.totalBeforeFilters: 0 means no Book-on-Wego bookable hotel surfaced for these dates. Say exactly that, never "no hotels exist" – the search only ever asks for Book-on-Wego inventory, so that zero says nothing about the wider destination. false is inconclusive: it stays false for most of a search's lifetime. On the rooms/rates endpoint the flag is advisory – true says upstream finished aggregating rates, and the CLI settles that read for you. It describes aggregation still running rather than the page in your hand, so it can sit beside a complete-looking page (hasMore: false with a small totalCandidates) without contradicting it – those results are usable, and more may still be landing.

When it is still empty after a settle, say it is still settling, retain the searchId, and offer to refresh. Do not conclude there are no matches, and do not create a second search: the create is the metered call, and the CLI's own stderr hint names the id to re-read. One endpoint needs a different id, because the two searches are not interchangeable – an empty rooms/rates read is re-run as hotels rooms with the hotel-scoped --search the CLI just printed, since hotels results would settle the city search instead.

A filter finding nothing is never a reason to drop the user's constraint. Check the term or the bound against the vocabulary the snapshot echoes (for hotels, metadata.filterOptions – see Refine or paginate), then either retry with a name from it or tell the user their constraint matched nothing. Silently widening a search the user narrowed is how a "nonstop only" request comes back with a one-stop recommendation.

Search flights

Follow this value chain:

search inputs
  -> searchId + results[].tripId          (a results page is CARDS: price summary, no fares)
  -> flights trip   -> fares[]    (the only read that carries fares)
  -> direct handoffUrl OR Wego fareId
  -> fareOptionId
  -> bookingUrl

Create the search

wego flights search    \
  [--return ] \
  [--cabin economy|premium_economy|business|first] \
  [--adults N] [--children N] [--infants N] \
  [--site SG] [--currency USD] [--locale en]

Save all original inputs, including whether either endpoint was a city. Save the returned searchId and every result's tripId.

A results page carries no fares. search and results return one lean card per trip: a cheapest-price summary (price.total, price.websiteCount, price.hasWegoFare), trip-level stops and durationMinutes, and a per-leg summary with airline names, aircraft, stopovers and transportTypes (see below – a leg is not always a flight). Every fare – its fareId, kind, refundable, handoffUrl – comes from flights trip, which is one extra call on the trip the user actually picks. Read price.hasWegoFare before you open a trip: true means the Wego checkout branch is available for it, false means the continue step will be a partner or airline handoff.

Not every "flight" flies. Check transportTypes before you call one a flight. Airlines sell surface segments under a flight number – the Etihad coach from Dubai Bus Station to Abu Dhabi is sold as EY5421 – and those itineraries are often the cheapest on the page, so they dominate a --sort price_asc read. Every leg on a card and on flights trip carries transportTypes, the distinct modes across its segments in order: ["FLIGHT"] is a plain flight, and anything else (["BUS","FLIGHT"], ["TRAIN","FLIGHT"]) means part of that leg is not a plane. Say so before you quote the trip, in the same breath as the price: "USD 455, but the first leg is a two-hour Etihad coach from Dubai Bus Station, not a flight." Open flights trip to name which segment and where it leaves from – each segment carries its own transportType, plus fromName and fromStationType (bus_station, train_station), so XNB becomes "Dubai Bus Station" instead of reading like a third airport code. A traveller who asked to leave from DXB did not ask to start at a bus station across town, and only you can tell them. Match the claim to the evidence, because the mode is upstream's and it is sometimes wrong. Where an endpoint's fromStationType / toStationType reads bus_station or train_station, the ground segment is real: name the station, as in "a coach from Dubai Bus Station". Where a non-flight segment runs between two airports, which happens when a carrier files a surface equipment code on a leg that really does fly, say the airline lists that segment as ground transport rather than asserting a coach. A five-hour "bus" between two international airports is a filing quirk, not a journey anyone takes by road, and telling a traveller it is a coach is its own wrong answer. OTHER is a mode the API does not model; treat it exactly like BUS – not a flight, name it and let the traveller decide. This is disclosure, not exclusion: these are real, bookable itineraries that wego.com sells and shows with a bus icon, so present them, never silently drop them.

Creating a search is the metered call, so pace it. Reuse one searchId through results wherever the question can be answered by re-reading instead of re-creating.

search accepts no filter flags – they live on flights results (see Refine or paginate). So whenever the user stated a constraint those filters accept (departure window, stops, airlines, stopover airport, price, duration), the page search returns is not the page you rank from: re-read the same searchId with those flags before you read, rank, or recommend anything. Picking a flight that happens to satisfy the constraint out of an unfiltered page is not the same as applying it, and leaves you asserting a constraint you never checked against the full candidate set.

Not every constraint is a flag, and flights refundability is the one that catches agents out: it is a property of each fare, not of the trip, and flights results has no --refundable (hotels does). Carry that requirement forward to flights trip and pick a fare whose fares[].refundable is true.

search blocks to settled and stamps settled, so re-read the same search rather than polling it:

wego flights results  --wait [--currency USD] [--locale en]

Settled snapshots and empty pages carries the rest, and flights needs all of it: these results have no completion flag, so no snapshot ever proves a flight does not exist.

Refine or paginate

wego flights results  \
  [--wait] \
  [--page N] [--page-size N] \
  [--sort score_desc|price_asc|duration_asc|leg1_departure_time_asc|leg1_departure_time_desc|leg2_departure_time_asc|leg2_departure_time_desc] \
  [--airlines SQ,TR] [--alliances star_alliance,lcc] [--stops 0,1] \
  [--min-price N] [--max-price N] [--max-duration N] \
  [--min-stopover-duration N] [--max-stopover-duration N] \
  [--departure-blocks midnight|morning|afternoon|night] [--departure-range 1320-360] \
  [--arrival-blocks midnight|morning|afternoon|night] [--arrival-range 0-1080] \
  [--return-departure-blocks morning] [--return-departure-range 360-720] \
  [--return-arrival-blocks night] [--return-arrival-range 0-1320] \
  [--outbound-min-duration N] [--outbound-max-duration N] \
  [--return-min-duration N] [--return-max-duration N] \
  [--booking-types wego|airline] [--booking-sites expedia.com] \
  [--stopover-airports DOH] [--aircraft 380,789] \
  [--airlines-match any|all] [--same-airline true|false] \
  [--currency USD] [--locale en]

Translate the user's constraints into flags – every one of them, on this read. Re-supply still-active constraints on each refinement instead of assuming a previous filtered read changed the underlying search. Use --stops 0 for nonstop.

• --wait performs a bounded server-friendly settle and adds a settled: converged|budget_exhausted field to the output; prefer it over hand-rolled re-read loops.
• The clock filters cover both ends of both legs. Eight flags, one per {outbound, return} × {departure, arrival} × {blocks, range} combination. --departure-* and --arrival-* bound the outbound leg; prefix --return- for the return leg. Each reads local time at that airport, so --arrival-range is the arrival airport's clock, not the origin's.
  • --*-blocks takes comma-separated midnight (00:00–05:59), morning (06:00–11:59), afternoon (12:00–17:59), night (18:00–23:59). The four partition the day, so passing all four returns everything exactly once. (wego.com's own buckets overlap at 06:00, 12:00 and 18:00; these do not, so a 06:00 flight is morning here and both midnight and morning there.)
  • --*-range takes a min-max minutes-of-day window, 0–1439, both ends inclusive; when min>max it wraps past midnight, e.g. 1320-360 = 22:00–06:00.
  • Prefer an explicit range whenever the user gave a hard edge. The blocks are six hours wide, so night admits a 19:50 departure and afternoon admits a 17:55 landing. Reach for blocks only when the user spoke in those terms.
• Arrival time is usually what the traveller is planning around, so do not answer an arrival constraint with a departure filter. "Land before 18:00" is --arrival-range 0-1080. "Nothing that lands at 4am" is --arrival-range 360-1320. "Home before 22:00" on a round trip is --return-arrival-range 0-1320. These bind the hotel check-in cut-off, the last train home, the morning meeting – all things a departure window cannot express, because the same 10:00 departure lands at very different hours depending on the routing.
  • "Get me in before midnight" is the one to read carefully: every landing is before some midnight, so the constraint the traveller means is "not in the small hours", and the flag for it bounds the far end – --arrival-range 300-1439 (05:00–23:59) drops a 00:30 or 04:00 arrival. 0-1439 is the whole day and filters nothing.
  • Arrival bounds read the clock, not the calendar. A red-eye landing 04:00 the next day is minute 240, exactly like a same-day 04:00 landing, so --arrival-range 360-1320 drops both and --arrival-range 0-1080 keeps both. When the day matters, filter on the clock and then read each card's legs[].arrivalDayOffset (1 = lands the next day) and say so, rather than implying the filter checked it.
• Use --departure-* and --arrival-* together when the user gave both ends. They AND on the same leg, so they narrow rather than widen: "leave after 9am and land before 6pm" is --departure-range 540-1439 --arrival-range 0-1080.
• A round-trip constraint needs the --return-* flags; the outbound flags never reach the return leg. When the traveller states hours that plainly apply to both journeys ("no early starts either way"), send both sets. When they state hours for the way home only, send only the --return-* ones. If you bound one leg and not the other, say which leg you bounded rather than presenting the list as though it answered the whole request.
  • Every --return-* flag needs a return leg to judge. On a one-way search none exists, so any --return-* filter matches nothing and metadata.totalCandidates comes back 0. That is deliberate, not a bug and not an empty snapshot: it means the filter was inapplicable. Drop the flag and re-read rather than telling the traveller there are no flights.
• --outbound-min-duration / --outbound-max-duration / --return-min-duration / --return-max-duration bound one leg's elapsed time in minutes, inclusive. These are always leg-prefixed because the unprefixed --max-duration bounds the whole trip, and the two answer different questions: a 3-hour outbound paired with a 14-hour return totals 17 hours, so no trip-wide ceiling can reject the long way home on its own. Use the per-leg flags for "I do not mind a long flight out but keep the return under 8 hours" (--return-max-duration 480).
• --booking-types (wego, airline) accepts comma-separated enum values; like --sort, it is validated client-side before any network call, so a typo fails locally.
• --alliances takes comma-separated codes in the server's own spelling, and is not a fixed set, so it is not validated locally: an unknown code returns an empty page rather than an error. Read metadata.filterOptions.alliances for the codes the current snapshot actually carries. Common ones are star_alliance, oneworld and sky_team (note the underscore), alongside groupings that are not strictly alliances, such as lcc for low-cost carriers.
• --min-stopover-duration / --max-stopover-duration bound the layover in minutes, inclusive, on a trip's worst leg – the largest leg total, never an individual connection. --max-duration bounds neither, because it adds flying and waiting into one number. The ceiling is exact about what it measures, since capping the worst leg caps every leg – but what it measures is how long a wait is, never when it falls. It is not an overnight filter: a 135-minute wait starting 04:00 is under any sane ceiling and is still a night in the terminal, and a 465-minute wait starting 11:00 is over it and never sees one. For "no overnight wait", bound the length with this flag if the traveller also wants it short, then read the connection's own clock – flights trip --view detail gives each segment's arrivesAt and departsAt, and the gap between them is the wait, in local time at the connection airport. The floor is weaker than it sounds: a leg waiting 450 then 510 minutes is judged on 960, so --min-stopover-duration 120 does not promise every connection is 120 minutes long – on a multi-stop leg, or on the shorter leg of a round trip, a tight connection can survive it. When the traveller says "leave me at least two hours to change planes", send the floor and then read the card: legs[].layoverMinutesByStop lists one wait per connection, aligned to via, so you can see the real gaps and say so rather than implying a guarantee the filter does not make. A direct trip totals 0, so every maximum keeps it and any minimum above 0 drops it – pair a floor with --stops 0 only when the traveller wants both. Read metadata.filterOptions.stopoverDurations ({min, max}) for the span the snapshot carries before picking a bound.
• --stopover-airports (comma-separated IATA codes, e.g. DOH) restricts connections to those airports – use it for "connect through Doha" or "must have a stopover in X".
• --aircraft takes comma-separated aircraft codes in the server's own spelling (380, 789, 32N), not the labels the cards print (A380, B787-9, A320 Neo). It is not a fixed set and is not validated locally: an unknown code returns an empty page rather than an error. A trip matches when any leg flies a listed code, so an A380 outbound with an A320 return still matches, and there is no whole-trip variant of this flag the way --airlines-match all is for airlines. Read metadata.filterOptions.aircraft for the codes this snapshot carries and the label beside each one, then filter on the code – several codes can share one label (321 and 32S are both A321), so the label alone cannot address them. Use it for a positive requirement - "I want the A380", "put me on a 787" - and never fold results[].legs[].aircraft yourself to answer that: the page is one slice of the ranked candidate set, so the cheapest few cards are not where a widebody has to appear. It cannot express an exclusion. "Anything but a regional jet" has no flag: passing the codes the traveller wants to AVOID selects exactly the trips they refused. Either enumerate the acceptable codes from metadata.filterOptions.aircraft and pass those, or say the API cannot filter that way and let the traveller choose from what the snapshot carries.
• "Only Emirates" means the whole trip, so pass --airlines-match all. Bare --airlines EK keeps a trip when any one leg carries EK, so a flynas-out / Emirates-back itinerary survives a filter the traveller meant as a trip-wide constraint. --airlines-match all requires every leg to carry a listed airline, which is what wego.com does. Use all whenever the user says "only X" or "fly X", and the default any only when they will accept X on one direction. all modifies --airlines and does nothing alone, so the CLI rejects --airlines-match all without one.
• --same-airline true is stricter and stands alone: every leg must be marketed by exactly one airline, the same one on every leg, so an interline or self-transfer leg sold by two carriers is dropped. Use it for "don't mix airlines" with no carrier named, or add it to --airlines EK to rule out a two-carrier leg as well. It matches the marketing carrier, so a codeshare (Malaysia Airlines selling a Thai-operated flight) is still kept, exactly as on wego.com. When the user cares who actually flies the aircraft, read the leg's operatingAirlines rather than trusting this flag. Both flags are validated client-side, so a typo fails locally.
• --booking-sites and --booking-types select trips, not fares. A trip matches when any of its fares comes from a listed provider or kind, and the card's price.total is the trip's cheapest fare – which may be a different provider from the one you filtered on. So never quote a filtered card's price as "the price on expedia.com": open the trip and read that provider's own fare.
• Never name the airline from legs[].airlines alone. That field is the marketing carrier – whose code is on the ticket – and on a codeshare a different airline flies the aircraft. When a leg carries operatingAirlines, say so ("EgyptAir, but the Muscat–Kuala Lumpur leg is flown by Oman Air"): mileage accrual, lounge access and baggage rules follow the operator, so a bare "EgyptAir" i