Travel

Hotelist

hotelist-pp-cli

Every Hotelist feature, plus a local SQLite mirror that ranks rating-per-dollar across whole countries, compares chains head-to-head, and tracks how a city's hotels change over time.

Printed by @dbryson (David Bryson)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install hotelist

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-hotelist --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-hotelist skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-hotelist. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Every Hotelist feature, plus a local SQLite mirror that ranks rating-per-dollar across whole countries, compares chains head-to-head, and tracks how a city's hotels change over time.

Hotelist.com (by @levelsio) rates hotels with AI: it reads real traveler reviews, scores actual room photos, and photo-verifies claimed amenities so you can filter on a gym with real weights or a bathtub that actually exists. This CLI puts that data in your terminal and in agent context with --json/--select output, an offline cache, and cross-location commands the single-map website can't express: rank-country, chain-compare, corridor, and a watch/diff drift tracker. Data is scraped from Hotelist (community/AI-rated, not an official API).

Quick Start

# Health check: confirms Hotelist.com is reachable before you search.
hotelist-pp-cli doctor --dry-run

# AI-rated hotels in a city, sorted by Hotelist Score.
hotelist-pp-cli search bangkok --json

# Photo-verified amenities: a real weightlifting gym and a pool.
hotelist-pp-cli filter lisbon --gym-weights --pool --json

# Best rating-per-dollar in a location.
hotelist-pp-cli value tulum --json

# National value leaderboard the website's map UI can't produce.
hotelist-pp-cli rank-country portugal --min-rating 8 --max-price 150 --json

Unique Features

These capabilities aren't available in any other tool for this API.

Cross-location value the map UI can't express

rank-country — Rank the best hotels across an entire country by Hotelist rating-per-dollar, with compound amenity and price filters.

When an agent needs the single best-value hotel in a whole country under hard constraints, reach for this instead of paging city-by-city search.
```
hotelist-pp-cli rank-country thailand --min-rating 8 --max-price 150 --amenities pool,coworking --json
```
chain-compare — Compare hotel chains head-to-head on mean rating, median price, and rating-per-dollar in a country.

Answers 'which chain is actually worth it here?' in one call instead of a dozen manual map filters.
```
hotelist-pp-cli chain-compare --chains marriott,hilton,hyatt --country japan --metric best-value --json
```
corridor — Find the best hotel in each stop of a multi-city route in one pass, with shared filters.

Plans a nomad's annual route in one command; pick this over N separate searches when the user names several cities.
```
hotelist-pp-cli corridor --cities "Chiang Mai,Lisbon,Medellin" --min-rating 7.5 --max-price 120 --amenities coworking --json
```

Local state that compounds

watch — Snapshot a saved location over time and diff which hotels improved, declined, or changed price since you last checked.

The only way to answer 'did this city's hotels get better or more expensive since last time?' — pick it for any change-over-time question.
```
hotelist-pp-cli watch diff lisbon --since 2026-01-01 --metric both --json
```
chain-consistency — Compute mean, median, and spread of a single chain's ratings across a country to see if the brand is reliably good or full of outliers.

Use before trusting a loyalty brand in an unfamiliar region; surfaces hidden outlier risk a single listing can't show.
```
hotelist-pp-cli chain-consistency --chain marriott --country thailand --json
```
price-cliff — Find the price point in a city where rating-per-extra-dollar collapses — the cheapest hotel that's still legitimately good.

Turns 'spend the least without sacrificing quality' into one number plus the hotels just below the cliff.
```
hotelist-pp-cli price-cliff bangkok --min-rating 7 --json
```

Recipes

Best-value hotel with a real gym in a city

hotelist-pp-cli filter lisbon --gym-weights --json --select hotels.name,hotels.hotellist_rating,hotels.price

Photo-verified weightlifting gym, narrowed to just name/rating/price so an agent doesn't parse the full payload.

National value leaderboard

hotelist-pp-cli rank-country thailand --min-rating 8 --max-price 150 --top 10 --json

Top 10 hotels by rating-per-dollar across the whole country in one call.

Compare loyalty chains before committing

hotelist-pp-cli chain-compare --chains marriott,hyatt --country japan --metric best-value --json

Head-to-head mean rating, median price, and value per chain.

Plan a nomad route

hotelist-pp-cli corridor --cities "Chiang Mai,Lisbon,Tbilisi" --min-rating 7.5 --max-price 120 --json

Best hotel per stop that clears all filters, in one pass.

Deep-dive one hotel's AI breakdown

hotelist-pp-cli show KYLCGAVE --json

Full Hotelist Score, AI photo and review ratings, consensus, verified amenities, pros and cons.

Usage

Run hotelist-pp-cli --help for the full command reference and flag list.

Commands

hotel

A single AI-rated hotel from Hotelist.

hotelist-pp-cli hotel <hotel_id> - Fetch the raw detail-modal HTML for one hotel (Hotelist Score, verified amenities, AI rating breakdown). The 'show' command parses this into structured fields.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
hotelist-pp-cli hotel mock-value

# JSON for scripting and agents
hotelist-pp-cli hotel mock-value --json

# Filter to specific fields
hotelist-pp-cli hotel mock-value --json --select id,name,status

# Dry run — show the request without sending
hotelist-pp-cli hotel mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
hotelist-pp-cli hotel mock-value --agent

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
Offline-friendly - sync/search commands can use the local SQLite store when available
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.

Health Check

hotelist-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

Config file: ~/.config/hotelist/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Troubleshooting

Not found errors (exit code 3)

Check the resource ID is correct
Run the list command to see available items

API-specific

search returns an empty list for a city — Run 'hotelist-pp-cli sync cities' to refresh the city-to-geohash table, then retry; the city name must match a Hotelist city.
prices look off or undated — Hotelist prices are AI-estimated nightly figures, not live date-specific quotes; --checkin/--checkout are display context only, not a backend filter.
stale results — Add --fresh to bypass the local cache and re-fetch from Hotelist; default cache is fresh-on-read with a domain-appropriate stale window.
HTTP 429 or slow responses — The CLI rate-limits politely by design; lower concurrency with --max-scan-pages on multi-location commands or wait and retry.