--- name: pp-seats-aero description: "Every Seats.aero Partner API endpoint, plus a local award-availability store that tells you what is new, what is still live, and where your miles reach nonstop. Trigger phrases: `find award seats to Tokyo in business`, `what award availability is new since yesterday`, `where can my miles take me nonstop from JFK`, `is this award seat still available before I book`, `show me the award calendar for united to Europe`, `use seats-aero`, `run seats-aero`." author: "Cathryn Lavery" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - seats-aero-pp-cli install: - kind: go bins: [seats-aero-pp-cli] module: github.com/mvanhorn/printing-press-library/library/travel/seats-aero/cmd/seats-aero-pp-cli --- # Seats.aero — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `seats-aero-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 seats-aero --cli-only ``` 2. Verify: `seats-aero-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/seats-aero/cmd/seats-aero-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. seats-aero-pp-cli wraps all seven Partner API endpoints (cached search, bulk availability, trips, routes, destinations, refresh, live) with agent-native output, then syncs routes and availability into typed SQLite tables. That local store powers new-since, calendar, direct-scan, reach and a quota-guarded recheck, none of which a thin wrapper or the web app can do. ## When to Use This CLI Use seats-aero-pp-cli whenever an agent needs award-flight availability by mileage program: cheapest awards on a route, a program's calendar, nonstop reach from an airport, or verifying a cached seat before booking. It is the right tool for miles-and-points redemption research and for building a local award-availability corpus that can be queried offline. ## Anti-triggers Do not use this CLI for: - Do not use it to book or ticket a flight; it reports availability only and never books. - Do not use it for cash fares, hotel awards, points valuations, or transfer-partner math; the Partner API carries none of that. - Do not use it to set push alerts; Seats.aero alerts are a web-app feature, use new-since on a schedule instead. - Do not expect live search with a Pro key; that endpoint is commercial-agreement only. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Local state that compounds - **`new-since`** — See which award seats appeared on a route since you last looked, from your synced local data. _Reach for this when the user asks what changed or what is new on a route, instead of re-running a full search and diffing by eye._ ```bash seats-aero-pp-cli new-since --origin JFK --destination NRT --cabin business --since 24h --agent ``` - **`direct-scan`** — Find direct-flight award seats under a mileage ceiling across every synced program at once. _Pick this over the awards search when the user wants nonstop-only results across programs from already-synced data with zero API calls._ ```bash seats-aero-pp-cli direct-scan --origin JFK --destination NRT --cabin business --max-mileage 90000 --sources united,virginatlantic,aeroplan --agent ``` - **`calendar`** — Turn one route's synced availability into a date-by-cabin matrix you can scan at a glance. _Use this when the user asks which dates have business or first availability on a route; it answers from the local store in one shot._ ```bash seats-aero-pp-cli calendar --origin JFK --destination NRT --source united --start 2026-10-01 --end 2026-12-31 --agent ``` ### Quota-aware plumbing - **`recheck`** — Re-verify aging award rows are still live right before booking. It performs one live quota probe per run (1 daily call), and --apply is refused when quota is unknown unless --ignore-quota is passed. _Print-only by default: lists the aging rows it would refresh, their age, and the remaining daily quota (one probe call). Add --apply to spend refresh credits; --apply is refused when the quota is unknown unless --ignore-quota is passed._ ```bash seats-aero-pp-cli recheck --origin JFK --destination NRT --cabin business --max-mileage 90000 --agent ``` - **`reach`** — Discover where your miles can take you nonstop from one airport, ranked by cost and cross-checked against real dated seats. _Reach for this when the user has miles but no fixed destination. It has no local mode, and results is an object {origin, cabin, max_mileage, source, destinations[]} rather than a bare array. --confirm-live makes up to 10 extra live /search calls (opt-in; never under the test harness)._ ```bash seats-aero-pp-cli reach --origin JFK --cabin business --max-mileage 90000 --top 10 --agent ``` ## Command Reference ## Upgrading from 2026.8.1 `seats-aero-partner-search` was renamed to `awards`; the old command remains a hidden, deprecated alias for one release. Its `--cabin` flag is now `--cabins` and accepts comma-separated values. Existing stores are migrated by the first read-write command, such as `sync`; `doctor` is read-only and reports `migration_pending` without changing the store. The credential environment variable is now `SEATS_AERO_API_KEY`. `SEATS_AERO_PARTNER_PARTNER_AUTHORIZATION` and the TOML key `aero_partner_partner_authorization` are still honoured; `doctor` reports the selected `credentials_location`. The store is migrated in place on the first read-write command (`sync` or `doctor`), while the legacy `seats_aero_partner_search` table is left untouched. `sync --concurrency` now defaults to `1` (was `4`), and `--timeout` now defaults to `1m` (was `30s`). The MCP tool is now `awards_cached-search`. **availability** — Manage availability - `seats-aero-pp-cli availability` — Retrieve a large amount of availability objects from one specific mileage program. **awards** — Manage awards - `seats-aero-pp-cli awards` — Search Seats.aero cached award availability between one or more origin and destination airports, across one or more mileage programs. **destinations** — Manage destinations - `seats-aero-pp-cli destinations` — Returns the airports reachable from (or to) a single airport **live** — Manage live - `seats-aero-pp-cli live` — Commercial-agreement API keys only; Pro keys receive 403 -- do not retry. 5-15 s latency. **refresh** — Manage refresh - `seats-aero-pp-cli refresh` — Use this endpoint to refresh old cached data; credit-metered; the response quota block shows remaining refreshes; Pro keys only. **reach** — Discover nonstop destinations within a mileage ceiling - `seats-aero-pp-cli reach` — Has no local mode, and `results` is an object `{origin, cabin, max_mileage, source, destinations[]}` rather than a bare array. `--confirm-live` makes up to 10 extra live `/search` calls (opt-in; never under the test harness). **recheck** — Re-verify aging award rows before booking - `seats-aero-pp-cli recheck` — Print-only by default; performs one live quota probe per run (1 daily call). `--apply` is refused when the quota is unknown unless `--ignore-quota` is passed. **routes** — Manage routes - `seats-aero-pp-cli routes` — Get all origin-destination routes tracked for a mileage program. **trips** — Manage trips - `seats-aero-pp-cli trips ` — Retrieve flight-level information from an Availability object by its revalidation/trip ID from search or availability results. ## Freshness Contract This printed CLI owns bounded freshness only for registered store-backed read command paths. In `--data-source auto` mode, those paths check `sync_state` and may run a bounded refresh before reading local data. `--data-source local` never refreshes. `--data-source live` reads the API and does not mutate the local store. Set `SEATS_AERO_NO_AUTO_REFRESH=1` to skip the freshness hook without changing source selection. `sync` and `sync --resources availability` cannot populate availability because the endpoint requires `source`. Use `seats-aero-pp-cli sync --resources availability --resource-param availability:source= --since 7d` once per program. The `routes` resource needs no parameter. Covered paths: - `seats-aero-pp-cli availability` - `seats-aero-pp-cli availability get` - `seats-aero-pp-cli availability list` - `seats-aero-pp-cli availability search` - `seats-aero-pp-cli awards` - `seats-aero-pp-cli awards get` - `seats-aero-pp-cli awards list` - `seats-aero-pp-cli awards search` - `seats-aero-pp-cli destinations` - `seats-aero-pp-cli destinations get` - `seats-aero-pp-cli destinations list` - `seats-aero-pp-cli destinations search` - `seats-aero-pp-cli routes` - `seats-aero-pp-cli routes get` - `seats-aero-pp-cli routes list` - `seats-aero-pp-cli routes search` When JSON output uses the generated provenance envelope, freshness metadata appears at `meta.freshness`. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash seats-aero-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. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Cheapest business awards across all programs, narrowed for an agent ```bash seats-aero-pp-cli awards --origin-airport SFO --destination-airport NRT --cabins business --order-by lowest_mileage --take 10 --agent --select data.Date,data.Route.Source,data.JMileageCost,data.JDirect ``` One cached search across every program, with --select trimming the wide availability rows to the four fields that matter. ### What appeared since yesterday ```bash seats-aero-pp-cli new-since --origin JFK --destination NRT --cabin business --since 24h --agent ``` Diffs the local availability table on first_seen_at, so only genuinely new rows come back. ### Verify before you book, without spending credits ```bash seats-aero-pp-cli recheck --origin JFK --destination NRT --cabin business --max-mileage 90000 --agent ``` Print-only by default: lists the aging rows it would refresh, their age, and the remaining daily quota (one probe call). Add --apply to spend refresh credits. ### Direct-only under 90k miles across three programs ```bash seats-aero-pp-cli direct-scan --origin JFK --destination NRT --cabin business --max-mileage 90000 --sources united,virginatlantic,aeroplan --agent ``` A cross-program join over synced data that the one-program-per-call bulk endpoint cannot answer. ### Where can 90k miles take me nonstop ```bash seats-aero-pp-cli reach --origin JFK --cabin business --max-mileage 90000 --top 10 --agent ``` Fans out via destinations then confirms each candidate against dated seats. reach has no local mode, and results is an object {origin, cabin, max_mileage, source, destinations[]} rather than a bare array. --confirm-live makes up to 10 extra live /search calls (opt-in; never under the test harness). ## Auth Setup Seats.aero Pro subscribers create a Partner API key under Settings, then export it as SEATS_AERO_API_KEY. Keys are Pro-tier (1,000 calls per day, resets at midnight UTC; the X-RateLimit-Remaining header tracks it) or commercial-agreement keys. Pro keys cannot call live search and commercial keys cannot call refresh; doctor reports the remaining daily calls and which tier your key appears to be. Run `seats-aero-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **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 seats-aero-pp-cli destinations --agent --select airport,business,economy ``` - **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 `SEATS_AERO_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `SEATS_AERO_CONFIG_DIR`, `SEATS_AERO_DATA_DIR`, `SEATS_AERO_STATE_DIR`, `SEATS_AERO_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `SEATS_AERO_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 `seats-aero-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": { "seats-aero": { "command": "seats-aero-pp-mcp", "env": { "SEATS_AERO_HOME": "/srv/seats-aero" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `SEATS_AERO_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 `SEATS_AERO_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 seats-aero-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": ["", "seats-aero-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 slo