Universal Modder um CLI: Commands, Options and Examples

The um command connects game discovery, asset tools, backups and field notes. Start with um --help, then add a group and --help to inspect the command you need. If your terminal cannot find it, follow the Universal Modder install guide or the um command not found fix.

Select code

um --version
um --help
um scan --help

You can select the code to copy it manually.

This reference covers universal-modder 0.2.0. The help output shown matches that release, and the operation examples show syntax to adapt to your own files and paths. Browse the um package source on GitHub for the full implementation.

Choose a command

Task	Command	What it needs
Find an installation or inspect its engine	`um scan`	A local game installation
Generate hosted art, models or audio	`um fal`	A fal key and the selected service
Generate images through ComfyUI	`um comfy`	Your running ComfyUI server and models
Resize, cut out or pack existing images	`um sprite`	Input images
Turn a GLB into directional sprite frames	`um render3d`	Blender and a model
Inspect or capture Windows game windows	`um win`	Windows, directly or through WSL
Inspect footage and assemble a video	`um video`	Media files and ffmpeg
Save, compare or restore a folder snapshot	`um backup`	A source folder and backup storage
Check a release folder	`um publish check`	Your prepared mod folder
Search, draft or check a field note	`um kb`	A local or synced knowledge base

Use the Universal Modder tutorial to put these commands in order, or use game-modding prompts to describe the task to your agent. The agent's skill, the um executable and optional fal connection are separate installation checks.

um scan

scan accepts a game name for fuzzy matching or a direct installation path. --list lists discovered Steam, Epic and Xbox installations; --json selects machine-readable output. It helps identify engine/runtime clues, loaders, save locations and possible routes before you choose a modding approach.

Select code

um scan --list
um scan "Terraria" --json
um scan "/path/to/your/game" --json

You can select the code to copy it manually.

Help output:

text

Select code

usage: um scan [-h] [--list] [--json] [game]

You can select the code to copy it manually.

Output to expect: a discovery list or a report for the selected game. Its findings depend on your installation, and an engine match is a starting point for choosing a route. Record the game's version alongside the result.

um fal

The fal group offers image, sprite, editing, texture, 3D, rigging, audio and video recipes, plus model search, schema and price lookup. Recipe examples take a prompt or input file, with --out and --name controlling saved outputs. --model selects an endpoint; repeatable --set passes additional model inputs.

Select code

um fal price fal-ai/trellis-2
um fal sprite "a small brass lantern, side view, readable game sprite" --out assets/gen --name lantern

You can select the code to copy it manually.

Help output:

text

Select code

usage: um fal price [-h] endpoint

You can select the code to copy it manually.

Output to expect: price lookup prints JSON; generation downloads returned files and appends provenance to fal_manifest.jsonl in the output folder. Hosted generation can incur charges, and local reference files are uploaded when used as inputs. Choose the endpoint and review its current price before generating. For authentication setup, use the FAL_KEY is not set guide.

um comfy

comfy sends image work to a ComfyUI server. status checks connectivity and available checkpoints; image uses the standard text-to-image graph; run accepts a workflow exported in API format. Start your server and load the required models first.

Select code

um comfy status
um comfy image "a small blue potion bottle" --size 512x512 --seed 7 --name potion --out assets/local
um comfy run my-workflow.json --name potion

You can select the code to copy it manually.

Common options include --url, --checkpoint, --steps, --seed and --sprite. The default address is http://127.0.0.1:8188, or COMFYUI_URL when set. The built-in image graph targets SD 1.5/SDXL-style checkpoints; other workflows use run.

Output to expect: images in --out and entries in comfy_manifest.jsonl. A fal key is unnecessary for this route, but the server, models and hardware are your own prerequisites.

um sprite

sprite transforms existing files locally. Its subcommands cover cutout, fitting, pixelation, palettes, sheets, slices, frames, team masks, seamless textures and previews. For fit, input and output come first, followed by the required --size.

Select code

um sprite fit assets/lantern-source.png assets/lantern.png --size 64x26 --anchor center --hard-alpha
um sprite sheet assets/lantern-sheet.png assets/frame-01.png assets/frame-02.png --cols 2

You can select the code to copy it manually.

fit uses nearest-neighbor resizing by default; --smooth switches to Lanczos for painted art. --no-upscale prevents enlargement. sheet takes output before frames, supports --pad, and offers --vertical for a one-column strip.

Output to expect: transformed image files at your chosen paths. Inspect dimensions, alpha and frame order against the game's requirements. A saved PNG still needs an in-game check. See the Terraria example for the purpose of this pipeline.

um render3d

render3d runs Blender to create sprite frames from a GLB. Presets are aoe2, iso8, trueiso, topdown, side and turntable. Choose a camera that matches the target game, then set canvas dimensions and the model's rendered size.

Select code

um render3d model.glb frames/ --preset iso8 --canvas 128x128 --length 96 --anims idle:1:still

You can select the code to copy it manually.

