While I've successfully used it for my own purposes, it's still in its infancy. Please create an issue if you encounter any problems, and be sure to make backups of your shortcuts.vdf file!

nonsteam is a tool and library for viewing and editing your non-Steam game entries from the command line or with code.

Steam stores its non-Steam game entries in an opaque binary file that can't be edited by hand or manipulated by common command-line tools. This has become an acute pain point with the introduction of the Steam Deck, as the Linux environment makes the CLI the most convenient means of performing customization.

If you already have node/npm installed you can simply install as a global module:

npm i -g nonsteam

Otherwise, you can download a precompiled binary from the latest release and put in your PATH.

⚠️ IMPORTANT ⚠️ Steam will not pick up changes to non-Steam games while running. Be sure to restart Steam after making any changes.

You can run nonsteam help to see a list of available commands, and nonsteam help <command> to get more details.

$ nonsteam get

2502275492: GOG Galaxy
3733884208: Dolphin

$ nonsteam get 2502275492 --details

appid: 2502275492
  AppName: 'GOG Galaxy'
  Exe: '"c:/path/to/executable.exe"'
  StartDir: '"c:/path/to/"'
  icon: ''
  ShortcutPath: ''
  LaunchOptions: 'SOME_ENV_VAR="foo" %command%'
  ...

$ nonsteam edit 2502275492 -w \
  --allow-overlay \
  --is-hidden false

... Updated app with ID: 2502275492

$ nonsteam add -w \
  --app-name "Dungeon Crawl Stone Soup" \
  --exe '"c:\program files\crawl\crawl.exe"' \
  --start-dir '"c:\program files\crawl\"' \
  --allow-overlay

... Added app with ID: 4148342750

nonsteam edit -w 4148342750 \
  --image-icon "my_icon.png" \
  --image-grid "https://cdn2.steamgriddb.com/grid/8e26736829e07acb465bc6eacbf2ed1f.png" \
  --image-grid-horiz "https://cdn2.steamgriddb.com/grid/66f041e16a60928b05a7e228a89c3799.png" \
  --image-hero "https://cdn2.steamgriddb.com/hero/03ed6c135c5912cf3bd6060f43ededf1.png" \
  --image-logo "https://cdn2.steamgriddb.com/logo/7d08c3cfc1bc6c0ca31c8fa6d89aa0f1.png"

nonsteam edit -w 4148342750 --sgdb-id 36334

nonsteam edit -w 4148342750 \
  --sgdb-id 36334 \
  --image-icon "my_icon.png" \
  --image-grid "https://cdn2.steamgriddb.com/grid/68300e070409b2fe66caf7b80bdb4502.png"

$ nonsteam delete -w 4148342750

... Deleted app with ID: 4148342750

For more information regarding the images that Steam uses, take a look here.

The field names for non-Steam game entries are inconsistent inside of Steam's binary format. For reference, here are all of Steam's native field names, with their equivalents as CLI options and in the nonsteam API.

Note that, in Steam's format, all of the fields are either strings, 32-bit unsigned integers, or string arrays. Other types are coerced back and forth as needed within nonsteam.

*You might find Valve documentation indicating that this field is a string. This is simply wrong based on real-world experimentation.

By default, nonsteam will attempt to locate the file containing your non-Steam game entries (shortcuts.vdf) by querying the registry on Windows or by looking in common install dirs on Linux. However, if your Steam installation is atypical, or if you'd just prefer to be explicit, you can use a specific file by passing the -i, --input option:

nonsteam get -i "C:\Program Files (x86)\Steam\userdata\241873089\config\shortcuts.vdf" 4148342750

nonsteam get -i ~/.steam/steam/userdata/241873089/config/shortcuts.vdf 4148342750

You are required to be explicit about how to save your changes. There are two options that control the output file, and at least one must be set for edit, add, or delete commands:

• -w, --overwrite will cause your changes to be destructively written back to the input file.
• -o, --output <path> will non-destructively write the updated file to the specified path.

The former is more convenient, but the latter is safer. You're strongly encouraged to make backups before using --overwrite.

A blank file can be used as input, so you can simply do:

touch new-shortcuts.vdf
nonsteam add -i new-shortcuts.vdf -w --app-name "My App"

echo $null > new-shortcuts.vdf
nonsteam.exe add -i new-shortcuts.vdf -w --app-name "My App"

If you find you keep reading and writing to the same file, which is very typical, and you're tired of typing -w -i <path>, you can use the following environment variables to set defaults:

NONSTEAM_OPTION_INPUT="$HOME/.steam/steam/userdata/241873089/config/shortcuts.vdf"
NONSTEAM_OPTION_OVERWRITE=true

In addition to the CLI interface, nonsteam also provides a TypeScript API. Documentation is coming, but, for now, here's a simple example:

import { load } from "nonsteam";

load().then(nonsteam => nonsteam
  .addEntry({
    appName: "My Non-Steam App",
    exe: "/path/to/executable",
  })
  .deleteEntry(1987654311)
  .editEntry(1234567890, {
    icon: "path/to/new/icon.png",
  })
  .save().then(() => console.log("success!"));
);

Or, with async/await:

const nonsteam = (await load())
  .addEntry({
    appName: "My Non-Steam App",
    exe: "/path/to/executable",
  })
  .deleteEntry(1987654311)
  .editEntry(1234567890, {
    icon: "path/to/new/icon.png",
  });
await nonsteam.save();