Commands Reference

Complete reference for all CLI commands. Each command can be run individually or as part of the full analyze pipeline.

Global Options

These options work with all commands:

Flag	Description
-q, --quiet	Minimal output
-v, --verbose	Verbose output
--debug	Print debug info
--no-cache	Skip cache and regenerate all results
--cache-dir <dir>	Custom cache directory

analyze

Run the complete pipeline and generate all exports

Varies by chat size ($0.01-$1.00+)

chat-to-map analyze <input>

Pipeline

parse → filter → scrape-urls → classify → geocode → fetch-images → export

Options

-c, --home-country <name>	Your home country (auto-detected if not set)
--timezone <tz>	Your timezone (auto-detected if not set)
-o, --output-dir <dir>	Output directory (default: ./chat-to-map/output)
-f, --format <formats>	Output formats: csv,excel,json,map,pdf
--min-confidence <num>	Minimum confidence threshold (default: 0.5)
--skip-geocoding	Skip geocoding step
-m, --max-messages <num>	Max messages to process (for testing)
--dry-run	Show stats without making API calls

Required API Keys

• OPENROUTER_API_KEY or ANTHROPIC_API_KEY
• GOOGLE_MAPS_API_KEY

scan

Quick heuristic scan to find activity candidates (free, no API key)

Free

chat-to-map scan <input>

Pipeline

parse → heuristic extraction

Options

-n, --max-results <num>	Max results to return (default: 10)
-m, --max-messages <num>	Max messages to process

preview

AI-powered preview of your top candidates

~$0.01

chat-to-map preview <input>

Pipeline

parse → heuristic extraction → AI classification (top candidates only)

Options

-c, --home-country <name>	Your home country (auto-detected if not set)
--timezone <tz>	Your timezone (auto-detected if not set)
-n, --max-results <num>	Max results to return (default: 10)
-m, --max-messages <num>	Max messages to process
--dry-run	Show stats without making API calls

Required API Keys

• OPENROUTER_API_KEY or ANTHROPIC_API_KEY

parse

Parse and validate a chat export file

Free

chat-to-map parse <input>

Pipeline

Parse only

Options

--json [file]	Output as JSON (to file or stdout)
-m, --max-messages <num>	Max messages to process

embed

Generate embeddings for semantic search

~$0.001 per 1,000 messages

chat-to-map embed <input>

Pipeline

parse → embed all messages

Options

-m, --max-messages <num>	Max messages to process
--dry-run	Show cost estimate without making API calls

Required API Keys

• OPENAI_API_KEY

filter

Extract candidates using heuristics and/or embeddings

~$0.001 per 1,000 messages (embeddings only)

chat-to-map filter <input>

Pipeline

parse → heuristics + embeddings → merge candidates

Options

--method <method>	Extraction method: heuristics, embeddings, or both (default: both)
--json [file]	Output as JSON (to file or stdout)
--min-confidence <num>	Minimum confidence threshold (default: 0.5)
-m, --max-messages <num>	Max messages to process
-a, --all	Show all candidates (default: top 10)
--dry-run	Show cost estimate without making API calls

Required API Keys

• OPENAI_API_KEY (for embeddings)

scrape-urls

Scrape metadata from URLs found in candidates

Free

chat-to-map scrape-urls <input>

Pipeline

Uses cached candidates → scrape URLs

Options

--json [file]	Output as JSON (to file or stdout)
--concurrency <num>	Max concurrent scrapes (default: 5)
--timeout <ms>	Timeout per URL in ms (default: 4000)
-m, --max-messages <num>	Max messages to process
-a, --all	Show all enriched URLs (default: first 10)
--dry-run	Show URL count without scraping

classify

Classify candidates into activities using AI

~$0.05-$0.50 depending on chat size

chat-to-map classify <input>

Pipeline

parse → filter → scrape-urls → AI classification

Options

-c, --home-country <name>	Your home country (auto-detected if not set)
--timezone <tz>	Your timezone (auto-detected if not set)
--json [file]	Output as JSON (to file or stdout)
-n, --max-results <num>	Max results to display (default: 10)
-m, --max-messages <num>	Max messages to process
-a, --all	Show all activities (default: top 10)
--dry-run	Show stats without making API calls

Required API Keys

• OPENROUTER_API_KEY or ANTHROPIC_API_KEY

geocode

Geocode classified activities to coordinates

~$0.005 per location

chat-to-map geocode <input>

Pipeline

Uses cached classifications → Google Maps geocoding

Options

-c, --home-country <name>	Your home country (auto-detected if not set)
--timezone <tz>	Your timezone (auto-detected if not set)
--json [file]	Output as JSON (to file or stdout)
-n, --max-results <num>	Max results to display (default: 10)
-m, --max-messages <num>	Max messages to process
-a, --all	Show all geocoded activities (default: top 10)
--dry-run	Show stats without making API calls

Required API Keys

• GOOGLE_MAPS_API_KEY

fetch-image-urls

Fetch images for geocoded activities

Varies (can use free CDN defaults)

chat-to-map fetch-image-urls <input>

Pipeline

Uses cached geocoded activities → fetch images

Options

--json [file]	Output as JSON (to file or stdout)
--no-image-cdn	Skip CDN default images (fetch all from APIs)
--skip-pixabay	Skip Pixabay image search
--skip-wikipedia	Skip Wikipedia image lookup
--skip-google-places	Skip Google Places photos
-n, --max-results <num>	Max results to display (default: 10)
-a, --all	Show all activities with images

Required API Keys

• GOOGLE_MAPS_API_KEY (optional)
• PIXABAY_API_KEY (optional)

list

Show previously processed chats

Free

chat-to-map list

Pipeline

Reads from cache directory

Pipeline Flow

Commands build on each other. Each command checks for cached results from earlier stages and reuses them if available:

parse → scan (heuristics) → embed → filter (merge) → scrape-urls → classify → geocode → fetch-images → export

For example, running geocode will automatically run parse, filter, scrape-urls, and classify first if they haven't been cached.