Commands¶

Global flags¶

• --config <path>: add a highest-precedence config file layer.
• --dry-run: validate and print planned actions without writing changes.

Use --dry-run first when targeting real libraries.

sync¶

Runs the default curation pipeline:

1. Retail sync with Igir hardlinks.
2. Hacks build with rompatcherjs.
3. Folder organization per game (<game>/<retail-file> and <game>/hack/<hack-file>).

Use --no-hacks to run retail sync only.

With global --dry-run, this command validates selection/config and prints the exact Igir command without executing it.

Example: retro-collection-tool --dry-run sync --systems nes,snes,genesis,sms

hacks¶

Applies curated patches from roms/Hacks/<system>/<hack-name>/ and writes ROMM-compatible outputs.

Safety flag: --no-move-retail keeps retail ROM files in place and only writes hack outputs.

With global --dry-run, this command prints the planned sequential patch chain without writing files.

Patching is performed with rompatcherjs (npx --yes rom-patcher) and applies all patch files in filename order (.ips, .bps, .ups, .xdelta, and other supported formats).

Hacks are now organized under the matched game directory when possible: roms/Library/roms/<system>/<game>/hack/<hack-name>.<ext>

Game matching uses the base ROM name and normalizes region groups (for example (USA, Europe)), so translations/hacks can align with retail game folders.

Matching retail ROM files in the system root are moved into the matched <game>/ folder. Source files from roms/Hacks are used only as patching inputs.

clean¶

Removes generated output directories for selected systems.

Flags:

• --systems <csv> or --all-systems
• --include-bios to include BIOS targets in clean operations

Examples: retro-collection-tool clean --systems genesis

retro-collection-tool --dry-run clean --all-systems --include-bios

bios¶

Imports BIOS files into ROMM Structure A targets: roms/Library/bios/<platform>/...

The BIOS workflow is feature-gated by features.enable_bios and uses catalog matching for known BIOS files.

• Matching always uses filename from the catalog.
• If a catalog source includes one or more signatures (md5, sha1, sha256, crc32), every provided signature must match.
• If a catalog source omits MD5, filename-only matching is used.
• Unknown files are skipped and reported.
• Source roots can include raw files and zip packs.

Flags:

• --systems <csv> or --all-systems
• --strict to fail when required BIOS entries are missing

Examples:

retro-collection-tool bios --systems gba,gbc

retro-collection-tool --dry-run bios --all-systems --strict

export¶

Copies selected systems to another destination (for SD cards).

Required flag:

• --destination <path>

Example: retro-collection-tool export --systems nes --destination /run/media/user/SDCARD/roms

cache¶

• cache path: print active cache path
• cache clean: remove cache files

bootstrap¶

Creates expected directory structure for configured systems.

systems¶

Prints enabled systems.

arcade¶

Arcade workflow is feature-gated by features.enable_arcade and now supports:

• arcade dats update: download/update MAME 2003 Plus and FBNeo DAT files into cache.
• arcade dats verify: ensure cached DAT files exist and are non-empty.
• arcade verify: run Igir in dry-run mode against arcade DAT + vault inputs.
• arcade sync: run Igir with hardlink output into ROMM library targets.

Arcade processing now delegates compatibility/filtering logic to Igir and DAT semantics.

Examples:

retro-collection-tool arcade dats update

retro-collection-tool arcade dats verify

retro-collection-tool arcade verify

retro-collection-tool --dry-run arcade sync

Stub Commands¶

• redump is currently a placeholder command.