CLI reference

All commands are run via the rsmm entry point:

./rsmm <command> [options]     # Linux
rsmm <command> [options]       # Windows

Commands that take a mod id (enable, disable, lint, diff, pack, publish, test) accept the folder name under mods/ in any case, with the trailing slash tab completion adds, or as a path (mods/MyMod). A misspelled id or subcommand gets a “did you mean …?” instead of a list.

---

Core commands

rsmm apply

Install all enabled mods into the game directory. Backs up originals, applies patches, and merges [[patch]] blocks from manifest.toml.

./rsmm apply
./rsmm apply --game-dir /custom/path
./rsmm apply --verbose        # list every file installed, restored or registered

By default it prints one line per mod (+ nyx installed 359 file(s), 345 new) plus any warnings, merges and errors, with a live counter while it works on a terminal. -v / --verbose (or RSMM_VERBOSE=1) lists every file instead; restore --all follows the same rule. Warnings raised while a mod’s content is built name that mod ([warn] custom-hero-test: custom mesh does not overlap…).

Rollback: ./rsmm restore --all

rsmm list

Show installed mods and their status.

./rsmm list

rsmm doctor

Health check, and the repair path for what it finds. Run this often — it is the first thing to try when something “just doesn’t work”.

./rsmm doctor                      # report only (never writes)
./rsmm doctor --fix                # run the safe repairs, then re-check
./rsmm doctor --fix --force        # also run destructive repairs
./rsmm doctor --only loader        # one section; --only list names them all
./rsmm doctor --json               # machine-readable findings

Findings carry a stable code and, where one exists, the exact rsmm command that repairs them. --fix runs those repairs and then re-runs every check, so a repair is only reported as fixed when the check actually goes green.

Flag	Meaning
--fix	Run each finding’s automated repair (apply, install-loader, rebuild-asset-map, update-data). Repairs are ordinary rsmm commands — doctor never reimplements one.
--force	With --fix, also run repairs that roll the install back or delete installed files (restore --all).
--only CHECK	Restrict to named checks; repeatable. --only list prints them.
--json	Structured report: per-finding kind, code, detail, and whether a repair is automatic.
--game-dir	Point at a non-default install.

Plain doctor is read-only on purpose: a health check that silently rewrites a game install on every run is a footgun, so repairs are opt-in.

What it covers: game install reachable and writable, asset map freshness, game version drift, the loader (DLL bytes by hash, the disk-loaded Lua SDK under <game>/rsmm/lib, the planted pattern DB, dangerous feature flags left armed, and — on Proton — whether Steam’s launch options still carry the WINEDLLOVERRIDES the loader needs), mod manifests and asset paths, raw-file and [[patch]] conflicts, whole-file overrides a declarative block could replace, the dependency graph, applier state versus what is actually on disk, UsedRscList.ot record alignment, and recent crash dumps.

A whole-file override is a mod shipping a complete game file where a [[patch]] kind = "stat" (stat files), [[patch]] kind = "ot" (ApplicationSettings.ot via _root/) or [[content]] kind = "talent" (hero talent values) would do. The copy works, but it cannot merge with another mod and it silently reverts whatever the next game patch changes in that file. rsmm lint <id> prints the replacement block. It only offers one it has proven: the block is parsed back and run through the same code apply uses, and must rebuild the mod’s file byte for byte. Without a readable game copy it names the route but cannot write the block.

Tip

A planted winhttp.dll is only half an install. The Lua SDK and pattern DB are loaded from <game>/rsmm/, and a Steam update replaces the DLL while deleting that tree — which looks exactly like “the loader is broken”. Doctor checks all three.

rsmm run

Launch Ravenswatch from the CLI.

./rsmm run
./rsmm run --game-dir /custom/path

rsmm watch

Re-apply mods automatically whenever a file changes under mods/. Keeps running in the background.

./rsmm watch
./rsmm watch --no-lint             # apply even when a changed mod has lint errors

Each save prints which mods and files changed, then lints those mods before applying. A changed mod with lint errors is not applied: the errors are printed and the game keeps the last good apply until you fix them and save again. Without that, a manifest caught half-written would be skipped by apply, which takes the mod out of the game until the next save. Files apply writes itself (emitted content, its caches, mods/_merged/) and editor swap files don’t count as changes.

rsmm restore

