Atlas Obscura CLI

Every Atlas Obscura search, plus a local database, road-trip corridor routing, and saved trips no other Atlas Obscura tool has.

Search the world's hidden wonders by keyword or coordinates, pull full place detail with Know-Before-You-Go notes, and mirror it all into a local SQLite store for offline, agent-native use. Then go further than any scraper: find wonders along a driving route, save and export trips, and track what you've visited. Community-sourced from atlasobscura.com — not an official API.

Learn more at Atlas Obscura.

Created by @dbryson (David Bryson).

Quick Start

# health check; works with no setup since Atlas Obscura needs no API key
atlas-obscura-pp-cli doctor --dry-run

# keyword search across all wonders
atlas-obscura-pp-cli search "catacombs" --json

# wonders within 5 miles of a place, sorted by distance
atlas-obscura-pp-cli near "Paris" --radius 5 --json

# full detail incl. Know Before You Go
atlas-obscura-pp-cli show gustave-eiffels-secret-apartment

# wonders along the drive
atlas-obscura-pp-cli route "San Francisco" "Los Angeles" --limit 10 --json

Unique Features

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

Trip planning

• route — Find Atlas Obscura wonders along the driving corridor between two cities, not just in one place.

  Reach for this when a user is driving between two places and wants worthwhile stops along the way.

  atlas-obscura-pp-cli route "San Francisco" "Los Angeles" --min-score 6 --limit 15 --json
  

• cluster — Group nearby wonders into spatially tight clusters that make a walkable half-day.

  Use to turn a pile of nearby wonders into an efficient day on foot.

  atlas-obscura-pp-cli cluster "Edinburgh" --radius 3 --min 3 --json
  

• export — Serialize a saved trip to GPX, GeoJSON, or a markdown itinerary, fully offline.

  Use to hand a road trip to a GPS, a map tool, or a human-readable log.

  atlas-obscura-pp-cli export california-oddities --format md
  

Local state that compounds

• trip — Accumulate places into named itineraries that persist across sessions.

  Use to build up a trip over multiple sessions instead of re-searching each time.

  atlas-obscura-pp-cli trip add winchester-mystery-house --trip california-oddities
  

• visited — Record which wonders you've seen, with optional date and note.

  Use to remember what you've already seen so gaps and surprise can skip them.

  atlas-obscura-pp-cli visited mark salvation-mountain --note "worth the desert drive"
  

• gaps — Show good wonders near a point that you haven't visited yet, ranked by interestingness.

  Use to plan what's left to see near a place you're revisiting.

  atlas-obscura-pp-cli gaps "Portland, Oregon" --radius 40 --min-score 6 --json
  

• surprise — Pick one high-interest wonder you haven't visited, seeded by date so it's stable per day.

  Use in a daily agent heartbeat to surface a fresh wonder without repeats.

  atlas-obscura-pp-cli surprise --near "Tokyo" --exclude-visited --json
  

Recipes

Plan stops along a road trip

atlas-obscura-pp-cli route "Denver" "Moab" --min-score 6 --limit 12 --json

Surfaces the best-scoring wonders within the driving corridor between two cities.

Lean nearby scan for an agent

atlas-obscura-pp-cli near "35.0116,135.7681" --radius 3 --json --select results.title,results.distance_from_query,results.url

Deeply nested response narrowed to just title, distance, and URL so an agent doesn't parse image and coordinate noise.

Build and export a trip

atlas-obscura-pp-cli trip add winchester-mystery-house --trip ca && atlas-obscura-pp-cli export ca --format md

Accumulate places into a named trip, then render a markdown itinerary with descriptions and Know Before You Go.

What haven't I seen near home

atlas-obscura-pp-cli gaps "Austin, Texas" --radius 30 --min-score 6 --json

Cross-references cached wonders against your visited log and returns only the worthwhile unseen ones.

Usage

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

Commands

categories

Browse places by Atlas Obscura category

• atlas-obscura-pp-cli categories <slug> - List place links in a category (e.g. cemeteries, caves, ruins)

destinations

Browse places by destination (city/region)

• atlas-obscura-pp-cli destinations <slug> - List place links for a destination (e.g. paris-france, new-york)

places

Atlas Obscura places (wonders)

• atlas-obscura-pp-cli places <slug> - Fetch a place detail page by slug or numeric id

Output Formats

# Human-readable table (default in terminal, JSON when piped)
atlas-obscura-pp-cli places mock-value

# JSON for scripting and agents
atlas-obscura-pp-cli places mock-value --json

# Filter to specific fields
atlas-obscura-pp-cli places mock-value --json --select id,name,status

# Dry run — show the request without sending
atlas-obscura-pp-cli places mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
atlas-obscura-pp-cli places 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

atlas-obscura-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

Config file: ~/.config/atlas-obscura-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

• Empty results for a place name — Place geocoding uses Open-Meteo; try a more specific name ("Portland, Oregon") or pass explicit lat,lng to near.
• near --category returns few results — Category is filtered client-side from place tags; raise --max-scan-pages or --radius to widen the scan.
• Stale cached place — Pass --refresh on show/near to bypass the local cache TTL and re-fetch from atlasobscura.com.
• Rate-limited or 403 from atlasobscura.com — The CLI keeps a low request rate by default; slow down with --limit and rely on the local cache for repeat queries.

Sources & Inspiration

This CLI was built by studying these projects and resources:

• atlas-obscura-api — TypeScript (9 stars)
• node-atlas-obscura — JavaScript
• travel-hacking-toolkit (atlas-obscura skill) — JavaScript
• obscura-scraper — JavaScript

Generated by CLI Printing Press