Simkl → Overseerr Integration

Enterprise-grade automation for syncing your Simkl "Plan to Watch" lists to Overseerr, automatically triggering downloads via your *ARR stack.

Features

✅ Smart Filtering: Only syncs items marked as "Plan to Watch" - not completed or currently watching ✅ Dual Media Support: Movies and TV shows ✅ Enterprise Architecture: Built on ListSync framework ✅ Production Ready: Comprehensive error handling and logging ✅ Flexible Execution: CLI with dry-run mode, selective sync options

Quick Start

1. Initial Setup

# Clone and setup
cd /home/brian/list-sync
python3 setup_simkl.py

The setup will guide you through:

• Creating a Simkl developer app
• Getting API credentials and access token
• Configuring Overseerr connection
• Testing all connections

2. Basic Usage

# Sync everything (movies + shows)
python3 simkl_sync.py

# Dry run (see what would be synced)
python3 simkl_sync.py --dry-run

# Sync only movies
python3 simkl_sync.py --movies

# Sync only TV shows
python3 simkl_sync.py --shows

3. Automated Scheduling

Add to crontab for automatic daily sync:

# Daily sync at 2 AM
0 2 * * * cd /home/brian/list-sync && python3 simkl_sync.py >/dev/null 2>&1

How It Works

1. Connects to Simkl API using your credentials
2. Fetches watchlists filtering for status = "plantowatch"
3. Submits requests to Overseerr for each item
4. Overseerr triggers Radarr/Sonarr to download content
5. Content appears in your Plex library automatically

Configuration

All settings are stored in .env.simkl:

# Simkl API Configuration
SIMKL_CLIENT_ID=your_client_id
SIMKL_CLIENT_SECRET=your_client_secret
SIMKL_ACCESS_TOKEN=your_access_token

# Overseerr Configuration
OVERSEERR_URL=http://your_overseerr_host:5055
OVERSEERR_API_KEY=your_api_key
OVERSEERR_REQUESTER_USER_ID=1

# Sync Configuration
SYNC_INTERVAL_HOURS=24
LOG_LEVEL=INFO

Simkl Setup Instructions

1. Go to https://simkl.com/settings/developer
2. Create new app:
   • Name: ListSync Integration
   • Description: Automated sync for Simkl watchlists
   • Redirect URI: urn:ietf:wg:oauth:2.0:oob
3. Copy Client ID and Secret to setup script

Architecture

Simkl API → ListSync Provider → Overseerr API → Radarr/Sonarr → Downloads

• Provider: /list_sync/providers/simkl.py - Core integration logic
• Sync Script: simkl_sync.py - Production sync execution
• Setup Script: setup_simkl.py - Configuration and authentication

Filtering Logic

Movies: Only syncs items with status = "plantowatch" TV Shows: Only syncs items with status = "plantowatch"

Excluded:

• completed - Already watched
• watching - Currently watching
• dropped - Abandoned shows
• paused - Paused shows

Troubleshooting

No items found

# Check your Simkl lists
python3 simkl_sync.py --dry-run

Items must be marked as "Plan to Watch" in Simkl, not just added to watchlist.

Authentication errors

# Re-run setup to refresh tokens
python3 setup_simkl.py

Connection issues

• Verify Overseerr is accessible
• Check API keys in .env.simkl
• Ensure *ARR services are running

Files

• simkl_sync.py - Main sync script
• setup_simkl.py - Configuration setup
• .env.simkl - Configuration file
• list_sync/providers/simkl.py - Provider implementation
• archive/ - Development files (archived)

Support

The integration follows ListSync patterns and can be extended or customized as needed. All logging goes to console for easy monitoring and debugging.

---

Enterprise-grade Simkl integration - ready for production deployment.