MiNERVA Archivist

English · Español

A command-line ROM librarian: it picks one game per title (1G1R), downloads only what you're missing, and keeps the folder tidy — without you babysitting it.

---

What it is

You have DAT files and a ROM folder. MiNERVA Archivist reads the DATs, works out which single version of each game you actually want, checks what's already on disk, fetches the rest, and lays everything out.

It carries its own 1G1R engine — a port of Retool's selection logic — so there's no second tool to run first. Clonelists, metadata, RetroAchievements and MIA data are pulled straight from retool-clonelists-metadata and cached locally.

What it does

• Reads any DAT you throw at it. No-Intro, Redump and MAME-Redump CHD sets are detected from the file itself — no type flags.
• Picks one game per title. Production status → language → region → achievements → clonelist priority → revision. An enhanced re-release stands in for the edition it replaces; a multi-game pack yields to the games in it unless you say otherwise.
• Cuts what you don't want. One --exclude list covers prototypes, betas, trial discs, bonus discs, pirates, MIA dumps, applications, BIOS, manuals, coverdiscs and video — recognised by category or by name.
• Keeps what you do. Naming a language or a region gives you that set; a wishlist and an achievements filter each name their own, and say whether they add to each other or narrow each other.
• Downloads only the gaps. Matches missing games against the platform-wide torrent and hands just those files to aria2c.
• Tidies up afterwards. Four ES-DE-compatible layouts, .m3u playlists for multi-disc games, and orphan cleanup that moves files to .trash instead of deleting them.

Everything that touches your files is a dry run by default — add --apply when you're happy with the plan.

Install

Dart SDK ≥ 3.12.

dart pub get

# run from source
dart run bin/minerva_archivist.dart <command> [options]

# or compile a standalone binary (faster startup)
dart compile exe bin/minerva_archivist.dart -o minerva_archivist

Downloading needs aria2c on PATH or passed via --aria2 <path>. Everything else works offline once synced.

Quick start

# 1. mirror the metadata locally (re-run anytime; only changed files are fetched)
minerva_archivist sync

# 2. see what the selection looks like — nothing is written
minerva_archivist filter -d <dat-or-folder>

# 3. preview the whole pipeline against your library
minerva_archivist run -d <dat-or-folder> -r <rom-root>

# 4. do it for real
minerva_archivist run -d <dat-or-folder> -r <rom-root> --apply

A typical everyday invocation — Spanish first, English as fallback, no demos or BIOS, downloading whatever's missing:

minerva_archivist run -d <dat-or-folder> -r <rom-root> \
  --lang Es,En,Ja \
  --exclude mia,preproduction,demos,pirate,bonus-discs,applications,bios,manuals,video \
  --with-download --extract --apply

Each stage reports what it dropped and why:

[select] 404 in DAT -> 309 wanted  (status -89, language -6)
[audit] 0/309 on disk, 309 missing, 0 unknown
[download] 309 missing -> 303 in torrent, 6 not distributed, 102.5 MB

Commands

Command	What it does
sync	Mirror clonelists / metadata / RetroAchievements / MIA locally
filter	Show the 1G1R selection — offline, read-only
audit	Compare the selection against what's on disk
download	Fetch missing games from the platform torrent
organize	Lay files out in one of four ES-DE layouts
m3u	Write playlists for multi-disc games
prune	Move anything unselected to .trash
run	All of the above, in order

Every flag, every combination, and the wishlist format live in GUIDE.md (español).

Contributing

Architecture, layout conventions and how to run the tests are in CONTRIBUTING.md.

Credits & license

The selection engine follows Retool by unexpectedpanda, and consumes its clonelists and metadata. DAT data comes from the No-Intro and Redump preservation projects. Thanks to all of them.

Licensed under the GNU General Public License v3.0 — see LICENSE.

MiNERVA Archivist  Copyright (C) 2026  Zeedif
This program comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions.