⚠️ NOTICE: nonsteam is beta software! ⚠️

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

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.

CLI

Installation

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.

Basic usage

⚠️ 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.

List all non-Steam games

$ nonsteam get

2502275492: GOG Galaxy
3733884208: Dolphin

Get detailed information about one (or more) games

$ 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%'
  ...

Modify an existing game

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

... Updated app with ID: 2502275492

Add a new non-Steam game

$ 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

Add images from URLs or local file paths

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"

Add images from steamgriddb.com

nonsteam edit -w 4148342750 --sgdb-id 36334

Combine both approaches to override SGDB images

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

Remove a non-Steam game

$ nonsteam delete -w 4148342750

... Deleted app with ID: 4148342750

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

Fields for non-Steam games

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.

| Steam | nonsteam CLI | nonsteam API | Type | | - | - | - | - | | appid | --app-id | appId | number (10-digit) | | AppName | --app-name | appName | string | | Exe | --exe | exe | string | | StartDir | --start-dir | startDir | string | | icon | --icon | icon | string | | ShortcutPath | --shortcut-path | shortcutPath | string | | LaunchOptions | --launch-options | launchOptions | string | | IsHidden | --is-hidden | isHidden | boolean | | AllowDesktopConfig | --allow-desktop-config | allowDesktopConfig | boolean | | OpenVR | --open-vr | openVr | boolean | | Devkit | --devkit | devkit | boolean | | DevkitGameID | --devkit-game-id | devkitGameId | string | | DevkitOverrideAppID | --devkit-override-app-id | devkitOverrideAppId | number* | | LastPlayTime | --last-play-time | lastPlayTime | Date | | FlatpakAppID | --flatpak-app-id | flatpakAppId | string | | tags | --tags | tags | string[] |

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

Using a specific non-Steam games file

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

Saving changes

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.

Creating a new non-Steam games file

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"

Environment variables

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

API

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();