@gojinko/cli

Command-line tool for the Jinko developer platform. Search flights and hotels, build trips (multi-domain — flights and hotels share one cart), and hand users off to a Jinko-hosted checkout page.

Install

npm install -g @gojinko/cli

Authentication

Jinko authenticates with a tenant API key (jnk_...). Get one from dashboard.gojinko.com → Developers → API keys.

# Store an API key (recommended)
jinko auth login --key jnk_YOUR_KEY

# Or interactively — prompts for the key
jinko auth login

# Or pass it via the environment (agents, CI/CD)
export JINKO_API_KEY=jnk_YOUR_KEY

OAuth sign-in is deprecated and no longer supported for the data plane. Use an API key.

Auth commands

jinko auth login --key jnk_…  # Store an API key (recommended)
jinko auth login              # Interactive — prompts for an API key
jinko auth status             # Show current method, expiry
jinko auth logout             # Clear stored credentials

Environments (prod / sandbox)

Defaults to production. Use --env sandbox to target the sandbox environment (isolated data, separate API keys):

jinko auth login --env sandbox --key jnk_your_sandbox_key   # store the sandbox key
jinko config set environment sandbox                        # make sandbox the default
jinko --env prod find-destination --origins NYC             # one-off prod override

Prod and sandbox keys are stored separately in ~/.jinko/config.yaml. Resolution precedence: --env → JINKO_ENV → config environment → prod. JINKO_API_BASE overrides the mapped URL (for dev/staging).

Commands

Exploration (cached)

| Command | Description | |---|---| | find-destination | Discover destinations from an origin | | flight-calendar | Cheapest prices across a date range for a known route | | find-dates | Best date options for a known route — up to ten cheapest itineraries, one per date-pair, spread across the month | | lowest-fare | Cheapest fares for a fixed route + date — up to ten itineraries, cheapest first |

Live pricing & trip building

| Command | Description | |---|---| | flight-search | Direct search by route + dates OR price-check an offer_token. Returns bookable trip_item_token. Carries the full shop filter set (stops, time windows, layovers, fare attributes, alternate airports) and reports which filters the results honor. | | price-monitoring | Cache-only price snapshot for a fixed OD + dates — intended for scheduled polling. Semantically distinct from flight-search (one-shot live shopping). | | hotel-search | Live hotel search by city / query / geo / hotel-ids. Returns hotels with rooms, rates, htl_* offer tokens. | | hotel-details | Lazy lookup for a specific hotel — images, amenities, location detail. Pairs with hotel-search when the user wants the full picture before booking. | | ground-search | Live rail / coach / ferry search. Each result's id is itself the trip_item_token — no prefix. | | trip | Create/update a trip, add flight or hotel items, set travelers |

Legacy

| Command | Description | |---|---|

Checkout

| Command | Description | |---|---| | checkout | Finalize a trip → returns checkout_url (human pays in a browser) + agent_spt_params (agent pays programmatically) + items + total. (book is a deprecated alias.) | | agent-pay submit | Pay programmatically with a Shared Payment Token: present --trip-id + --token; the BFF schedules the agent fulfillment and redeems the SPT. Returns the Jinko booking_ref (JNK-…) once authorized. Falls back to checkout_url on a 3DS step-up. | | get-ancillaries | List a trip's purchasable ancillaries (bags / seats / meals) without generating a checkout URL | | select-ancillaries | Optional: preselect bags / seats / meals before handoff | | trip-status | Full lifecycle state: cart, quote, fulfillment, bookings — plus the Jinko booking_ref once fulfillment has been scheduled (it can be present before payment completes — read fulfillment.status for paid), the value get-booking / hotel-cancel / refund / exchange take as --booking-ref |

Post-booking

| Command | Description | |---|---| | get-booking | Retrieve the whole booking (flight + hotel) by reference (booking ref + last-name guest-auth). No subcommands. Carries calendar — the .ics files for the booking's flights and stays; the table format lists one line per file, --format json carries the contents. | | refund check | Check refund eligibility for a booking | | refund commit | Initiate a refund for a booking | | refund status | Check the status of a previously committed refund | | exchange shop | Search exchange options for an existing booking | | exchange price | Price a selected exchange option | | exchange commit | Commit a flight exchange | | exchange status | Check the status of a previously committed exchange | | hotel-cancel | Cancel a hotel booking (idempotent — safe to retry). Guest auth via --ref + --last-name, or authenticated via --provider-booking-id. |

Utility

| Command | Description | |---|---| | config set / config show | Manage local config — config set environment <prod\|sandbox>, config set api_key <jnk_…> (stored under the active env) | | schema [cmd] | Show request/response schemas |

Canonical Flow

flight-search → trip → checkout → user pays on checkout_url → trip-status
                                ↘ agent-pay submit (programmatic, Shared Payment Token) → trip-status

Quote is automatic — checkout handles it internally. A human pays on the returned checkout_url (the Jinko web page, not in the CLI); an agent can instead mint a Shared Payment Token from agent_spt_params and call agent-pay submit to pay programmatically.

Examples

# Live flight search by route + dates (returns trip_item_token directly)
jinko flight-search --origin PAR --destination NYC --departure-date 2026-06-15

# Filtered search — non-stop, morning departure, checked bag in the fare
jinko flight-search --origin JFK --destination CDG --departure-date 2026-09-01 \
  --max-stops 0 --departure-time-range 06:00-11:00 --checked-bag-included

