SteamGrid Manager (sgm)

Back up, restore, and manage custom Steam library artwork on SteamOS. Scan game libraries, create Steam shortcuts, and download artwork automatically.

The Problem

On SteamOS (Steam Deck), custom game images (capsules, heroes, logos, icons) live in the Steam userdata grid folder. These get set by tools like Steam ROM Manager, Heroic Launcher, or the Decky SteamGridDB plugin. Steam client updates frequently wipe this folder, destroying all custom artwork.

The Solution

sgm backs up and restores grid images, re-downloads from multiple art providers, auto-detects when images are wiped, and manages game libraries with Steam integration.

sgm backup                                   # snapshot all grid images
sgm restore                                  # restore after a Steam wipe
sgm refresh                                  # re-download ALL missing art (SRM + ROMs + shortcuts)
sgm refresh --system c64                     # re-scrape missing art for C64 only
sgm refresh --game "Contra"                  # re-scrape one specific game
sgm monitor install                          # auto-restore when images are wiped
sgm rom scan /path/to/Roms                   # scan game library
sgm rom import /path/to/Roms                 # create shortcuts + download artwork
sgm rom remove --system atari2600            # remove a system's shortcuts + art
sgm export create                            # portable bundle for another device

Quick Start

1. Install

On SteamOS (Steam Deck):

curl -fsSL https://raw.githubusercontent.com/fewtarius/SteamGridManager/main/install.sh | bash

Or manually:

git clone https://github.com/fewtarius/SteamGridManager.git ~/.local/share/sgm
cd ~/.local/share/sgm
pip install requests

2. Configure

sgm config init

This walks you through:

Finding your Steam installation (auto-detected on SteamOS)
Setting your SteamGridDB API key (free, see Getting API Keys)
Choosing a backup location

3. First Backup

sgm backup

4. Check Status

sgm status

Getting API Keys

sgm can download artwork from up to three providers. Each requires a free API key.

SteamGridDB (recommended)

SteamGridDB is the primary artwork source. Required for sgm refresh, recommended for sgm rom import.

