Automatically sync your Letterboxd lists to Radarr for seamless movie management.

Lettarrboxd is an application that monitors your Letterboxd lists (watchlists, regular lists, watched movies, filmographies, collections, etc.) and automatically pushes new movies to Radarr. It runs continuously, checking for updates at configurable intervals and only processing new additions to avoid duplicate API calls.

The application supports various types of Letterboxd URLs for the LETTERBOXD_URL environment variable:

• Watchlists: https://letterboxd.com/username/watchlist/
• Regular Lists: https://letterboxd.com/username/list/list-name/
• Watched Movies: https://letterboxd.com/username/films/
• Collections: https://letterboxd.com/films/in/collection-name/
• Popular Movies: https://letterboxd.com/films/popular/
• Actor Filmography: https://letterboxd.com/actor/actor-name/
• Director Filmography: https://letterboxd.com/director/director-name/
• Writer Filmography: https://letterboxd.com/writer/writer-name/

# User's watchlist
LETTERBOXD_URL=https://letterboxd.com/moviefan123/watchlist/

# User's custom list
LETTERBOXD_URL=https://letterboxd.com/dave/list/official-top-250-narrative-feature-films/

# User's watched movies
LETTERBOXD_URL=https://letterboxd.com/moviefan123/films/

# Movie collection
LETTERBOXD_URL=https://letterboxd.com/films/in/the-dark-knight-collection/

# Popular movies
LETTERBOXD_URL=https://letterboxd.com/films/popular/

# Another user's list
LETTERBOXD_URL=https://letterboxd.com/criterion/list/the-criterion-collection/

# Actor filmography (e.g., Tom Hanks)
LETTERBOXD_URL=https://letterboxd.com/actor/tom-hanks/

# Director filmography (e.g., Christopher Nolan)
LETTERBOXD_URL=https://letterboxd.com/director/christopher-nolan/

# Writer filmography (e.g., Aaron Sorkin)
LETTERBOXD_URL=https://letterboxd.com/writer/aaron-sorkin/

Note: All Letterboxd lists must be public for the application to access them.

docker run -d \
  --name lettarrboxd \
  -e LETTERBOXD_URL=https://letterboxd.com/your_username/watchlist/ \
  -e RADARR_API_URL=http://your-radarr:7878 \
  -e RADARR_API_KEY=your_api_key \
  -e RADARR_QUALITY_PROFILE="HD-1080p" \
  -e RADARR_TAGS="watchlist,must-watch" \
  -e DRY_RUN=false \
  ryanpage/lettarrboxd:latest

For testing purposes, you can enable dry run mode:

docker run -d \
  --name lettarrboxd-test \
  -e LETTERBOXD_URL=https://letterboxd.com/your_username/watchlist/ \
  -e RADARR_API_URL=http://your-radarr:7878 \
  -e RADARR_API_KEY=your_api_key \
  -e RADARR_QUALITY_PROFILE="HD-1080p" \
  -e DRY_RUN=true \
  ryanpage/lettarrboxd:latest

See docker-compose.yaml for complete example.

To monitor multiple Letterboxd lists simultaneously, deploy one lettarrboxd instance per list. Each instance operates independently with its own configuration, allowing you to:

• Watch different lists with different quality profiles
• Use custom tags to organize movies from different sources
• Set different check intervals for each list
• Maintain separate data directories to track each list's state

services:
  lettarrboxd-watchlist:
    image: ryanpage/lettarrboxd:latest
    container_name: lettarrboxd-watchlist
    environment:
      - LETTERBOXD_URL=https://letterboxd.com/your_username/watchlist/
      - RADARR_API_URL=http://radarr:7878
      - RADARR_API_KEY=your_api_key
      - RADARR_QUALITY_PROFILE=HD-1080p
      - RADARR_TAGS=watchlist,personal
      - CHECK_INTERVAL_MINUTES=60
    volumes:
      - ./data/watchlist:/data
    restart: unless-stopped

  lettarrboxd-criterion:
    image: ryanpage/lettarrboxd:latest
    container_name: lettarrboxd-criterion
    environment:
      - LETTERBOXD_URL=https://letterboxd.com/criterion/list/the-criterion-collection/
      - RADARR_API_URL=http://radarr:7878
      - RADARR_API_KEY=your_api_key
      - RADARR_QUALITY_PROFILE=HD-1080p
      - RADARR_TAGS=criterion,classics
      - CHECK_INTERVAL_MINUTES=120
    volumes:
      - ./data/criterion:/data
    restart: unless-stopped

  lettarrboxd-nolan:
    image: ryanpage/lettarrboxd:latest
    container_name: lettarrboxd-nolan
    environment:
      - LETTERBOXD_URL=https://letterboxd.com/director/christopher-nolan/
      - RADARR_API_URL=http://radarr:7878
      - RADARR_API_KEY=your_api_key
      - RADARR_QUALITY_PROFILE=Ultra HD
      - RADARR_TAGS=nolan,director-filmography
      - CHECK_INTERVAL_MINUTES=1440  # Check once per day
    volumes:
      - ./data/nolan:/data
    restart: unless-stopped

