Back to ChatToMap

CLI Tool

Process your chat exports locally with full control over the pipeline. The CLI is open source and free to use.

Installation

You can run the CLI directly with npx (no installation required), or install it globally:

npx chat-to-map scan "WhatsApp Chat.zip"

Run directly without installing

npm install -g chat-to-map

Or install globally for repeated use

Quick Start

The CLI has three main commands for different use cases:

1. Free Scan (No API Key Required)

Find activity candidates using pattern matching and heuristics. This is completely free and doesn't require any API keys:

chat-to-map scan "WhatsApp Chat.zip"

2. AI Preview (~$0.01)

Classify your top candidates using AI. Requires an API key for Anthropic, Google AI, OpenAI, or OpenRouter:

chat-to-map preview "WhatsApp Chat.zip"

3. Full Analysis

Run the complete pipeline: parse → extract candidates → classify → geocode → fetch images → export. Produces CSV, Excel, JSON, PDF, and an interactive HTML map:

chat-to-map analyze "WhatsApp Chat.zip"

API Keys

The preview and analyze commands require API keys for AI classification and geocoding. Set them as environment variables:

# Required for classification (choose one)
export OPENROUTER_API_KEY=sk-or-...    # Recommended (cheapest)
export ANTHROPIC_API_KEY=sk-ant-...    # Or use Anthropic directly

# Required for geocoding
export GOOGLE_MAPS_API_KEY=AIza...

# Optional for semantic search
export OPENAI_API_KEY=sk-...

By default, the CLI uses Gemini 2.5 Flash via OpenRouter for classification, which is the most cost-effective option. You can change the model with the CLASSIFIER_MODEL environment variable.

Supported Formats

The CLI can process exports from:

Privacy

The CLI has zero telemetry. Your chat data stays on your machine. The only network requests are to APIs you explicitly configure (AI providers for classification, Google Maps for geocoding).

Next Steps