Skip to content

Command line & AI agents

Most of what you do in Laufzeit's window can also be done from a terminal: add and edit games, create prefixes, install winetricks packages, download runners, pick artwork, launch games, connect store accounts and install their games, and sort the library into categories. That makes Laufzeit scriptable, and it lets an AI coding agent such as Claude Code run your library for you: you say what you want, the agent does it, and you play.

How it works

Call Laufzeit with a command instead of no arguments:

laufzeit game list
laufzeit prefix list
laufzeit runner list
laufzeit --help            # every command
laufzeit game add --help   # one command's options

With the AppImage, that's ./laufzeit_*.AppImage game list. With the Flatpak, it's flatpak run io.github.firsttris.Laufzeit game list; an alias saves typing it:

alias laufzeit='flatpak run io.github.firsttris.Laufzeit'

laufzeit skill install from the Flatpak writes that form into the skill, so an agent uses it from the start.

The commands do exactly what the matching buttons do: the same checks, the same prefix setup, the same launch. They work while Laufzeit's window is open, too. The window notices the change within a second and shows it, so you can watch a script fill your library.

Laufzeit runs without a window for these commands, but it still needs your desktop session (as for any launch), so run them in a terminal on your desktop rather than over SSH.

A game is named by its ID (laufzeit game list shows the first 8 characters, which are enough), by its name, or by a part of its name that only one game has: laufzeit game launch quake.

Games

Command Does
game list Lists the games with ID, runner, UMU ID and prefix
game show <game> Shows all of a game's settings
game add --exe <exe> --prefix <dir> --runner <id> [settings] Adds a game. A prefix Laufzeit doesn't know yet is added (and created) first. Without --name, the name comes from the .exe
game install <installer> --prefix <dir> [--runner <id>] [--name] [--exe] [--setup] [settings] [-- <installer args>…] Runs a game's installer in a prefix and adds the game it installed. The installer is a setup .exe or .msi, or a disc image (.iso). Without --runner, the newest Proton. See Installing from a setup file or a disc
game edit <game> [--name] [--exe] [--prefix] [--runner] [--clear-env] [settings] Changes a game. Whatever you don't pass stays as it is
game remove <game> Removes the game from the library, like Remove in the window. Prefix and game files stay
game launch <game> Starts the game and waits until it exits; prints the log's path
game stop <game> Ends the game's whole session, also one the window or Steam started
game log <game> [--print] Prints the path of the latest log, or with --print the log itself
game artwork <game> [--query] [--steamgriddb-id] [--kinds cover,icon,wide,hero,logo] Picks the best-rated SteamGridDB images (needs the API key)
game shortcut <game> [--place menu\|desktop] Creates a start menu or desktop shortcut
game steam-add <game> [--restart-steam] / game steam-remove <game> Adds the game to Steam, or removes it

The settings game add, game install and game edit take:

Option Sets
--env KEY=VALUE An environment variable (repeatable). --unset-env KEY removes one
--args "…" The launch arguments, quoted as on a Windows command line
--notes "…" The game's notes, shown on its card; "" removes them
--umu-id <id> The protonfixes match. A Steam app ID such as 377160 becomes umu-377160; "" removes it. --umu-store gog sets the store
--proton NAME=on\|off\|default A Proton switch for this game (repeatable), for example --proton PROTON_USE_WINED3D=on
--gamemode, --power-profile, --inhibit-sleep, --mangohud on, off, or default to follow the global setting again

For example, Fallout 4 with Proton-GE, its protonfixes, and the frame rate cap its physics need:

laufzeit game add --name "Fallout 4" \
  --exe "/games/Fallout 4/Fallout4.exe" \
  --prefix ~/Games/prefixes/fallout4 \
  --runner GE-Proton10-30 \
  --umu-id 377160 \
  --env DXVK_FRAME_RATE=58

Installing from a setup file or a disc

game install does what Run installer does in the window, in one step:

  1. It adds the prefix if Laufzeit doesn't know it yet.
  2. A disc image is mounted read-only with udisksctl (no root needed) and unmounted again at the end. The installer on it is the one its autorun.inf starts, else its setup.exe or install.exe; --setup <path on the disc> picks another.
  3. It runs the installer and waits until it, and everything it started, has ended.
  4. It adds the game the installer created a shortcut for, named after the shortcut unless --name is given.
