watchwise-cli

A CLI tool that generates personalized movie and TV show recommendations based on your IMDB ratings. It analyzes your taste profile and uses TMDB, Trakt, and OMDb APIs to find titles you'll love — plus a bonus "horizon expander" pick to broaden your horizons.

Features

• Import your IMDB rating history from a CSV export
• Build a taste profile (genre weights, director preferences, decade trends)
• 5 personalized recommendations + 1 bonus pick from unexplored genres
• Recommendation history — previously suggested titles are automatically excluded
• Randomized results — different recommendations every run
• IMDB links for every recommendation
• Genre diversity enforcement (no 5 identical-genre picks)
• Interactive API key setup on first run
• Single binary, no runtime dependencies

Installation

macOS (Homebrew)

brew install rursache/tap/watchwise-cli

Windows / Linux / macOS (Go)

go install github.com/rursache/watchwise-cli@latest

Build from Source

git clone https://github.com/rursache/watchwise-cli.git
cd watchwise-cli
go build -o watchwise-cli .

Configuration

All configuration is stored in ~/.watchwise/. On first run, the CLI will ask for your API keys and save them to ~/.watchwise/auth.json:

{
  "tmdb": { "api_key": "your-tmdb-key" },
  "trakt": { "client_id": "your-trakt-client-id" },
  "omdb": { "api_key": "your-omdb-key" }
}

Field	Required	Description
tmdb.api_key	Yes	TMDB API key — get one free at themoviedb.org
trakt.client_id	No	Trakt Client ID — enhances recommendations with community data. Create an app at trakt.tv
omdb.api_key	No	OMDb API key — adds Rotten Tomatoes & Metacritic scores. Get one free at omdbapi.com

Your taste profile is saved to ~/.watchwise/profile.json and reused on subsequent runs.

Previously recommended titles are tracked in ~/.watchwise/history.json and automatically excluded from future runs. To reset your history and allow all titles to be recommended again:

rm ~/.watchwise/history.json

Usage

watchwise

First Run

1. Enter your API keys (or create auth.json manually)
2. Export your IMDB ratings:
   • Go to imdb.com/list/ratings
   • Click the three-dot menu (⋮) and select "Export"
   • Provide the downloaded CSV path when prompted
3. Pick Movies or TV Shows
4. Get your recommendations

Subsequent Runs

watchwise    # uses your saved profile, just pick movies or TV

Refreshing Your Profile

If you've rated new titles on IMDB, export a fresh CSV and delete the old profile:

rm ~/.watchwise/profile.json
watchwise

Examples

# Quick movie recommendations (pipe input)
echo '1' | watchwise

# Quick TV show recommendations
echo '2' | watchwise

How It Works

1. Parses your IMDB CSV export (ratings, genres, directors, decades)
2. Builds a weighted taste profile from your rating patterns
3. Queries TMDB and Trakt with randomized pages for variety
4. Filters out everything you've already watched
5. Filters out previously recommended titles (from ~/.watchwise/history.json)
6. Scores candidates: genre match (50%), rating (25%), popularity (15%), recency (10%)
7. Applies genre diversity and adds a "horizon expander" from unexplored genres
8. Enriches results with Rotten Tomatoes & Metacritic scores (if OMDb configured)
9. Saves recommendations to history and fetches IMDB links for each

AI Skills

This project provides a "skill" for agentic AI tools, allowing AI assistants to generate personalized recommendations on your behalf:

• GitHub: skill folder

License

MIT License - see LICENSE for details