Roadside America CLI

Every offbeat roadside attraction on RoadsideAmerica.com — with a local SQLite cache, offline search, and superlative categories no other tool offers.

RoadsideAmerica.com is the web's best catalog of quirky US & Canada tourist attractions, but it has no API and a paywalled app. This CLI turns it into an agent-native, pipe-friendly tool: find what's near a place or coordinates, browse a whole state, pull the full writeup, and slice by superlative categories like biggest/smallest/tallest/weird-food. Everything is cached locally (fresh-on-read), every record links back to its source, and the scraper stays a polite, attributing, user-initiated citizen of the site.

Quick Start

# health + reachability check; no auth needed
roadside-america-pp-cli doctor

# quirky attractions near a city (geocoded), within 20 miles
roadside-america-pp-cli near "Austin, TX" --radius 20

# browse offbeat attractions in a state
roadside-america-pp-cli state TX --limit 10

# full writeup + location + source link for one attraction
roadside-america-pp-cli show 2055

Unique Features

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

Local cache intelligence

• category — Find the biggest, smallest, tallest, or weird-food attractions (and more) by classifying cached attractions locally.

  Reach for this when the user wants superlatives or a themed slice (giants, muffler-men, weird-food) rather than a place- or state-scoped list.

  roadside-america-pp-cli category biggest --json
  

• stats — Summarize the local cache: counts by state and by category, plus totals.

  Use to understand coverage of the local cache before planning, or to answer 'which state has the most offbeat stuff cached'.

  roadside-america-pp-cli stats --agent
  

• random — Pick a random offbeat attraction, optionally constrained by state or category.

  Use for serendipity or road-trip inspiration when the user has no specific target.

  roadside-america-pp-cli random --state TX
  

Route & comparison

• trip — Collect quirky stops near a list of cities or coordinates in one call, deduped and labeled by stop.

  Reach for this when planning a route and the user wants offbeat stops across several waypoints at once.

  roadside-america-pp-cli trip "Austin, TX" "Waco, TX" --radius 15 --json
  

• compare — Compare two states by offbeat-attraction count and surface a few top picks from each.

  Use when the user is deciding between regions or wants a quick 'which state is weirder' answer.

  roadside-america-pp-cli compare TX CA
  

Recipes

Quirky stops near coordinates, agent-friendly fields

roadside-america-pp-cli near 30.27,-97.74 --radius 25 --agent --select name,city,distance,source_url

Pass raw lat,lng to skip geocoding and select only the fields an agent needs.

Weird food across a cached state

roadside-america-pp-cli category weird-food --json

Classifies cached attractions by food keywords; populate the cache with state/near first.

Plan offbeat stops across a route

roadside-america-pp-cli trip "Austin, TX" "Waco, TX" "Dallas, TX" --radius 15 --json

Aggregates nearby attractions for each waypoint, deduped and labeled by stop.

Full writeup with source attribution

roadside-america-pp-cli show 2055 --json

Returns structured name/address/writeup plus the RoadsideAmerica.com source URL.

Usage

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

Commands

raw

Raw RoadsideAmerica.com passthrough (HTML link/page extraction). Prefer the top-level near / state / show / category commands for structured output.

• roadside-america-pp-cli raw by-state - Raw attraction links for a US/Canada state (HTML fragment).
• roadside-america-pp-cli raw detail - Raw attraction detail page (HTML).
• roadside-america-pp-cli raw nearby - Raw nearby attraction links for coordinates (HTML fragment).

Output Formats

# Human-readable table (default in terminal, JSON when piped)
roadside-america-pp-cli raw by-state --state example-value

# JSON for scripting and agents
roadside-america-pp-cli raw by-state --state example-value --json

# Filter to specific fields
roadside-america-pp-cli raw by-state --state example-value --json --select id,name,status

# Dry run — show the request without sending
roadside-america-pp-cli raw by-state --state example-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
roadside-america-pp-cli raw by-state --state example-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

roadside-america-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

Config file: ~/.config/roadside-america-pp-cli/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

• Slow responses or HTTP 429 — The CLI self-limits to ~1 request/3s and caches in SQLite; let it back off, or rely on cached data (results show fetched_at).
• near "" returns nothing — Widen --radius, or pass coordinates directly: near 30.27,-97.74 --radius 25.
• Geocoding a place name fails — Pass latitude,longitude directly to near/trip; geocoding uses keyless OSM Nominatim which may rate-limit.
• category returns few results — Categories classify the LOCAL cache; run state/sync/near first to populate, then re-run category.