Metadata-Version: 2.5
Name: romledger
Version: 0.2.0
Summary: Track which retro games you have and which are missing, verified against No-Intro and Redump DATs.
Project-URL: Homepage, https://github.com/kjiwa/romledger
Project-URL: Documentation, https://github.com/kjiwa/romledger/tree/master/docs
Project-URL: Issues, https://github.com/kjiwa/romledger/issues
Project-URL: Changelog, https://github.com/kjiwa/romledger/blob/master/CHANGELOG.md
Author: Kamil Jiwa
License-Expression: MIT
License-File: LICENSE
Keywords: emulation,igir,no-intro,redump,retro-gaming,romm,roms
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.143.0
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: uvicorn>=0.54.0
Description-Content-Type: text/markdown

# romledger

Track which retro games you have and which are missing, verified against No-Intro and Redump DATs.
It runs on one computer: point it at a folder of ROMs and it reports, per platform, what is there
and what is not.

## Status

Works today:

- Validate a config file (`romledger config`)
- Download No-Intro and Redump DATs (`romledger dats update`)
- Match your library and inboxes to the DATs (`romledger scan`)
- Show progress per platform (`romledger status`)
- List missing games, with Vimm's Lair search links (`romledger missing nes --links`)
- Import from the inboxes into a per-platform folder layout (`romledger import`)
- Browse progress, missing games and the inbox, and upload files, in a local dashboard (`romledger serve`)
- Download missing games from CoolROM and the Internet Archive (`romledger fetch`)
- Mark games as in your library or missing while you browse Vimm's Lair, CoolROM and the Internet
  Archive (browser extension)
- Check that the supported sites and the igir pin still match (`romledger canary`; runs weekly in CI)

Vimm's Lair is manual; see [docs/sources.md](https://github.com/kjiwa/romledger/blob/master/docs/sources.md).

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/overview-desktop-dark.png">
  <img alt="The romledger overview page: one card per platform with a progress bar and counts of games had, in the inbox, missing and unmatched." src="https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/overview-desktop-light.png">
</picture>

![A terminal running romledger status, which lists wanted, have, inbox, missing and unmatched counts per platform, then romledger missing snes, which lists missing games.](https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/demo.gif)

## How it fits

- [igir](https://igir.io) matches files to DATs and moves them into place.
- romledger decides what you have and what is missing.
- [RomM](https://romm.app) is optional. The library layout is RomM's folder naming
  (`roms/<platform>/`), and romledger works the same without RomM.

## Install

Requires Python 3.11+ and Node.js 22.22+ (romledger runs [igir](https://igir.io) through `npx`).

```sh
uv tool install romledger
```

or, with [pipx](https://pipx.pypa.io):

```sh
pipx install romledger
```

## Configure

Create `~/.config/romledger/config.toml`:

```toml
[library]
roms = "~/roms/library"
inboxes = ["~/roms/inbox"]

[platforms.nes]
```

Both directories must exist. Platform names are the folder names RomM uses, such as `nes` and
`snes`. An unknown name makes `romledger config` print the known ones. `dat` is filled in for
known platforms.

Check it, then fetch DATs and scan:

```sh
romledger config
romledger dats update
romledger scan
romledger status
romledger serve --open
```

See [docs/setup.md](https://github.com/kjiwa/romledger/blob/master/docs/setup.md) for all options,
[docs/deploy.md](https://github.com/kjiwa/romledger/blob/master/docs/deploy.md) to run it as a container,
[docs/extension.md](https://github.com/kjiwa/romledger/blob/master/docs/extension.md) for the browser extension,
[docs/playing.md](https://github.com/kjiwa/romledger/blob/master/docs/playing.md) to play what you collect,
[docs/sources.md](https://github.com/kjiwa/romledger/blob/master/docs/sources.md) for download sources and
[docs/troubleshooting.md](https://github.com/kjiwa/romledger/blob/master/docs/troubleshooting.md) for error messages.

To work on romledger, see [CONTRIBUTING.md](https://github.com/kjiwa/romledger/blob/master/CONTRIBUTING.md).