laufzeit game install ~/Downloads/setup_game_1.0.exe --prefix ~/Games/prefixes/game \
  -- /VERYSILENT /SUPPRESSMSGBOXES /DIR="C:\Games\Game"
laufzeit game install ~/ISOs/GAME_DISC1.iso --prefix ~/Games/prefixes/game --umu-id umu-12345

Everything after -- goes to the installer. Many installers run without a window when told to:

Installer Arguments
Inno Setup (GOG's offline installers, many others) /VERYSILENT /SUPPRESSMSGBOXES /DIR="C:\Games\<name>"
NSIS /S, and to pick the folder '/D=C:\Games\<name>' last. NSIS ignores /D for a folder with a space in it, as Wine passes that argument on in quotes
Windows Installer (.msi) /qn

An installer that has to be clicked through opens its window on the desktop as usual, and the command waits until you (or a computer-use tool) are done. If the installer creates no shortcut, or several (a game and its configuration tool, say), the command names them and stops: add the game with game add then, or pass --exe the next time. The installer's log is in the error, and in the result as log_path. Ctrl+C, or an agent's command timeout, ends the installer and unmounts a disc image again.

Disc images whose game checks for the disc while it runs, and installers that ask for a second disc, aren't covered. Without udisksctl (the udisks2 package), extract the image first, for example with 7z x game.iso -ogame, and pass the installer in it.

Library, categories and favorites

game commands work on the games in the library. The library and category commands cover the whole library: also the games of your connected stores that aren't installed yet. They name a game by its key, which library list shows: epic:<app>, gog:<id> or amazon:<id> for a store's game, the game's ID for one you added by hand. Its name, or a part of it only one game has, works too.

Command Does
library list [--category <name>] [--favorites] [--hidden] [--tested works\|issues\|broken\|untested] [--compatibility] Lists every game with its key, source, whether it's installed, its categories, play time and test result. Hidden games only with --hidden; --tested lists only the games with that test result; --compatibility adds each game's ProtonDB rating and umu-protonfixes match
library favorite <game>… [--off] Marks games as favorites, or unmarks them
library hide <game>… [--off] Hides games from the library (they show up under Hidden), or shows them again
library test-status <game> works\|issues\|broken\|clear [--note "…"] Notes how an installed game ran when tested: it works, works with issues (black videos, no sound, needs a login), or is broken. The window shows it as a small ✓, ! or ✕ on the cover, the note as its tooltip. clear takes the result away
category list Lists the categories and how many games each holds
category add <name> Creates a category, e.g. Kinder
category rename <category> <new name> Renames a category
category remove <category> Deletes a category; its games stay in the library
category assign <category> <game>… Puts games in a category; a game can be in several
category unassign <category> <game>… Takes games out of a category

A store game keeps its categories, favorite mark and play time when it's installed, uninstalled and installed again.

Sorting a whole library into categories is a job for an agent: "Create the categories Kinder, Koop and Rennspiele, and sort my games into them." It reads laufzeit library list --json, decides per game, and calls laufzeit category assign Kinder epic:Fortnite gog:1207658924 ….

Stores

Command Does
store list Lists Epic Games, GOG and Amazon Games: connected or not, the account, how many games
store login <store> Opens the store's login page in the browser (epic, gog or amazon)
store connect <store> <code> Finishes the login with the code the page shows, then fetches the game list
store disconnect <store> Signs out; games installed from the store stay installed
store sync <store> Fetches the store's game list again, for example after buying a game
store install <game> [--dir <dir>] [--prefix <dir>] [--runner <id>] Installs a store game and adds it to the library. Without options: the store's last install folder, a new prefix of its own and the newest Proton
store uninstall <game> Deletes a store game's files and takes it out of the library; it stays in the store's list

The games are named as in library list: by key (epic:<app>, gog:<id>, …) or name. All of a store's games, installed or not, show up there once it's connected.

Logging in still needs you: store login opens the store's page in the browser and prints its address (open that yourself when there's no browser to open, over SSH say). Sign in there and pass on what the page shows, as with Connect in the browser in the window (see Connecting your account): for Epic the page's text, for GOG and Amazon the address from the address bar. store connect takes it as it is. The code works once and only for a few minutes.

