Canonical: https://rom-weaver.com/docs/cli-apply # Apply patches from the CLI Apply one patch or an ordered chain in the terminal, handle headers and byte order, verify checksums, and validate patches without keeping an output ROM. New to the CLI? Start with [your first apply](). Each recipe uses only the flags its task needs; the [patching flags]() are catalogued in the reference. ## Table of contents - [Apply one or more patches](<#apply-one-or-more-patches>) - [Apply a Dreamcast DCP patch](<#apply-a-dreamcast-dcp-patch>) - [Pipe the patched ROM to another program](<#pipe-the-patched-rom-to-another-program>) - [Pick one patch out of an archive](<#pick-one-patch-out-of-an-archive>) - [Verify the ROM before and after](<#verify-the-rom-before-and-after>) - [Apply a patch made for a headerless ROM](<#apply-a-patch-made-for-a-headerless-rom>) - [Apply an N64 patch regardless of byte order](<#apply-an-n64-patch-regardless-of-byte-order>) - [Validate a patch chain](<#validate-a-patch-chain>) - [Undo a PPF patch](<#undo-a-ppf-patch>) - [Where next](<#where-next>) ## Apply one or more patches Apply one patch, or several in order, each on the result of the last: ```bash rom-weaver patch apply \ --input original.sfc \ --patch translation.bps \ --output translated.sfc rom-weaver patch apply \ --input original.sfc \ --patch base.ips \ --patch fixes.ups \ --output patched.zip ``` `patch apply` is the canonical spelling; `weave` remains accepted for compatibility. An output extension matching the selected ROM leaf writes a plain ROM, so `translated.sfc` does not need `--no-compress`. A registered container extension such as `.zip` still compresses the result. Use `--no-compress` to force raw bytes. The [output reference]() lists compression overrides and aliases. For an ordinary file apply, omit `--output` to write a sibling such as `original-patched.sfc`. Existing names are preserved by adding a numeric suffix. Weave applies keep their weave-provided output name; a weave without one still requires `--output`. Formats that carry their own checksums are verified strictly, so a wrong original ROM stops the run - see [Fix a checksum error]() when that happens. ## Apply a Dreamcast DCP patch 1. Keep the Dreamcast `.gdi` or `.cue` sheet with every referenced track at its recorded path. 2. Check that the disc matches the DCP author's required release before applying, for example with `rom-weaver checksum`. DCP apply cannot verify it for you. 3. Apply the `.dcp` alone, using the sheet as the input: ```sh rom-weaver patch apply --input game.gdi --patch hack.dcp --output patched.chd ``` For a CUE-based disc, replace `game.gdi` with the `.cue` path. DCP rebuilds the high-density data track's filesystem and selects that track automatically. DCP cannot run in a patch chain or with cheats, an explicit target, or byte-level header, checksum-repair, and N64 byte-order transforms. It also rejects the checksum guards `--expect-in`, `--expect-out`, `--patch-input-check`, and `--patch-output-check`, and fails before writing output. A weave's optional cheats are skipped with a warning; its required cheats fail the apply unless you pass `--without-cheats`. Browser Apply does not support this disc-sheet workflow. Test the resulting CHD in a compatible Dreamcast emulator. Keep the original disc and tracks until you check the result. ## Pipe the patched ROM to another program Use `--output -` and `--no-compress` to send the patched ROM to a compressor: ```bash rom-weaver patch apply \ --input original.sfc \ --patch translation.bps \ --no-compress --output - | gzip > translated.sfc.gz ``` To have rom-weaver produce the archive itself, replace `--no-compress` with `--compress-format zip` and redirect stdout to a ZIP file. The operation finishes in temporary storage before it writes stdout. See the [binary pipeline reference]() for storage requirements and restrictions. ## Pick one patch out of an archive Point `--patch` at an archive and `--patch-select` at the file inside it: ```bash rom-weaver patch apply \ --input game.chd \ --select '*.bin' \ --patch quality-of-life.7z \ --patch-select 'Game (USA)/Quality of Life.ppf' \ --no-compress \ --output patched.bin ``` `--select` chooses the payload inside the input, `--patch-select` the file inside the patch archive. Without the second flag, `--select` applies to both, and no single pattern can match a `.bin` in the input and a `.ppf` in the patch. Match on the path when the archive nests its patches in folders: `'*USA*/*.ppf'` works, a bare `'*USA*'` does not. Repeat `--patch-select` once per `--patch`, in order; each binds to the `--patch` before it: ```bash rom-weaver patch apply \ --input game.sfc \ --patch base.zip --patch-select base-v2.bps \ --patch extras.zip --patch-select widescreen.bps \ --output patched.sfc ``` ## Verify the ROM before and after When a patch page publishes the expected checksums, pin them so the run fails loudly instead of producing a broken ROM: ```bash rom-weaver patch apply \ --input original.sfc \ --patch translation.bps \ --output translated.sfc \ --expect-in crc32=ABCD1234 \ --expect-out sha1=0123456789abcdef0123456789abcdef01234567 ``` `--expect-in` stops before patching unless the input matches; `--expect-out` fails the run unless the finished ROM matches. ## Apply a patch made for a headerless ROM `--patch-header auto` uses available checksums and first-patch inference to choose between headered and headerless input. When the evidence is inconclusive, it keeps the existing form. `--output-header auto` keeps required format headers and recognized NSRT dump metadata. Override the defaults when the patch author specifies a layout. Add `--repair-checksum` only when the output needs internal checksum repair: ```bash rom-weaver patch apply \ --input game.smc \ --patch hack.ips \ --output patched.sfc \ --patch-header strip \ --output-header strip \ --repair-checksum ``` ## Apply an N64 patch regardless of byte order N64 ROMs circulate in three interleavings, and a patch only applies to the one it was made against. The default `--n64-byte-order auto` matches your ROM to the patch's source CRC32 and writes the output back in the order the input arrived in, so usually there is nothing to do. An IPS patch carries no checksum; auto then reads the shape of its changes, and says so in the report when that settles it. Set a specific patch-input order only when the author documents it: ```bash rom-weaver patch apply \ --input game.n64 \ --patch fix.bps \ --output fixed.n64 \ --n64-byte-order big-endian ``` The output keeps the input's byte order. The `.n64` extension above reflects that; `--n64-byte-order big-endian` selects the patch input, not the output format. ## Validate a patch chain `patch validate` checks the chain without keeping an output ROM. It can create temporary files while applying the patches: ```bash rom-weaver patch validate \ --input original.sfc \ --patch base.ips \ --patch fixes.ups ``` Patches default to automatic checksum inference. Pass `--default-patch-basis base` for patches made from the original ROM, or `previous` for a dependent chain. Pass `--independent` to check each patch separately and report every verdict. The command exits `1` if any patch fails. Use `--expect-in ALGO=HEX` to check the ROM itself. ## Undo a PPF patch Use the patched ROM and the exact PPF3 patch that changed it. The patch must include undo data. Create one with `rom-weaver patch create original.bin modified.bin -o change.ppf --ppf-undo`. ```sh rom-weaver tools ppf-undo -i patched.bin --patch change.ppf -o restored.bin --no-compress ``` To restore from archived ROM and patch inputs and compress the result: ```sh rom-weaver tools ppf-undo \ -i patched.zip --select game.bin \ --patch change.zip --patch-select change.ppf \ -o restored.zip ``` See [compression overrides]() for other formats and codecs. Compare the restored file with the original's known checksum before you use it. If the patch lacks undo data, restore your backup instead. The [tools reference]() lists the inputs and limits. ## Where next - A checksum mismatch is almost always a wrong starting file; see [Fix a checksum error](). - Record a finished run as a shareable recipe with [Weaves from the CLI](). - Bake cheat codes into a ROM (`--code`), write a weave alongside the patched ROM (`--emit-weave`, `--tui`), or patch straight from a `rom-weaver-weave.json`: the [patching flags]() cover every option, and `rom-weaver patch apply --help` is authoritative.