@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

# API key (recommended for agents, CI/CD)
export JINKO_API_KEY=jnk_YOUR_KEY

# OAuth (interactive humans — opens a browser)
jinko auth login

Create API keys at https://builders.gojinko.com. OAuth tokens auto-refresh.

Auth commands

jinko auth login              # Interactive login
jinko auth login --key jnk_…  # Store 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. | | 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. | | 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. 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 |

Post-booking

| Command | Description | |---|---| | get-booking | Retrieve the whole booking (flight + hotel) by reference (booking ref + last-name guest-auth). No subcommands. | | 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

# 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

# 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 --ref <booking_ref> --last-name <name>
# Or via the authenticated shortcut:
jinko hotel-cancel --provider-booking-id <id> --provider nuitee

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 |