# Watch your personal watchlist
docker run -d \
  --name lettarrboxd-watchlist \
  -e LETTERBOXD_URL=https://letterboxd.com/your_username/watchlist/ \
  -e RADARR_API_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your_api_key \
  -e RADARR_QUALITY_PROFILE="HD-1080p" \
  -e RADARR_TAGS="watchlist,personal" \
  -e CHECK_INTERVAL_MINUTES=60 \
  -v ./data/watchlist:/data \
  ryanpage/lettarrboxd:latest

# Watch the Criterion Collection
docker run -d \
  --name lettarrboxd-criterion \
  -e LETTERBOXD_URL=https://letterboxd.com/criterion/list/the-criterion-collection/ \
  -e RADARR_API_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your_api_key \
  -e RADARR_QUALITY_PROFILE="HD-1080p" \
  -e RADARR_TAGS="criterion,classics" \
  -e CHECK_INTERVAL_MINUTES=120 \
  -v ./data/criterion:/data \
  ryanpage/lettarrboxd:latest

# Watch Christopher Nolan's filmography
docker run -d \
  --name lettarrboxd-nolan \
  -e LETTERBOXD_URL=https://letterboxd.com/director/christopher-nolan/ \
  -e RADARR_API_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your_api_key \
  -e RADARR_QUALITY_PROFILE="Ultra HD" \
  -e RADARR_TAGS="nolan,director-filmography" \
  -e CHECK_INTERVAL_MINUTES=1440 \
  -v ./data/nolan:/data \
  ryanpage/lettarrboxd:latest

1. Unique Container Names: Each instance must have a unique container name (e.g., lettarrboxd-watchlist, lettarrboxd-criterion)

2. Separate Data Directories: Use different volume mounts for each instance to maintain independent state tracking:

   volumes:
     - ./data/watchlist:/data    # Instance 1
     - ./data/criterion:/data    # Instance 2

3. Distinctive Tags: Use the RADARR_TAGS variable to organize movies by source:

   - RADARR_TAGS=watchlist,personal
   - RADARR_TAGS=criterion,classics
   - RADARR_TAGS=nolan,director-filmography

4. Appropriate Check Intervals: Adjust CHECK_INTERVAL_MINUTES based on how frequently each list updates:

   • Personal watchlists: 30-60 minutes
   • Curated lists: 2-24 hours
   • Static collections: 24 hours or more

5. Quality Profiles: Each instance can use different quality profiles based on content type:

   - RADARR_QUALITY_PROFILE=HD-1080p      # Standard content
   - RADARR_QUALITY_PROFILE=Ultra HD       # Premium content

• Node.js 20+
• Yarn package manager

# Clone the repository
git clone https://github.com/ryanpag3/lettarrboxd.git
cd lettarrboxd

# Install dependencies
yarn install

# Create environment file
cp .env.example .env
# Edit .env with your configuration

# Run in development mode
yarn start:dev

yarn start:dev    # Run with auto-reload
yarn tsc          # Compile TypeScript
yarn tsc --noEmit # Type check only

When NODE_ENV=development, the application:

• Only processes the first 5 movies (for faster testing)
• Uses more verbose logging
• Includes additional debug information

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Movies not being added

• Verify your Radarr API key and URL are correct
• Check that the quality profile name matches exactly (case-sensitive)
• Ensure your Letterboxd list is public

Docker container won't start

• Verify all required environment variables are set
• Check container logs: docker logs lettarrboxd

This project is licensed under the MIT License - see the LICENSE file for details.

This project is intended for use with legally sourced media only. It is designed to help users organize and manage their personal media collections. The developers of Lettarrboxd do not condone or support piracy in any form. Users are solely responsible for ensuring their use of this software complies with all applicable laws and regulations in their jurisdiction.