Restore original game files. Reverses rsmm apply.

./rsmm restore --all               # Restore everything
./rsmm restore --mod MyMod         # Restore files for one mod

rsmm log

Read the loader log file (<game>/mods/_log.txt).

./rsmm log                         # Full dump
./rsmm log -n 80                   # Last 80 lines
./rsmm log -f                      # Follow live (Ctrl-C to stop)
./rsmm log --grep lua              # Filter (case-insensitive)
./rsmm log --clear                 # Clear the log before a fresh launch

rsmm overlay

Read the live HUD data a mod publishes. Overlays are declared by mods (an [overlay] block in manifest.toml) and filled at runtime with R.overlay.publish — the client hardcodes none of them.

./rsmm overlay                     # every installed mod that declares one
./rsmm overlay damage-meter        # that mod's board
./rsmm overlay damage-meter -w     # live, e.g. on a second monitor
./rsmm overlay damage-meter --json # machine-readable

Columns, sorting and the highlighted row come from the declaration, so the terminal view and the desktop app’s overlay window show the same thing.

---

Mod management

rsmm new <id>

Scaffold a new mod directory:

./rsmm new MyMod
# Creates: mods/MyMod/manifest.toml

./rsmm new MyMod --kind item        # also seeds a [[content]] block
./rsmm new MyMod --desc "Faster dodges" --tags balance,heroes --license MIT

The author comes from --author, else your git config user.name. Fill in --desc, --tags and --license too and the new mod passes rsmm lint with no warnings; leave them out and the scaffold says what is still missing.

--kind takes item, talent, enemy, boss, map or hero. Kinds that aren’t confirmed are scaffolded with experimental = true and enabled = false.

For --kind item the block is read out of the base you clone rather than templated — its icon, rarity and every patchable value field with its true current value, so the scaffold applies without hand-editing:

./rsmm new IronCrabHide --kind item --base Common/Armor_Per_Object \
    --name "Iron Crab Hide" --desc "Bonus armor per rare object."

Flag	Meaning
--base ID	Vanilla id to clone. Bare (Armor_Per_Object) or rarity-qualified (Common/Armor_Per_Object). Omit it at a terminal to get a searchable picker.
--name TEXT	Display name for the mod and its content.
--desc TEXT	Description shown in-game and on the store card.
--icon ID	Vanilla icon stem (rsmm items icons) or assets/<file>.png. Defaults to the base’s own icon.
--rarity R	Common, Rare, Epic, Legendary, Cursed or Powerups. Defaults to the base’s rarity.
--author NAME	Who made it. Defaults to git config user.name.
--tags a,b	Store tags, comma-separated: lower-case letters, digits and -, at most 16.
--license ID	SPDX id (MIT, CC-BY-4.0) or a licence name.

See Custom items for the full walkthrough.

rsmm pack <id>

Package a mod for distribution. Verifies no vanilla (unmodified game) bytes are included.

./rsmm pack MyMod                  # Writes dist/MyMod.zip
./rsmm pack MyMod --allow-vanilla  # Skip vanilla-byte check (personal backups only)

rsmm publish <id>

Upload a mod to the store in one command: lint, pack (with the vanilla-byte check), upload with its checksum, queue the malware scan, and wait until the version is live. A version can only be downloaded once its scan comes back clean; that gate is on the server and a token cannot skip it.

./rsmm publish login        # paste a token from rsmm.me/account (input hidden)
./rsmm publish whoami       # which account the token publishes as
./rsmm publish MyMod        # pack, upload, scan, wait until live
./rsmm publish MyMod --no-wait
./rsmm publish logout

Create the token on your account page under API tokens. It is shown once, and it can publish new versions of your own mods and nothing else. It cannot change your account, create more tokens, delete mods or moderate. Every token expires (30 days to a year), you can hold ten at a time, and you get an email whenever one is created.

The CLI reads the token from RSMM_API_TOKEN or from the file login writes (~/.config/rsmm/credentials.json, %APPDATA%\rsmm\credentials.json on Windows, owner-only permissions). There is deliberately no --token flag, because command arguments end up in shell history and the process list. It refuses to send a token anywhere but HTTPS (plain HTTP only for localhost). If a token may have leaked, revoke it on the account page. Revocation takes effect on the next request.