# Widen the search to more departure airports (the anchor still decides ranking)
jinko flight-search --origin JFK --destination CDG --departure-date 2026-09-01 \
  --origin-alternate-airports EWR LGA

# Or price-check an offer_token from flight-calendar
jinko flight-search --offer-token <offer_token>

# Live hotel search (returns htl_* tokens that plug into trip the same way as flight tokens)
jinko hotel-search --city-name "Paris" --country-code FR --checkin 2026-07-15 --checkout 2026-07-18 --adults 2

# Live ground search — rail, coach, ferry. Codes are ISO-country + city (GBLON), NOT IATA (LON).
jinko ground-search --departure-city GBLON --arrival-city FRPAR --date 2026-08-28 --adults 2 --currency GBP
# --currency is currently REQUIRED despite the schema marking it optional:
# without it the provider rejects the search and you get an unhelpful "Please retry."
# Each connection's id IS the trip item token — pass it through unmodified:
jinko trip --trip-item-token <connection_id>

# Multi-domain cart: add flight + hotel to the same trip → one Stripe checkout
jinko trip --trip-item-token <flight_token>            # returns trip_id
jinko trip --trip-id <trip_id> --trip-item-token <htl_*>

# Create trip with travelers + contact
jinko trip \
  --trip-item-token <token> \
  --travelers '[{"first_name":"Jane","last_name":"Doe","date_of_birth":"1990-01-15","gender":"FEMALE","passenger_type":"ADULT"}]' \
  --contact '{"email":"[email protected]","phone":"+33612345678"}'

# Finalize → returns checkout_url (human) + agent_spt_params (agent)
jinko checkout --trip-id <trip_id>

# Optional: add baggage/seats/meals before handoff
jinko select-ancillaries \
  --trip-id <trip_id> \
  --item-id <item_id> \
  --select <offer_id_1>,<offer_id_2> \
  --pax <passenger_ref> \
  --quantity 2

# Poll status until fulfilled
jinko trip-status --trip-id <trip_id>

# Refunds
jinko refund check  --booking-ref <ref> --pnr <pnr>
jinko refund commit --booking-ref <ref> --pnr <pnr> --reason "schedule change"

# Hotel cancellations (idempotent — safe to retry)
jinko hotel-cancel --booking-ref <booking_ref> --last-name <name>
# Or via the authenticated shortcut:
jinko hotel-cancel --provider-booking-id <id> --provider nuitee

Flight search filters

flight-search exposes every filter the POST /v1/flight_search contract accepts, one option per field — run jinko flight-search --help for the list. Two things are worth knowing before you use them:

The response says which filters were honored. Every search comes back with applied_filters (the ones these results DO honor) and unapplied_filters (the ones they do not, each with a reason). A filter the platform could not enforce is a reported outcome, not an error: the call still returns 200 with offers. Post-filter them yourself, or tell the user the constraint could not be met. --format table prints the report under the results; JSON output carries both lists as response fields.

Alternate airports widen an airport anchor. --origin-alternate-airports and --destination-alternate-airports add departure/arrival airports beside --origin / --destination — widening only, so they can add results but never remove any. The anchor decides ranking and truncation, which makes the two airports NOT interchangeable: put the airport that matters most in --origin. Against a city anchor (--origin-type city, or a code the platform resolves to a city) the list is ignored — a city already searches its whole metro area — and comes back in unapplied_filters under the name origin or destination, never under the option name it was sent with.

jinko flight-search --origin PAR --destination NYC --departure-date 2026-06-15 \
  --origin-alternate-airports ORY --format table
# ...offers...
#
# Unapplied filters:
#   origin — <the reason the platform gives for not enforcing it>

Output Formats

jinko flight-search --origin PAR --destination NYC --departure-date 2026-06-15
jinko flight-search --origin PAR --destination NYC --departure-date 2026-06-15 --format table

Schema Introspection

jinko schema                  # List all tools
jinko schema flight-search    # Show a tool's request/response schema

Canonical flags & deprecated aliases (JIN-665)

CLI flags now match the canonical jinko-api request field names, kebab-cased (e.g. departure_dates → --departure-dates, star_rating/min_star_rating → --star-rating). The previous flag spellings keep working as deprecated aliases — they print a one-line DEPRECATED notice to stderr (never stdout, so JSON output stays parseable) and will be removed in the next major release.

| Command | Canonical flag | Deprecated alias | |---|---|---| | flight-search, price-monitoring | --origin / --destination | --from / --to | | flight-search, price-monitoring | --departure-date / --return-date | --date / --return | | flight-search, price-monitoring | --cabin-class | --cabin | | flight-search, price-monitoring | --adults | --passengers | | flight-calendar | --origins / --destinations | --from / --to | | find-dates, lowest-fare | --origins / --destinations | --from / --to | | find-destination | --origins / --departure-dates / --max-total / --sort-by … | --from / --date / --max-price / --sort … | | hotel-search | --city-name / --country-code | --city / --country | | hotel-search | --latitude / --longitude / --radius-km | --lat / --lng / --radius | | hotel-search | --guest-nationality | --nationality | | hotel-search | --star-rating / --max-star-rating | --stars / --max-stars | | get-booking, hotel-cancel | --booking-ref | --ref |