Useful options include --headings, --elevation, --engine cycles or --engine eevee, and --shadows. --anims accepts comma-separated name:frames:motion entries. Blender must be discoverable on PATH or selected through BLENDER.

Output to expect: PNG frames named by animation, heading and frame; optional shadow passes have _s in their names. Packing the frames into a game-specific format is a later step. The Age of Empires II example explains that distinction.

um win

win provides Windows process/window tools, capture, recording and input. It targets native Windows or WSL driving Windows. Start by inspecting the target window before using capture or input commands.

text

Select code

um win ps Terraria
um win shot --exe Terraria.exe terraria-window.png --scale 0.33
um win record --exe Terraria.exe --out C:\ModLab\terraria-take --seconds 12

You can select the code to copy it manually.

Window selection uses --exe, --title or --hwnd; recording also accepts --pid for audio selection. record supports --fps, --no-audio and --crop. setup installs the bundled Windows tools and downloads a checked ffmpeg build with gfxcapture; it changes your local setup, so run it deliberately.

Output to expect: ps lists processes with windows; shot writes an image; record writes .mkv, .audio.raw and .json files. Input via drive and registry changes are distinct actions. Review the workflow's safety boundaries before automating them.

um video

video inspects and edits existing footage. Use probe for media properties, contact for a timestamped frame grid and compile for an edit decision list. Other commands include mux, beats and first-frame.

Select code

um video probe take.mp4
um video contact take.mp4 contact.jpg --every 2 --cols 6
um video compile edit.json showcase.mp4 --preview

You can select the code to copy it manually.

contact supports --start, --end and thumbnail --width. compile --preview uses a quicker, reduced-resolution encode; --keep retains its work folder. The JSON edit list must follow the format defined in the video module.

Output to expect: JSON from probe, a contact-sheet image or an encoded video, depending on the subcommand. If the process cannot start ffmpeg, follow the Universal Modder ffmpeg fix before changing the edit list.

um backup

backup snapshots folders, lists snapshots, compares changes and restores a chosen snapshot. Give a backup a recognizable name and keep the source location in your modding notes.

Select code

um backup create "/path/to/lab-saves" --name terraria-lab
um backup list terraria-lab
um backup diff terraria-lab "/path/to/lab-saves"
um backup restore terraria-lab --to ./restore-check

You can select the code to copy it manually.

create accepts --note. diff and restore can select a specific --snapshot. Without --yes, restore prints a preview and exits with a request to rerun; it does not wait for an interactive answer. After reviewing the snapshot and target, add --yes to perform the restore. --clean also removes files absent from the snapshot. Begin with a separate restore-check directory so you can inspect the result.

Output to expect: a snapshot ZIP and manifest under the toolkit's backup storage, a JSON difference report, or a restore summary. The default storage is ~/.universal-modder/backups/; UM_HOME changes the toolkit's state directory.

um publish check

publish check inspects a prepared mod folder before sharing. Pass --game to compare its files with your owned game installation and detect byte-identical copies.

Select code

um publish check ./MyMod --game "/path/to/owned/game"

You can select the code to copy it manually.

Help output:

text

Select code

usage: um publish check [-h] [--game GAME] mod

You can select the code to copy it manually.

Output to expect: individual failure/warning lines and a summary containing file, failure and warning counts. It checks for leaked secrets and game-file copies, and warns about items such as decompiler fingerprints or missing documentation. A warning can coexist with exit status zero, so read the report. It checks files only and does not upload a release.

um kb

kb searches and maintains field notes. Search before repeating a game's earlier experiments, and keep the note's versions and verification status attached to anything you reuse.

Select code

um kb search terraria --route loader-api --limit 5
um kb new --game Terraria --title "A small lantern weapon" --out knowledge/games/terraria/lantern-weapon.md
um kb check knowledge/games/terraria/lantern-weapon.md

You can select the code to copy it manually.

Search filters include --game, --engine and --route; --json changes output format. --root chooses a knowledge root, and --remote searches the synced copy even from a clone. sync refreshes that cache. Run new inside a clone of the Universal Modder repository containing the knowledge template, or supply an appropriate --root; the standalone executable alone does not provide that editable checkout. new --from-scan can gather local game information, so omit it if you only want to draft a blank note.

Output to expect: matching note summaries or JSON, a newly written Markdown note, or validation findings. pr prepares a contribution and is a dry run without --yes; submitting a contribution changes a remote repository and needs a deliberate publishing decision.

Check syntax on your installed version

Run the most specific help command when a copied example is rejected. Include the recipe or subcommand: um fal sprite --help, um backup restore --help, or um kb search --help. Record um --version with the exact redacted error when asking for help. The troubleshooting index separates command discovery, agent integration, authentication and media dependencies.

Frequently asked questions

Does um --help call a paid API?

No. Version and help output come from the local argument parser. Generation commands are separate and can contact hosted services.

Can I use the CLI without an agent plugin?

Yes. Install the standalone toolkit CLI in your chosen environment, then check um --version and um --help. Agent skill discovery and optional fal authentication are separate.