Commands

Run omavn on its own to see your library and what to do next.

installCopy Anchor Link

omavn install <download> [--id ID] [--title TITLE] [--proton] [--offline]
omavn install --pick

Unpacks, installs, and registers a game, then fetches its VNDB metadata and art. <download> can be a file or a folder. Alias: add.

• --id sets the library id (default: from the catalog or the folder name)
• --proton runs a Ren'Py game through Proton instead of natively
• --offline skips VNDB and art
• --pick chooses the download from a menu (Omarchy)

runCopy Anchor Link

omavn run <game> [--target ID] [--window | --gamescope] [-v] [--detach] [--print] [-- args...]

Launches a game. Alias: play. Ids, prefixes, and title fragments all work.

• --target picks another entry point, like a different edition or a config tool (omavn info lists them)
• --window / --gamescope override the display mode once (see display)
• -v shows Proton's output; otherwise it goes to the game's last-run.log
• --print shows the exact command instead of running it
• --detach returns right away

libraryCopy Anchor Link

omavn library

Pick a game from your library and play it. On Omarchy this is a full-screen cover grid; elsewhere a numbered list. Alias: pick.

list, infoCopy Anchor Link

omavn list
omavn info <game>

info shows the engine, runner, file and prefix paths, entry points, and notes.

setCopy Anchor Link

omavn set <game> display window      # auto | gamescope | window
omavn set <game> target amantes      # default entry point
omavn set <game> title "Dies irae"
omavn set <game> locale ja           # Japanese locale for untranslated games
omavn set <game> env.DXVK_HUD fps    # any environment variable
omavn set <game> env.DXVK_HUD        # remove it

metaCopy Anchor Link

omavn meta <game>             # refresh from VNDB
omavn meta <game> --vndb v548 # wrong match? pin the right entry
omavn meta --all

Refreshes metadata, art, the library card, and the app launcher entry.

removeCopy Anchor Link

omavn remove <game> [--yes]
omavn remove --pick

Deletes the game, its prefix, its saves (see omavn saves first), and its launcher entry. Asks first unless you pass --yes. Alias: rm.

savesCopy Anchor Link

omavn saves <game>          # save folders, newest first
omavn saves <game> --open   # open the newest in your file manager
omavn saves <game> --import /mnt/windows/Users/me/AppData/Roaming/light

Finds save data by what changed after install: the Wine prefix's AppData and Documents, save folders in the game, and ~/.renpy for native Ren'Py games. Back these up before omavn remove.

Coming from Windows? --import copies a save folder from your old Windows install (mounted drive, backup, USB stick) into the same place inside the game's prefix: everything after Users/<name>/ is kept, so AppData/Roaming/light lands where Dies irae looks for it. Games' readmes usually say where their saves live.

execCopy Anchor Link

omavn exec <game> -- winecfg
omavn exec <game> -- /path/to/patch.exe

Runs a program inside a game's Wine prefix. Handy for fan patches and config tools.

winetricksCopy Anchor Link

omavn winetricks <game> quartz wmp9

Installs Windows components into a game's prefix, for games whose movies or installers need them. Proton's built-in versions are usually better, so only reach for this when something doesn't work. Installed verbs are recorded in the game's manifest.

inspectCopy Anchor Link

omavn inspect <download>

Reports what omavn would do (game or installer, engine, entry points) without installing.

omarchyCopy Anchor Link

omavn omarchy setup | remove | status

See Omarchy.

runtimeCopy Anchor Link

omavn runtime list
omavn runtime install proton
omavn runtime install renpy 8.5.2

You rarely need this; runtimes are fetched when a game needs them. Set OMAVN_PROTON to a name from runtime list (or a path) to pin a Proton build.

selfCopy Anchor Link

omavn self update
omavn self check

Updates omavn in place from the latest GitHub release (checksum verified).

completionsCopy Anchor Link

omavn completions bash > ~/.local/share/bash-completion/completions/omavn

Also zsh, fish, elvish, powershell. The install script sets up bash and fish for you.

doctorCopy Anchor Link

Checks python3, display, Vulkan (including the 32-bit drivers most VNs need), gamescope, disk space, and runtimes.

feedbackCopy Anchor Link

omavn feedback [--kind bug|game|idea] [--game GAME] [message...]

Opens a prefilled GitHub issue. See Feedback.