store install prints its progress on stderr (a line that updates in a terminal, every 10 % in a log) and returns the new game (with --json, as JSON). It takes a while, so an agent should run it in the background. Ctrl+C, or the agent's own timeout, stops the download as the window's Cancel does. An open window shows the game in the library once it's installed, not on its Downloads page, which only shows the window's own installs. A store connected, synced or disconnected from the command line shows up in the window after its next start or Refresh library.

Only one install per store runs at a time, also across the window and the command line: a second one is refused while the first runs.

Prefixes

Command Does
prefix list Lists the prefixes, whether they're set up yet, and their games
prefix add <dir> Adds an empty or new folder, or an existing prefix (also a Steam compatdata folder)
prefix remove <dir> Takes a prefix off the list; the folder stays
prefix winetricks <dir> [--runner <id>] <package>… Installs winetricks packages. Without packages, lists the installed ones
prefix tool <dir> [--runner <id>] <tool> Opens winecfg, regedit, cmd, winefile, taskmgr or uninstaller
prefix run <dir> [--runner <id>] <program> [args…] Runs a program in the prefix and waits for it: an installer, or one of Wine's builtins such as regedit /S settings.reg

Without --runner, a prefix command uses the runner all of the prefix's games use.

Runners and umu-launcher

Command Does
runner list Lists the installed runners and how many games use each
runner sources Lists where runners can be downloaded from (proton-ge, …)
runner releases <source> Lists a source's recent releases
runner download <source> [<tag>] Downloads and verifies a release, the latest without a tag
runner remove <id> Deletes a runner no game uses
umu status / umu install Shows or installs/updates umu-launcher
umu search <name> Finds the UMU ID (protonfixes match) for a game

Backup and restore

Command Does
backup create [<file>] [--with-secrets] Backs up the library, all settings, categories, play times and artwork to one file: the one given, or laufzeit-backup-<UTC date>-<time>.tar.gz in the current folder. The API keys only with --with-secrets
backup list Lists the automatic backups (when turned on under Backup, and before every restore), newest first and numbered. A backup create file isn't among them
backup restore <file or number> Restores a backup: a file, or a number from backup list. What is now is backed up first, so laufzeit backup restore 1 undoes it

See Backup and restore for what a backup holds.

JSON output and exit codes

Add --json to any command to get its result as JSON on stdout, for example laufzeit game list --json (or laufzeit --json game list). Messages for people (progress, notes) always go to stderr, so they never mix into it.

A command exits with 0 on success, 1 when it fails (the error is printed to stderr), and 2 when its arguments are wrong. game launch exits with 1 when the game exits with an error, and prefix run when the program does.

Working with an AI agent

The command line is made to be driven by an AI coding agent like Claude Code. Start the agent in a terminal on your desktop, tell it to use laufzeit (it finds every command with laufzeit --help), and keep Laufzeit's window open: it shows each change within a second, so you see what the agent does and can try a game right away.

The Laufzeit skill

Laufzeit comes with an Agent Skill: a SKILL.md that teaches an agent how to work with Laufzeit. It covers the commands, --json, backing up first, one game at a time, reading the logs, protonfixes, test results and notes. With it installed, the agent picks it up by itself whenever you talk about your games.

Command Does
skill install [--dir <dir>] Installs the skill for Claude Code, in ~/.claude/skills/laufzeit/. --dir puts SKILL.md into another folder, for an agent that reads skills from elsewhere
skill show Prints the skill, to read it or paste it into an agent that doesn't read skill files
laufzeit skill install

Run it again after updating Laufzeit: the skill is built into Laufzeit, so the installed one then matches the new version's commands. Neither command needs the desktop session, so they work over SSH too. The skill is also in the repository, at skills/laufzeit/SKILL.md.

What you can hand over:

