I have a Steam Deck and a pile of self-contained Linux games — Godot exports, LÖVE builds, the odd plain ELF — that aren't on Steam. Getting one of them to show up in Game Mode as a proper library tile, with box art, controller-ready, is more fiddly than it should be. So I wrote a small tool to do the boring parts for me, and the most interesting part of building it turned out to be the file format Steam uses to track non-Steam games.
This is a writeup of that part: reading and rewriting shortcuts.vdf, why I did it with nothing but the Python standard library, and a couple of gotchas that cost me time so they don't cost you any.
Quick honesty note up front, because it shapes everything below: this is a side project. The format parsing is tested for clean round-trips, but I have not confirmed the full pipeline end to end on real Deck hardware yet. Treat the code as "interesting and worth poking at," not "battle-tested." Repo is at the bottom.
The actual problem
When you "Add a Non-Steam Game," Steam doesn't write a config file you can comfortably hand-edit. It records the entry in shortcuts.vdf, a binary file in Valve's KeyValues format, sitting in your userdata directory. If you want a game to appear without clicking through the UI, you have to write a valid entry into that binary file yourself.
