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
- Games
- Library, categories and favorites
- Stores
- Prefixes
- Runners and umu-launcher
- Backup and restore
- JSON output and exit codes
- Working with an AI agent
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:
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:
- It adds the prefix if Laufzeit doesn't know it yet.
- 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 itsautorun.infstarts, else itssetup.exeorinstall.exe;--setup <path on the disc>picks another. - It runs the installer and waits until it, and everything it started, has ended.
- It adds the game the installer created a shortcut for, named after the shortcut unless
--nameis 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 |
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:
- Computer Use MCP Server: xdotool and scrot, X11 only.
- codex-computer-use-linux: a small set of tools, also on Wayland (through ydotool).
With one connected, the agent can test a whole library on its own:
- Start a game in the background:
laufzeit game launch <game> &(it waits until the game exits). - 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.
- Stop it with
laufzeit game stop <game>and readlaufzeit game log <game> --printif it looked wrong. - Fix the setup and try again.
- Note the result:
laufzeit library test-status <game> works,issues --note "Videos stay black"orbroken --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:
- 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.
- Let it read the logs.
laufzeit game log <game> --printshows the agent what Wine and Proton printed, which is usually where the fix is. - 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. - 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 winetricksandprefix run … regedit /S file.reg. - Write down what you found.
--noteskeeps 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. - 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'sdrive_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.