Go to steamgriddb.com
Create a free account or sign in
Go to Profile > Preferences > API (direct link: https://www.steamgriddb.com/profile/preferences/api)
Generate an API key
Set it: sgm config set api_key YOUR_KEY_HERE

ScreenScraper (optional)

Good coverage for retro games. First provider checked in the cascade.

Go to screenscraper.fr
Create a free account
The ScreenScraper API requires developer credentials (devid/devpassword) tied to scraping apps. Most users won't need this - SteamGridDB alone has excellent coverage.

If you have dev credentials:

sgm config set screenscraper_devid YOUR_DEVID
sgm config set screenscraper_devpassword YOUR_DEVPASS
sgm config set screenscraper_ssid YOUR_USERNAME
sgm config set screenscraper_sspassword YOUR_PASSWORD

TheGamesDB (optional)

Community-driven database with good metadata.

Go to thegamesdb.net
Request a free API key
Set it: sgm config set thegamesdb_apikey YOUR_KEY_HERE

Cascade Order

When downloading artwork, sgm checks providers in this order:

ScreenScraper -> TheGamesDB -> SteamGridDB

If a provider doesn't have a particular art type, the next one is tried. This maximizes coverage for obscure titles.

For most users, just SteamGridDB is enough. It has the best coverage for Steam-friendly artwork sizes.

Commands

`sgm status`

Show current state: image counts by type, backup info, config status, monitor service.

sgm status

`sgm backup [--dry-run]`

Create a timestamped backup of all grid images and shortcuts.vdf.

sgm backup              # create backup
sgm backup --dry-run    # preview without backing up

Backups are stored in ~/.local/share/sgm/backups/<timestamp>/ and include all grid images, symlinks, and your shortcuts.vdf file for complete recovery.

`sgm restore [--list] [--timestamp TS] [--dry-run] [--force]`

Restore grid images from a backup snapshot.

sgm restore              # restore latest backup
sgm restore --list       # list available backups
sgm restore -t 20260316  # restore specific backup
sgm restore --dry-run    # preview without restoring
sgm restore --force      # skip confirmation prompt

`sgm refresh [OPTIONS]`

Re-download artwork for all game types in one pass: SRM-managed games, ROM shortcuts, and non-ROM shortcuts (Heroic, Wine, flatpaks). By default only missing art is downloaded.

sgm refresh                    # re-download all missing art (SRM + ROMs + shortcuts)
sgm refresh --all              # force re-download even if art already exists
sgm refresh --system c64       # only C64 ROMs
sgm refresh --game "Contra"    # only games whose name contains "Contra"
sgm refresh --type hero        # only hero banners, across all game types
sgm refresh --srm-only         # only SRM artworkCache entries (SteamGridDB only)
sgm refresh --shortcuts-only   # only non-ROM shortcuts (Heroic, Wine, flatpaks)
sgm refresh --roms-only        # only ROM shortcuts (all systems)
sgm refresh --dry-run          # preview what would be downloaded

Three art providers are tried in cascade order for each game: ScreenScraper → TheGamesDB → SteamGridDB. Each art type (tall/wide/hero/logo/icon) is filled independently — if ScreenScraper has box art but no icon, SteamGridDB fills in the icon.

Requires a SteamGridDB API key. ScreenScraper and TheGamesDB credentials are optional but recommended.

`sgm heroic [--no-art] [--dry-run]`

Import games from Heroic Games Launcher as Steam non-Steam shortcuts and download artwork.

sgm heroic               # import new Heroic games and download art
sgm heroic --no-art      # import shortcuts only, skip art download
sgm heroic --dry-run     # preview what would be imported

Reads Heroic's game library config (GOG/Epic/Amazon) and adds any games not already in Steam's shortcuts.vdf. Existing shortcuts are never overwritten.

`sgm config {init|show|set}`

Manage configuration.

sgm config init              # interactive setup wizard
sgm config show              # display current config
sgm config set api_key KEY   # set a value

`sgm monitor {install|uninstall|status|run}`

Manage the systemd service that auto-restores when Steam wipes grid images.

sgm monitor install     # install and start the service
sgm monitor status      # check service status
sgm monitor uninstall   # remove the service
sgm monitor run         # run a one-time check

Game Library Management

sgm can scan a game library, create Steam shortcuts, and download artwork. This gives your game collection a native Steam library experience.

Scan

sgm rom scan /path/to/Roms
sgm rom scan /path/to/Roms --system c64    # scan one system only

Import

sgm rom import /path/to/Roms               # all systems
sgm rom import /path/to/Roms --system c64   # one system
sgm rom import /path/to/Roms --dry-run      # preview only
sgm rom import /path/to/Roms --no-art       # skip artwork download

Import does the following:

Scans ROMs and cleans filenames into human-readable titles
Creates Steam shortcuts (won't duplicate existing entries)
Downloads artwork from configured providers
Saves images with correct Steam grid naming

Restart Steam after importing to see the new entries.

List Supported Systems

sgm rom systems

ROM Folder Layout

sgm expects ROMs organized by system folder name:

Roms/
+-- c64/
|   +-- Game Title (1984).d64
|   +-- Another Game.d64
+-- amiga/
|   +-- Game Title (USA).sfc
+-- genesis/
|   +-- Game Title (USA).md
+-- psx/
|   +-- Game Title (Disc 1).bin
|   +-- Game Title (Disc 1).cue
|   +-- Game Title (Disc 2).bin
+-- ...

Supported Systems

Folder	System	Manufacturer
`amiga`	Amiga	Commodore
`arcade`	Arcade	Various
`atari2600`	Atari 2600	Atari
`atari5200`	Atari 5200	Atari
`atari7800`	Atari 7800	Atari
`atarilynx`	Atari Lynx	Atari
`c64`	Commodore 64	Commodore
`coleco`	ColecoVision	Coleco
`dreamcast`	Dreamcast	Sega
`gamecube`	GameCube	Nintendo
`gamegear`	Game Gear	Sega
`gb`	Game Boy	Nintendo
`gba`	Game Boy Advance	Nintendo
`gbc`	Game Boy Color	Nintendo
`genesis`	Genesis / Mega Drive	Sega
`infocom`	Infocom / Z-Machine	Infocom
`intellivision`	Intellivision	Mattel
`mastersystem`	Master System	Sega
`n64`	Nintendo 64	Nintendo
`nds`	Nintendo DS	Nintendo
`neogeo`	Neo Geo	SNK
`nes`	NES	Compatible
`pc`	DOS	Microsoft
`ps2`	PlayStation 2	Sony
`psp`	PlayStation Portable	Sony
`psx`	PlayStation	Sony
`saturn`	Saturn	Sega
`snes`	Super Nintendo	Compatible
`vic20`	VIC-20	Commodore
`wii`	Wii	Nintendo
`wiiu`	Wii U	Nintendo
`xbox`	Xbox	Microsoft
`zmachine`	Z-Machine	Infocom

Title Cleaning

sgm cleans ROM filenames automatically:

Input	Output
`Game Title (USA).sfc`	Game Title
`Game Title (USA) (v1.01).iso`	Game Title
`Game v1.001 (2000)(Publisher)(NTSC)(US)[!]`	Game

ROM Artwork Tools

# Re-scrape missing artwork — recommended after 'rom import' if some art was missed
sgm refresh --system c64                              # retry all missing art for C64
sgm refresh --game "Contra"                           # retry one specific game
sgm refresh --roms-only                               # retry all ROM systems
sgm refresh --system c64 --all                       # force re-download even if art exists
sgm refresh --dry-run                                 # preview what would be scraped

# Low-level alias (same as sgm refresh --roms-only / --system):
sgm rom art scrape --system c64
sgm rom art scrape --game "Contra"

# Other artwork utilities
sgm rom art remap --backup /path/to/old-shortcuts.vdf  # migrate art from SRM IDs to SGM IDs
sgm rom art fix-mount --old-mount /media/deck           # update art after SD card path change
sgm rom art clear --system c64                          # remove art for a system

Artwork tips:

sgm refresh --dry-run shows every game with missing art before downloading
sgm refresh --game "partial name" is the fastest way to retry one game
Three providers cascade per art type: ScreenScraper -> TheGamesDB -> SteamGridDB
Each art type (tall/wide/hero/logo/icon) is filled independently — if ScreenScraper has box art but no icon, SteamGridDB fills in the icon

Remove a System

Remove all shortcuts and artwork for an entire system:

sgm rom remove --system atari2600             # interactive confirmation
sgm rom remove --system atari2600 --yes       # skip confirmation
sgm rom remove --system atari2600 --dry-run   # preview without changes

This removes:

All shortcuts for that system from shortcuts.vdf
All grid art files (tall, wide, hero, logo, icon) for those games
The Steam library collection for that system

Restart Steam after removing to see the changes.

Steam Collections

Rebuild Steam collections from current shortcuts (groups games by system tag):

sgm rom collections

Handles GoodTools, No-Intro, and Redump naming conventions. Multi-disc games are grouped automatically.

Portable Backup

Transfer your entire game library (images + shortcuts) between devices. Bundles include all grid images and a shortcuts.json for shortcut recreation.

Export

sgm export create                  # create bundle in default backup location
sgm export create -o /mnt/usb/     # export to USB drive
sgm export create -n my_backup     # custom bundle name
sgm export list                    # list available bundles

Import on Another Device

sgm import /path/to/bundle         # merge with existing (default)
sgm import /path/to/bundle --missing  # only fill in missing art types
sgm import /path/to/bundle --replace  # overwrite all existing
sgm import /path/to/bundle --with-shortcuts  # also recreate shortcut entries
sgm import /path/to/bundle --dry-run  # preview only

Configuration

Config file: ~/.config/sgm/config.json

Key	Default	Description
`api_key`	(empty)	SteamGridDB API key
`steam_path`	auto-detected	Steam installation path
`steam_user_id`	auto-detected	Steam user ID
`backup_path`	`~/.local/share/sgm/backups`	Backup storage
`srm_artwork_cache`	auto-detected	SRM artworkCache.json path
`auto_restore`	`true`	Auto-restore when wiped
`auto_restore_threshold`	`0.5`	Trigger when file count drops below 50%
`batch_size`	`50`	Downloads per batch
`log_level`	`info`	Log verbosity (debug, info, warning, error)
`screenscraper_devid`	(empty)	ScreenScraper developer ID
`screenscraper_devpassword`	(empty)	ScreenScraper developer password
`screenscraper_ssid`	(empty)	ScreenScraper username (ssid)
`screenscraper_sspassword`	(empty)	ScreenScraper password
`thegamesdb_apikey`	(empty)	TheGamesDB API key

Don't share your config file - it contains your API keys.

How It Works

Artwork Protection

Backup copies all grid images (including symlinks) to a timestamped snapshot
Restore copies files back and recreates symlinks from the saved map
Refresh uses SRM's artworkCache.json to map app IDs to SteamGridDB game IDs, then downloads matching artwork
Monitor checks the grid folder periodically via systemd and auto-restores if file count drops significantly

ROM Import

Scans ROM folder tree, matching subfolder names to known systems
Strips metadata (region, version, dump info) from filenames
Generates Steam shortcut IDs using the same CRC32 algorithm as Steam ROM Manager
Writes entries to Steam's shortcuts.vdf (non-destructive)
Cascades through art providers to find artwork for each game

Grid Image Types

Type	Filename	Size	Location in Steam
Tall capsule	`{id}p.png`	600x900	Library grid
Wide capsule	`{id}.png`	920x430	Shelf/carousel
Hero	`{id}_hero.png`	1920x620	Game detail banner
Logo	`{id}_logo.png`	~400x230	Overlay on hero
Icon	`{id}_icon.png`	256x256	Taskbar, friends

Requirements

Python 3.10+
requests (pip install requests)
SteamOS or Linux with Steam installed
SteamGridDB API key (free) for artwork features
(optional) Steam ROM Manager for refresh mappings
(optional) ScreenScraper / TheGamesDB keys for more ROM art coverage

Security

API keys are stored locally in ~/.config/sgm/config.json
Keys are only sent to their respective API endpoints
No keys are hardcoded in the source
Don't commit or share your config file
Use --dry-run on any command to preview before making changes

License

GPLv3. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.clio		.clio
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
art_scraper.py		art_scraper.py
backup.py		backup.py
config.py		config.py
heroic.py		heroic.py
install.sh		install.sh
monitor.py		monitor.py
portable.py		portable.py
refresh.py		refresh.py
requirements.txt		requirements.txt
rom_scanner.py		rom_scanner.py
sgm		sgm
sgm.py		sgm.py
shortcuts.py		shortcuts.py
steam.py		steam.py
systems.py		systems.py

Folders and files

Latest commit

History

Repository files navigation

SteamGrid Manager (sgm)

The Problem

The Solution

Quick Start

1. Install

2. Configure

3. First Backup

4. Check Status

Getting API Keys

SteamGridDB (recommended)

ScreenScraper (optional)

TheGamesDB (optional)

Cascade Order

Commands

sgm status

sgm backup [--dry-run]

sgm restore [--list] [--timestamp TS] [--dry-run] [--force]

sgm refresh [OPTIONS]

sgm heroic [--no-art] [--dry-run]

sgm config {init|show|set}

sgm monitor {install|uninstall|status|run}

Game Library Management

Scan

Import

List Supported Systems

ROM Folder Layout

Supported Systems

Title Cleaning

ROM Artwork Tools

Remove a System

Steam Collections

Portable Backup

Export

Import on Another Device

Configuration

How It Works

Artwork Protection

ROM Import

Grid Image Types

Requirements

Security

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`sgm status`

`sgm backup [--dry-run]`

`sgm restore [--list] [--timestamp TS] [--dry-run] [--force]`

`sgm refresh [OPTIONS]`

`sgm heroic [--no-art] [--dry-run]`

`sgm config {init|show|set}`

`sgm monitor {install|uninstall|status|run}`

Packages