--- name: pp-travelclick description: "Search any TravelClick-powered hotel's own rates directly -- room types, rate plans, fee-inclusive pricing, and the cheapest night to book -- without opening a browser tab per property. Trigger phrases: `check travelclick rates`, `search made hotel availability`, `find the cheapest night at this hotel`, `validate this corporate hotel code`, `compare these boutique hotels`, `use travelclick`, `run travelclick`." author: "Allen Lew" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - travelclick-pp-cli install: - kind: go bins: [travelclick-pp-cli] module: github.com/mvanhorn/printing-press-library/library/travel/travelclick/cmd/travelclick-pp-cli --- # TravelClick — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `travelclick-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install travelclick --cli-only ``` 2. Verify: `travelclick-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/travel/travelclick/cmd/travelclick-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. TravelClick/iHotelier powers the direct-booking widget for thousands of independent and boutique hotels. This CLI calls the same JSON API the widget itself uses to search availability, scan a date range for the lowest rate, validate corporate/group codes, and compare several hotels side by side. Search and info only -- no reservation, no guest PII, no payment data ever touches it. ## When to Use This CLI Use this CLI when checking a specific independent or boutique hotel's own direct rates -- price-matching against an OTA, finding the cheapest date for a stay, validating a corporate or event code, or comparing a handful of TravelClick-powered properties for the same trip. ## Anti-triggers Do not use this CLI for: - Do not use this CLI to make or modify a reservation -- it is search/info only and has no booking command by design. - Do not use this CLI for hotels that don't use TravelClick/iHotelier as their booking engine -- check that the hotel's booking URL is bookings.travelclick.com first. - Do not use this CLI to look up a guest's existing reservation, loyalty account, or payment details -- those require guest login and are out of scope. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Cross-hotel local queries - **`rates compare`** — Check several boutique hotels for the same dates in one call, ranked by lowest fee-inclusive total. _Reach for this when the user names more than one property for the same trip instead of calling 'rates search' repeatedly._ ```bash travelclick-pp-cli rates compare --hotels 102306,, --check-in 2026-09-15 --check-out 2026-09-18 ``` - **`rates cheapest-night`** — Scan several hotels' calendars at once and return the single best hotel+date combination. _Reach for this when the user is flexible on both hotel and date, not just date._ ```bash travelclick-pp-cli rates cheapest-night --hotels made-nyc, --from 2026-09-01 --to 2026-10-31 ``` - **`codes check-all`** — Test one corporate or group code against every saved hotel at once. _Reach for this when the user has a code but isn't sure which of their saved hotels honors it._ ```bash travelclick-pp-cli codes check-all ACME2026 --type corporate --hotels made-nyc, ``` ### Local state that compounds - **`hotels alias`** — Give a memorable name to a TravelClick hotel ID instead of memorizing a 6-digit number. _Reach for this before repeated lookups against the same property so later commands can take the alias instead of the raw ID._ ```bash travelclick-pp-cli hotels alias add made-nyc 102306 ``` - **`analytics price-drift`** — Track how a hotel's rates move over time from your own saved search history. _Reach for this after the user has run a few 'rates search --save' calls and wants to know if a rate went up or down._ ```bash travelclick-pp-cli analytics price-drift --hotel 102306 ``` ## HTTP Transport This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls. ## Discovery Signals This CLI was generated with browser-observed traffic context. - Capture coverage: 5 API entries from 5 total network entries - Protocols: rest_json (75% confidence) - Auth signals: bearer_token — headers: Authorization - Candidate command ideas: create_multi_room — Derived from observed POST /ibe-shop/v1/hotel/{hotel_id}/basicavail/multi-room traffic.; get_TEST123 — Derived from observed GET /ibe-codes/v1/hotel/{hotel_id}/specialcodes/corporate/TEST123 traffic.; get_avail — Derived from observed GET /ibe-shop/v1/hotel/{hotel_id}/avail traffic.; get_info — Derived from observed GET /ibe-entity/v1/hotel/{hotel_id}/info traffic. - Caveats: error_status_cluster: Endpoint cluster only observed error HTTP statuses.; error_status_cluster: Endpoint cluster only observed error HTTP statuses. ## Command Reference **codes** — Validate special rate codes (corporate/rate-access or group-attendee) against a hotel before applying them to a search. - `travelclick-pp-cli codes validate-corporate` — Check whether a corporate / rate-access code is valid for this hotel. - `travelclick-pp-cli codes validate-group` — Check whether a group-attendee code is valid for this hotel. **hotel** — Read-only hotel property information: address, policies, check-in/out times, and amenities. No PII, no reservation data. - `travelclick-pp-cli hotel ` — Fetch a hotel's public profile: name, address, geolocation, check-in/out times, accepted cards **rates** — Search room availability and rate plans for specific dates, or scan a date range for the cheapest night. - `travelclick-pp-cli rates calendar` — Scan a date range (up to ~60 days) - `travelclick-pp-cli rates search` — Search available rooms and rate plans for a hotel between check-in and check-out. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash travelclick-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Recipes ### Cheapest room+rate for a stay ```bash travelclick-pp-cli rates search 102306 --check-in 2026-09-15 --check-out 2026-09-18 --agent --select roomStays.roomTypes.roomTypeName,roomStays.roomTypes.averageRates.rate,roomStays.roomTypes.averageRates.rateExternalCode ``` Narrows the deeply-nested avail response to just room name, rate, and rate code per plan instead of the full policy/amenity/image payload. ### Find the cheapest night in a month ```bash travelclick-pp-cli rates calendar 102306 --from 2026-09-01 --to 2026-09-30 --json ``` Returns the lowest rate for every day in the range so you can sort for the minimum. ### Check a corporate code before searching ```bash travelclick-pp-cli codes validate-corporate 102306 ACME2026 ``` Confirms whether a rate-access code is live for this hotel. **Validating a code does not currently let you search rates for it** — see Known Limitations below before assuming this recipe's name describes the full workflow. ### Compare three boutique hotels for the same weekend ```bash travelclick-pp-cli rates compare --hotels 102306,, --check-in 2026-09-15 --check-out 2026-09-18 ``` Fans out the search across hotels and ranks them by lowest fee-inclusive total. ## Known Limitations **No way to search rates for a specific corporate/rate-access code.** `codes validate-corporate` and `codes validate-group` can only confirm whether a code is valid — `rates search` has no `--corporate-code`, `--rate-plan-id`, or equivalent parameter to actually filter results to that code's rate plan once validated. Confirmed by checking the discovery sample for `codes validate-corporate`: the only captured response is a 404 (`INVALID_CORP_ID`, from testing an intentionally-fake `TEST123` code) — discovery never observed what a *successful* validation returns, so neither the generator nor this CLI's author ever saw whether that response carries a rate plan ID, a discount code, or anything `rates search` could consume. The "Check a corporate code before searching" recipe above validates the code but cannot actually chain into a filtered search; treat it as a standalone validity check only. **Real, verified workaround**: the booking widget itself accepts a page-level `RatePlanId` query parameter that pre-selects a specific corporate rate — `https://reservations.travelclick.com/{hotel_id}?RatePlanId={id}` (redirects to `bookings.travelclick.com/{hotel_id}?RatePlanId={id}#/guestsandrooms`). Verified working directly against a real hotel ID with a valid corporate `RatePlanId`: the page loads with that specific negotiated rate pre-selected under Accommodations, and its real price is readable from the rendered page. This is a *page-level* UI parameter, not a confirmed `/ibe-shop/v1/hotel/{hotel_id}/avail` API query parameter — it was not captured at the network level, only observed working through the rendered widget, so it cannot be wired into `rates search`'s params without a fresh discovery pass that captures the underlying API call while this URL parameter is present. Until then, a specific corporate rate's real price has to be read from the widget directly (this URL pattern), not from this CLI. (The specific hotel/rate-plan pair used to verify this is omitted deliberately: pairing a real `RatePlanId` with the corporation it belongs to discloses that company's negotiated pricing to anyone who reads this file, so treat any `RatePlanId` you test with as sensitive and don't publish it alongside the company name.) **If you have a real corporate/rate-access code to test with**: re-running discovery's browser-sniff against `codes validate-corporate` with that valid code (not `TEST123`) would capture the missing successful-response shape, and re-sniffing `avail` while the widget has a `RatePlanId` selected would likely surface the real API-level parameter name. Either capture would unblock a durable fix; noting this so it doesn't require re-discovering the gap from scratch. ## Auth Setup TravelClick's widget mints a short-lived (~1 hour) OAuth2 client_credentials Bearer token client-side during page load. The exact token-mint endpoint was not isolated during discovery (it fires before any capture hook can attach), so this CLI cannot mint its own token yet -- capture one manually: open the hotel's booking page in Chrome, open DevTools' Network tab, filter for api.travelclick.com, click any request, and copy the Authorization header's value (everything after 'Bearer ') into TRAVELCLICK_TOKEN. Re-capture roughly every hour. Run `travelclick-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash travelclick-pp-cli rates search mock-value --check-in 2026-01-15 --check-out 2026-01-15 --agent --select timeSpan,roomTypes,allRoomTypes ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `TRAVELCLICK_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `TRAVELCLICK_CONFIG_DIR`, `TRAVELCLICK_DATA_DIR`, `TRAVELCLICK_STATE_DIR`, `TRAVELCLICK_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `TRAVELCLICK_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `travelclick-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "travelclick": { "command": "travelclick-pp-mcp", "env": { "TRAVELCLICK_HOME": "/srv/travelclick" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `TRAVELCLICK_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `TRAVELCLICK_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash travelclick-pp-cli recall "" --agent ``` The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "travelclick-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `travelclick-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes verbatim before any discovery step; they carry known gotchas for this query family even when no structured choreography exists yet. elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2: -> skip discovery; fetch live data for Results[*].ResourceID in parallel elif Found AND Results[0].EntityMatch == "partial": -> candidate hint, NOT a hit; read the resource title to validate before trusting elif (any row in Mismatches[] when --debug-mismatches was passed): -> treat as cold start; the stored learning is for a different entity (different canonical resolved from query_entities) else: // Found == false, no playbook, no notes -> cold start; run discovery normally; teach the answer afterward (Step 4). If the family has no playbook yet, that teach auto-synthesi