steamos-add-to-steam

Add a program to Steam library

$ steamos-add-to-steam [path/to/file]

steamos-add-to-steam [OPTIONS] NAME EXECUTABLE_PATH [WORKING_DIRECTORY]
The NAME is the display name for the shortcut in Steam.
The EXECUTABLE_PATH is the full path to the executable to be launched.
The optional WORKING_DIRECTORY specifies the working directory for the executable.

NAME
    The display name for the shortcut within the Steam client.

EXECUTABLE_PATH
    The full path to the executable file that Steam will launch.

WORKING_DIRECTORY
    (Optional) The directory where the executable should be run from. Essential for many games or applications to find their assets.

-h, --help
    Displays a help message and exits.

--verbose
    Enables verbose output, showing more details about the command's operations.

--dry-run
    Performs all steps except for the final modification of Steam's configuration files. Useful for testing.

--desktop-shortcut
    Creates an additional shortcut on the user's desktop (typically a `.desktop` file on Linux).

--run-in-terminal
    Launches the application within a terminal window, useful for console-based applications or for debugging output.

--category
    Assigns the new shortcut to a specific category (e.g., 'Emulators', 'GOG Games') within your Steam library.

--launch-options
    Specifies custom launch options for the executable, often used for Proton commands (e.g., `PROTON_LOG=1 %command%`) or game-specific arguments.

--img
    Sets a custom banner or grid image for the shortcut within Steam's UI.

--icon
    Sets a custom icon for the shortcut.

--gameid
    (Advanced) Assigns a specific Steam AppID to the shortcut. Generally not needed for typical user additions.

The steamos-add-to-steam command is a utility designed to seamlessly integrate non-Steam applications, games, or emulators into your Steam client library. This is particularly valuable on SteamOS, the Steam Deck, and other Linux systems where users desire a unified interface for managing and launching all their entertainment content. Instead of manually navigating Steam's graphical user interface to add a "Non-Steam Game," this command automates the creation of a Steam shortcut. It handles essential details such as setting the correct executable path, defining the working directory, and applying custom launch options. This functionality is crucial for adding titles from other digital storefronts like GOG or Epic Games Store, as well as emulated games, ensuring they appear alongside your native Steam library. It significantly enhances the user experience by simplifying library management and allowing for consistent launch behavior through Steam.

The steamos-add-to-steam command directly modifies Steam's configuration files, primarily shortcuts.vdf. For changes to take effect, the Steam client often needs to be restarted or its library refreshed. Ensure that the specified EXECUTABLE_PATH and WORKING_DIRECTORY are correct and accessible by Steam, especially if they are located on external drives or within Wine/Proton prefixes. Behavior and available options may subtly vary across different SteamOS versions or Steam client updates.

Steam stores non-Steam game shortcuts in a binary configuration file named shortcuts.vdf, located within the user's Steam userdata directory (e.g., ~/.steam/steam/userdata/<UserID>/config/shortcuts.vdf). The steamos-add-to-steam command automates the complex process of correctly formatting and adding entries to this file, which would otherwise require manual editing or navigating a graphical interface.

This command is frequently used in conjunction with Valve's Proton compatibility layer. Users can specify a Windows executable (e.g., an .exe file from a GOG game) as the EXECUTABLE_PATH, and then use the --launch-options parameter to force a specific Proton version or add Proton-specific environment variables, enabling Windows games to run smoothly through Steam.

The steamos-add-to-steam utility emerged as part of the SteamOS ecosystem, initially to simplify the integration of non-Steam content on Valve's Linux-based gaming operating system. Its importance surged with the release of the Steam Deck, where a seamless experience for managing both Steam and non-Steam content is paramount. It addresses the historical challenge of integrating external games and emulators into the Steam client's Big Picture Mode, which is optimized for controller input and a console-like experience.

steam(1) - The main Steam client application., xdg-open(1) - A general command for opening files or URLs with the user's preferred application, conceptually related to launching.