Failure	Meaning
the API token was rejected	Revoked, expired, or the account is not verified. Make a new one.
version … is already published	Bump [mod].version in manifest.toml.
this mod slug belongs to another account	Someone else owns that id. Rename the mod.
upload rate limit reached	Five uploads per hour per account.
the malware scan came back flagged	The version stays unavailable. Report it if you think it is a false positive.

rsmm install-loader

Copy the loader DLL (dist/winhttp.dll) into the game installation directory.

./rsmm install-loader

---

Asset editing

rsmm assets search <text> / rsmm assets show <path>

Find a cooked asset by its readable path. The install holds ~43,000 files whose names are cipher-encoded, so ls and grep cannot answer “where does the wolf enemy live” — but data/asset_map.json already carries the whole decoded ↔ encoded mapping (derived from the engine’s UsedRscList.ot), so this is a lookup, not a scan. No game install required.

./rsmm assets search wolf                  # every readable path containing "wolf"
./rsmm assets search enemies wolf          # both terms, any order (ANDed)
./rsmm assets search "Ui/*.png"            # glob when the term has * or ?
./rsmm assets search wolf --encoded -n 0   # print on-disk names too, no limit
./rsmm assets show Audio/Music.bank        # encoded name + install state

Terms are case-insensitive and accept either slash direction. show also answers for the two families that are in no manifest because the engine ciphers them by convention — Audio/*.bank and *.UsedRscCache.ot — and reports whether the installed copy is vanilla or currently overridden by a mod.

rsmm decode <file>

Structural dump of a cooked file (class table, sections, embedded strings).

./rsmm decode path/to/cooked.gen
./rsmm decode path/to/cooked.gen --raw   # Include hex payloads

rsmm uncook <file>

Extract a cooked asset to an editable source-format file. Per-class schemas are reversed-engineered incrementally (see docs/RE_NOTES.md); when the schema isn’t ready yet, --raw extracts section bytes directly so byte-level mods are unblocked.

./rsmm uncook path/to/cooked.yqz                # uncook to source format (schema-dependent)
./rsmm uncook path/to/cooked.yqz --info         # print container header + class table
./rsmm uncook path/to/cooked.yqz --raw          # dump all section payloads to <name>.raw
./rsmm uncook path/to/cooked.yqz --raw --section 3 -o sec3.bin

rsmm cook --from <reference> <source>

Pack a source asset into a cooked Ravenswatch file. Until per-class encoders land, --from <reference.yqz> is required: the reference supplies the container header + class table + version. --raw substitutes the input bytes verbatim as section payload, giving a byte-level edit path today.

# Round-trip section 3 byte-identically:
./rsmm uncook --raw --section 3 ref.yqz -o sec3.bin
./rsmm cook   --raw --from ref.yqz --section 3 sec3.bin -o out.yqz

# Once schemas land, cook from source format:
./rsmm cook --from ref.yqz model.gltf -o out.yqz

rsmm editor

One local page with four editors, each on its own tab. Each one reads your own install when the page asks for something, and each saves an ordinary mod that rsmm apply installs. Nothing from the game is bundled with the editor. The same editors also run in the browser with no install: the web editor.

Tab	What it builds
Items	a copy of a shipped magical item with its own id, name, text, rarity, icon, values and the stat each effect gives (kind = "item")
Talents	changed talent values (kind = "talent", one block per entity file) and renamed talent cards (kind = "skill")
Abilities	[[content.abilities]] steps for a custom hero: every number an ability uses, plus a graph for re-pointing links and copying parts
Map	a chapter’s map-generation recipe (kind = "tilegen") on a 3D view of its terrain

./rsmm editor                      # serve on 127.0.0.1:8765 and open a browser
./rsmm editor --tab map            # open on another tab: items, talents, abilities, map
./rsmm editor --port 9000          # pick the port (falls back to a free one)
./rsmm editor --no-browser         # just print the URL
./rsmm editor --game-dir "D:\SteamLibrary\steamapps\common\Ravenswatch"   # when it isn't found
./rsmm restore --all && ./rsmm apply   # install what you saved

item-editor, talent-editor, ability-editor and map-editor still work: each opens this editor on its tab.

The tab bar names the install the editor reads. When none is found, every tab says so and shows the --game-dir command to start it with; the folder can be Ravenswatch itself or DarkTalesResources inside it (RSMM_GAME_DIR works too). A dot on a tab means it holds changes that are in no mod yet. Item, talent, test-grant and ability changes are kept in your browser until you save them; Map changes are not, so closing the page with unsaved Map changes asks first.

Items and Talents. Check builds the blocks with the real kind builders, so it reports exactly what rsmm apply would refuse. Add to mod appends them to a mod’s manifest.toml, or creates the mod. An item copy’s id must be as long as its base’s: the copy keeps every byte offset. A hero’s number of talents is fixed, so the Talents tab edits existing talents rather than adding new ones.

Abilities. The page never writes a mod: press Copy manifest code and paste the steps under your custom hero’s [[content]] block (kind = "hero").

Map. The page shows every tile slot of a chapter on a 3D (or top-down) view of its painted terrain: height, design paths, blocked ground and water. Each slot is coloured by whether the selected tile can land there in the selected scenario. You can change how many of each tile kind the generator places, their minimum spacing, which footprints each kind fits, the per-flag quotas, and which kinds each slot may hold. Saving writes mods/<id>/manifest.toml with one tilegen declaration, which reopens in the editor. The tilegen kind is ⚠️ experimental: the recipe round-trips byte-identically, but an edited recipe has not yet been shown to change what generates.

The server answers only loopback hosts, and every write needs a token that exists only in the pages it served.

Numeric values and texture swaps

There is no dedicated command for these. A mod declares them as [[patch]] blocks in its manifest (or with m.stat(...) from the SDK), and rsmm apply merges every enabled mod’s patches — see Numeric balance and Texture swap. Find the names with rsmm assets search:

./rsmm assets search globalvalue Bleed     # a global value: Bleed_Duration_Value
./rsmm assets search enemycampdifficultydef  # camp difficulty bands (Easy, …)
./rsmm assets search Heroes Portrait png   # texture paths

rsmm values — back up a patch before a game update

A game update rebalances values in place, and afterwards the old ones exist nowhere: the update overwrites the files apply backed up from. Take a snapshot while the current patch is still installed:

./rsmm values snapshot                     # saves <date>-build<steam build id>
./rsmm values list
./rsmm values diff 2026-10-01-build23766761              # vs the install now
./rsmm values diff <old> <new> --filter Snow_Queen       # two snapshots
./rsmm values extract <old> EntitySettings/Heroes/Hero_Snow_Queen/Hero_Snow_Queen_Ice_Clone.entity.ot.EntitySettingsResource.gen -o old.gen

A snapshot holds every entity field as the editors show it, each magical object’s values and modifiers, and the pristine cooked bytes of EntitySettings/, Definitions/ and GlobalValues/ (about 9 MB). It is read from the install, never the authoring mirror, and stored in the per-user data directory (~/.local/share/rsmm/snapshots, %LOCALAPPDATA%\rsmm\snapshots), so restore --all and Steam’s file check leave it alone.

---

Debugging

rsmm doctor

See Core commands.

rsmm apply --dry-run

Show which cooked files the enabled mods would change, touching nothing. See rsmm apply.

./rsmm apply --dry-run

rsmm diff <id>

Show what applying one mod changes, without touching anything. Every file the mod ships is listed as replacing a game file (~), adding a new one (+), or being skipped because no game path can be derived for it (?). A file another enabled mod also writes is marked as merged (text banks, tile pools, resource caches and alias tables combine) or as a conflict naming the mod whose copy lands. [[patch]] fields set to a different value by another mod say which one wins under load_order. When the game is found, the summary also counts files that are installed and files that still need rsmm apply.

./rsmm diff my-mod            # first 15 files per section; conflicts always shown
./rsmm diff my-mod --all      # every file
./rsmm diff my-mod --json     # for scripts

Reading the loader log

Read the loader log of the last game launch. See rsmm log.

rsmm decode <file>

See Asset editing.

---

Common workflows

Goal	Commands
First-time setup	./rsmm doctor
Install all mods	./rsmm apply
Iterate on a mod	./rsmm watch (runs in background)
Package for sharing	./rsmm pack MyMod
Roll back everything	./rsmm restore --all
Launch the game	./rsmm run

---

Global options

Flag	Description
--game-dir <path>	Custom Ravenswatch installation path
--help	Show help for any command
--version	Show RSMM version