Weaves from the CLI

Create, inspect, and apply repeatable patch recipes from the terminal.

What a weave is explains the format. The weave reference lists metadata flags and schema behavior. For browser controls, use Share multiple ROM patches as one weave.

Create a weave from local files

The checks are computed from the real bytes:

rom-weaver weave create \
  --input original.sfc \
  --patch translation.bps \
  --patch fixes.ips \
  --output rom-weaver-weave.json

To distribute the recipe and patches together, add an archive output and exclude the ROM:

rom-weaver weave create -i original.sfc --patch translation.bps \
  --output rom-weaver-weave.json --weave release.zip --no-weave-rom

This records the expected ROM's checksums without including its bytes. For optional patches or release metadata, each --patch-* option describes the preceding --patch.

Include cheats in the weave

Add --cheat to record the selection beside the patches, so another machine rebuilds the same cheated ROM:

rom-weaver weave create \
  --input original.nes \
  --patch fixes.ips \
  --cheat "Infinite lives" \
  --cheat "Start with 9 keys" \
  --output rom-weaver-weave.json

Applying the weave bakes those cheats into the output:

rom-weaver patch apply -i original.nes --weave rom-weaver-weave.json -o patched.nes

To run the same weave without its cheats, add --without-cheats.

Each entry is looked up in the cheat database, so install it first with rom-weaver setup. An entry still applies without the database, from the code the weave recorded. Mark an entry "optional": true when the apply should skip it instead of failing.

Author a spec instead of flags

Write a spec with local paths and optional checksums. Add $schema for editor validation. Then use weave create --from to hash its files:

{
  "$schema": "https://raw.githubusercontent.com/rom-weaver/rom-weaver/main/docs/rom-weaver-weave-v2.schema.json",
  "version": 2,
  "patchBasis": "auto",
  "rom": { "path": "original.sfc" },
  "patches": [
    { "path": "translation.bps", "name": "English translation" },
    { "path": "fixes.ips", "optional": true }
  ],
  "output": { "name": "translated.sfc" }
}

rom-weaver weave create --from spec.json --output rom-weaver-weave.json

--from - reads the spec from stdin, in which case paths resolve against the current directory; otherwise they resolve against the spec file. Any flag you also pass overrides what the spec says, and a $schema already in the spec is kept. A ROM entry may use a local path or a url. A checks-only ROM entry is rejected. Patch entries need local paths unless explicit --patch flags replace the spec's patch list.

Parse and run a weave

Inspect the recipe, then apply it with your matching ROM:

rom-weaver weave parse --input release.zip
rom-weaver patch apply -i original.sfc --weave release.zip -o translated.sfc

Add --output extracted to weave parse to extract packaged files. Use --with NAME and --without NAME on apply to change the selected optional patches; each matches a patch name or file name and fails if it matches nothing. Test each combination you publish from the documented Original.