rom-utils

Utilities for managing RetroDECK game libraries between a Linux desktop and a Steam Deck, plus helpers for ROM conversion and package extraction.

Motivation

This repository centralizes practical scripts used for:

• Syncing ROM metadata, saves, states, and cheats between desktop and Steam Deck.
• Converting/extracting game assets into formats that are easier to run and store.
• Preparing PS Vita package content for installation workflows.

Supported Environment

Tested so far on:

• Linux desktop (Debian-based distributions)
• Steam Deck with RetroDECK

It may still work on other Linux distributions or platforms, but this is not currently verified.

Environment Assumptions

These scripts assume the following default RetroDECK locations:

• Linux desktop: /retro/retrodeck
• Steam Deck SD card install: /run/media/deck/SD_STEAM_DECK/retrodeck

If your setup differs, update the path variables in the sync/search scripts before use.

SSH Authentication

The sync scripts connect to deck@steamdeck using rsync over SSH. Before using any sync script the following prerequisites must be met:

1. SSH must be enabled on the Steam Deck. Go to Settings → System → Enable SSH in Gaming Mode, or start the service manually in Desktop Mode:

   sudo systemctl enable --now sshd

2. An SSH key-pair must already exist on your desktop. If not, generate one:

   ssh-keygen -t ed25519

3. The public key must be exchanged with the Steam Deck so the desktop can connect without a password:

   ssh-copy-id deck@steamdeck

4. Verify the connection is working before running any sync script:

   ssh -T deck@steamdeck

Dependencies

Install these tools before running the scripts:

• xdvdfs
• chdman via the apt install mame-tools package on Debian-based systems.
• docker

We also expect common GNU/CLI tools to be available, such as: bash, rsync, grep, sed, unzip, base64, and zlib-flate.

Setup

Clone this repository into a directory of your choice, for example under your home directory:

SSH:

git clone git@github.com:yveskaufmann/rom-utils.git "$HOME/rom-utils"

HTTPS:

git clone https://github.com/yveskaufmann/rom-utils.git "$HOME/rom-utils"

Add the scripts to your PATH e.g by adding the following lines to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/rom-utils:$PATH"
export PATH="$HOME/rom-utils/pkg2zip-image:$PATH"

Grant execute permissions (once):

chmod +x "$HOME/rom-utils"/*.sh
chmod +x "$HOME/rom-utils"/pkg2zip-image/build.sh

Available Scripts

Script	Purpose	Documentation
convert-to-chd-roms.sh	Convert extracted ISO/CUE content from zip files into .chd or .xiso.iso.	docs/scripts/convert-to-chd-roms.md
multi-disks.sh	Group multi-disc files and generate .m3u playlist files.	docs/scripts/multi-disks.md
prepare-vita-pkgs.sh	Extract PS Vita package content from zip archives via pkg2zip.	docs/scripts/prepare-vita-pkgs.md
rom-find-games.sh	Search ES-DE gamelist XML entries for game names.	docs/scripts/rom-find-games.md
sync-cheats.sh	Push/pull RetroDECK cheats folder between desktop and Steam Deck.	docs/scripts/sync-cheats.md
sync-roms.sh	Push/pull ES-DE media and collections (with filters/dry-run options).	docs/scripts/sync-roms.md
sync-saves.sh	Push/pull RetroDECK saves and states.	docs/scripts/sync-saves.md
pkg2zip-image/build.sh	Build a Docker image that provides the pkg2zip tool.	docs/scripts/pkg2zip-image-build.md

Legal Use

This repository provides automation and synchronization scripts only. It does not host, distribute, or include any copyrighted game assets such as ROMs, ISOs, BIOS files, firmware, or decryption keys.

Users are solely responsible for ensuring they have the legal right to back up and sync the files they target with these scripts under applicable local laws. This project is an independent utility and is not affiliated with, authorized, or endorsed by RetroDECK, Valve, or any console manufacturer.