A terminal-first collection manager for physical media — built for video, books, and music, and written to feel less like inventory software and more like a well-kept private vault.
The Undercroft is a SQLite-backed terminal app for cataloging the things you actually own, want, and revisit: tapes on the shelf, books by the bed, records and cassettes by the stereo. It favors speed, plain files, and atmosphere over web-stack bloat.
- Unified vault for video, books, and music
- API-assisted lookup for OMDb, Open Library, and Discogs
- Manual entry for oddities, bootlegs, obscure editions, and edge cases
- Wishlist support for each collection
- Ratings, notes, and long-form personal reviews
- Global search across the full vault
- Random picker for the eternal question of what to watch, read, or play next
- CSV export
- Single-file SQLite storage you fully control
- Import path for the old VHS Vault database, with VHS automatically attached as an owned format
pip install requests rich# Default database location: ~/undercroft.db
python undercroft.py
# Custom database location
python undercroft.py --db ~/vault/media.db
python undercroft.py --db /mnt/nas/collections/undercroft.db
# Or run as a module
python -m undercroft --db ~/my_collection.db- Video: OMDb API key — available from OMDb
- Books: Open Library — no key required
- Music: Discogs personal access token
Set keys from the Settings room inside the app.
~/undercroft.db— SQLite database, unless you choose another path~/.undercroft_config.json— local API key storage
Your collection is just a database file. Backups are simple copies of that file, and restores are equally direct. That is intentional.
This project is licensed under the GNU GPL v3.0. See LICENSE.
undercroft/
├── __init__.py # Package metadata
├── __main__.py # Entry point, main menu, backup, global search
├── ui.py # Theme, display helpers, prompts, vault chrome
├── db.py # Schema, migrations, import, integrity checks
├── config.py # Local API key management
├── apis.py # OMDb, Open Library, Discogs integrations
├── ops.py # Shared CRUD / browse / export behavior
├── vhs.py # Video section (VHS / DVD / Blu-ray / LaserDisc)
├── books.py # Books section
└── music.py # Music section