komga-readlists — Setup & Usage

A single stdlib-only Python script (update-readlists.py). No install, no dependencies beyond git.

Requirements

• Python 3 and git
• A running Komga instance and an API key (Komga → Me → API Keys)
• Network access to Komga and to GitHub (to pull the CBL collection)

Configuration (environment variables)

Variable	Default	Meaning
KOMGA_API_TOKEN	— (required)	Komga API key, sent as X-API-Key
KOMGA_URL	http://192.168.1.209:25600	Base URL of your Komga instance
CBL_REPO	~/.cache/CBL-ReadingLists	Local clone path; git pulled each run
CBL_REPO_URL	https://github.com/DieselTech/CBL-ReadingLists.git	Source of the .cbl reading orders
READLIST_DRY_RUN	1	1 = report only; 0 = create/refresh lists
COMPLETE_ONLY	1	1 = only import 100%-owned orders; 0 = also import ≥NEAR_PCT
NEAR_PCT	75	Threshold for the "near complete" report (and for partial import if COMPLETE_ONLY=0)
WORKERS	6	Parallel match workers
COVERAGE_OUT	—	Optional path to write a coverage markdown report

Usage

1. Dry run (matches everything, changes nothing):

KOMGA_API_TOKEN=yourtoken python3 update-readlists.py

Reports how many reading orders are 100% complete (importable), how many are near-complete, and — per list — whether it would be created or refreshed.

2. Live:

KOMGA_API_TOKEN=yourtoken READLIST_DRY_RUN=0 COVERAGE_OUT=coverage.md python3 update-readlists.py

Automated weekly runs (cron)

Use a small wrapper that holds the env, then a weekly cron entry:

# run-readlists.sh   (chmod 700 — it holds your token)
#!/bin/bash
export KOMGA_URL=http://komga:25600
export KOMGA_API_TOKEN=yourtoken
export CBL_REPO=/path/CBL-ReadingLists
export READLIST_DRY_RUN=0
export COVERAGE_OUT=/path/readlist-coverage.md
exec python3 /path/update-readlists.py

# Mondays 05:00
0 5 * * 1 /path/run-readlists.sh >> /path/cron.log 2>&1

Notes

• Complete-only by default: a read list is only materialised when you own every issue in it, so every list reads start-to-finish. As your library fills in, the next run picks up newly-complete orders automatically.
• Refresh is in-place (PATCH), so re-runs never duplicate lists and your curated lists are never deleted mid-update.
• The coverage report's "near complete" section shows what you're closest to finishing.