Task For example
Set games up "Add every game under ~/Games to Laufzeit, with Proton-GE, one prefix per game, the right protonfixes match and artwork."
Install from a setup file or disc "Install the game from ~/ISOs/GAME.iso into its own prefix, then find its protonfixes match and artwork."
Install from your stores "Connect my GOG account and install all my GOG games that are rated Gold or better on ProtonDB."
Move games over "These games come with their own Wine and start scripts. Move each game out of its bundled prefix, add it to Laufzeit with Proton, and carry over the fixes from the scripts and my save games."
Fix games "Fallout 4 crashes on start. Read its latest Laufzeit log and fix it."
Test games "Add all games under /mnt/games/ and check whether each one starts." (needs a computer-use tool, see Testing games on screen)
Organize the library "Create the categories Kids and Adults and sort all my games into them. Hide the store giveaways I've never played."
Tidy up "Give every game without artwork a cover, and add my favorites to Steam."

Organizing the library

The agent reads the whole library, store games not installed yet included, with laufzeit library list --json: each game's key, name, source, categories and play time. Then it creates the categories it needs and sorts the games in by key:

laufzeit category add Kids
laufzeit category add Adults
laufzeit category assign Kids epic:Fortnite gog:1207658924
laufzeit category assign Adults "Fallout 4"
laufzeit library favorite "Fallout 4"
laufzeit library hide amazon:amzn1.adg.product.1234

It can decide by the names it knows, or look games up first (their age ratings, genres, co-op modes). The categories show up as chips above the library right away.

Testing games on screen

The command line tells an agent whether a game's process started and ended, and the log tells it what Wine and Proton printed. Whether the game actually shows its menu, a black window or an error dialog, the agent can only see on the screen. A computer-use tool for the Linux desktop lets it: an MCP server that gives the agent screenshots, mouse and keyboard. For example:

With one connected, the agent can test a whole library on its own:

  1. Start a game in the background: laufzeit game launch <game> & (it waits until the game exits).
  2. Wait a little, then take a screenshot and judge it: the game's menu, a launcher window to click through, a black screen, an error dialog.
  3. Stop it with laufzeit game stop <game> and read laufzeit game log <game> --print if it looked wrong.
  4. Fix the setup and try again.
  5. Note the result: laufzeit library test-status <game> works, issues --note "Videos stay black" or broken --note "Crashes on start with VK_ERROR_DEVICE_LOST; tried WINED3D".

A result belongs to the runner and exe the game had when tested. Once either changes, the window shows it faded and library list --tested untested lists the game again, so "test every game that's untested" also catches the ones whose setup changed since.

These tools are community projects and get full control of your desktop: check what one does before you install it, and stay near the computer while the agent tests. Games that need an online login or a controller still need you.

Setting games up

Back up first. Before a larger change, have the agent run laufzeit backup create. If something goes wrong, laufzeit backup restore <file> brings everything back (and a restore can be undone too).

A good way to work with an agent:

  1. One game at a time. The agent adds a game; you start it from the window and say whether it works. The window shows the changes right away.
  2. Let it read the logs. laufzeit game log <game> --print shows the agent what Wine and Proton printed, which is usually where the fix is.
  3. Protonfixes first. With the right --umu-id (laufzeit umu search <name>), umu applies the fixes known for that game automatically. Many games then need nothing else.
  4. Carry over what other launchers set. Launch scripts and other launchers often set environment variables (DXVK_FRAME_RATE, WINEDLLOVERRIDES, …), winetricks packages or registry keys. Most generic ones (DXVK, d3dx9, esync and fsync) are built into Proton already; the game-specific ones become --env, prefix winetricks and prefix run … regedit /S file.reg.
  5. Write down what you found. --notes keeps it with the game: an offline login, why an override is set, which config file holds the resolution. The next person (or agent) sees it on the card.
  6. Save games live in the prefix. When a game moves to a new prefix, have the agent copy its saves from the old prefix's drive_c/users/… (Documents, Saved Games, AppData) into the new one's drive_c/users/steamuser/….

Moving and copying files is up to the agent's own tools; Laufzeit's command line takes over from there. Nothing an agent does through it deletes game files or prefixes, with one exception: store uninstall deletes a store game's files, as Uninstall in the window does (the game can be installed again from the store). Removing a game or a prefix only takes it off Laufzeit's lists.