@travalanpm/travel-cli

A command-line tool for hotel search and booking management. Designed to be called by AI agents through Agent Skills.

Booking is handled separately

This CLI does not include a book command. The booking endpoint of the travel API is x402-paywalled (HTTP 402 Payment Required + USDC on Base), and payment is handled by Coinbase's awal CLI:

npx awal@latest x402 pay <booking-url> -X POST -q '{...}' -d '{...}'

This split keeps wallet/key handling fully inside Coinbase's secure infrastructure. See the travel-skills repo for the full skill that orchestrates search + auth + fund + pay.

Install

npm install -g @travalanpm/travel-cli

Or run without installing:

npx @travalanpm/travel-cli@latest search-hotel --location "Tokyo" --checkin 2026-05-01 --checkout 2026-05-05

Configuration

export TVL_API_URL="https://api.travala.com"

If unset, the CLI uses the default production URL baked into src/utils/api.js.

Commands

travel-cli search-hotel

Search hotels by location and dates.

travel-cli search-hotel \
  --location "Da Nang, Vietnam" \
  --checkin 2026-06-14 \
  --checkout 2026-06-18 \
  --rooms "2" \
  --lat 16.0544 \
  --lng 108.2022

Options:

• --location <name> (required) — City or destination
• --checkin <date> (required) — YYYY-MM-DD
• --checkout <date> (required) — YYYY-MM-DD
• --rooms <occupancy> — e.g. "2" (1 room, 2 adults), "2,5" (2 adults + child age 5). Multiple rooms separated by ;
• --lat <num> --lng <num> — coordinates for precision
• --min-price <usd> --max-price <usd> — price filters in USD
• --limit <n> — max results (default 5)
• --filters <list> — comma-separated: free_breakfast,swimming_pool,ocean_view,all_inclusive

Returns JSON with sessionId (use it in follow-up calls) and an array of hotels with packageId for each.

travel-cli search-package

Get room types and rate packages for a specific hotel.

travel-cli search-package \
  --hotel-id "38894021" \
  --session-id "0aidL5kXJVtAS9oz" \
  --checkin 2026-06-14 \
  --checkout 2026-06-18 \
  --rooms "2"

travel-cli manage-booking

Retrieve booking details.

travel-cli manage-booking \
  --booking-id "MO45L74J" \
  --last-name "nguyn" \
  --email "[email protected]"

travel-cli cancel

Cancel a booking.

travel-cli cancel \
  --booking-id "MO45L74J" \
  --last-name "nguyn" \
  --email "[email protected]"

travel-cli book-status

Check whether a booking actually went through after awal x402 pay reports a post-authorization failure (e.g. Payment was authorized but rejected by server). The booking server may have settled and reserved the room even if the response didn't reach the agent in time — blindly retrying causes a double charge.

travel-cli book-status \
  --package-id "e47otEJtYeZYblF9" \
  --session-id "6kVmPYwZhQJewNTp"

Output is always JSON { httpStatus, body, interpretation }:

| httpStatus | Meaning | Action | | ------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- | | 200 | Booking already succeeded; body has transaction + bookingId. | Treat as success. Do not retry payment. | | 202 | Server still settling. | Wait body.retry_after_ms, then poll again (cap ~10s, ~6 polls). | | 404 | Nothing happened server-side. | Safe to retry the original awal x402 pay. | | 5xx | Recovery endpoint itself is down. | Tell the user to check email / awal wallet history. Do not retry. |

Override the recovery host (defaults to the production m2m payment service) with TVL_RECOVERY_URL:

export TVL_RECOVERY_URL="https://payment-mcp.travala.com"

Booking workflow (full picture)

# 1. Search
travel-cli search-hotel --location "Da Nang, Vietnam" --checkin 2026-06-14 --checkout 2026-06-18
# → returns sessionId + list of hotels with packageIds

# 2. (Optional) Browse rooms for one hotel
travel-cli search-package --hotel-id 38894021 --session-id 0aidL5kXJVtAS9oz \
  --checkin 2026-06-14 --checkout 2026-06-18

# 3. Authenticate the wallet (one time)
npx awal@latest authenticate --email [email protected]

# 4. Book and pay in one call (x402)
#    package_id + session_id go in the query string (-q),
#    contact goes in the body (-d).
npx awal@latest x402 pay https://payment-mcp.travala.com/m2m-payment/book/v2 \
  -X POST \
  -q '{"package_id":"e47otEJtYeZYblF9","session_id":"6kVmPYwZhQJewNTp"}' \
  -d '{"contact":{"given_name":"Justin","sur_name":"Ta","email":"[email protected]","phone":"+84336657091"}}' \
  --max-amount 1850000000

# 5. Look up the booking later
travel-cli manage-booking --booking-id MO45L74J --last-name "nguyn" --email [email protected]

Output format

All commands output JSON to stdout. Errors go to stderr with a non-zero exit code:

{ "error": "...", "code": "..." }

License

MIT