---
name: deck-sgdb
description: Batch-download SteamGridDB artwork (hero, wide capsule, portrait/poster) for RomM-synced shortcuts on the Steam Deck. Use when the user asks to update, download, or clean up Steam library artwork for their ROM games.
---

# deck-sgdb

Batch artwork tool for the Steam Deck's RomM-synced game library. Fetches hero, wide capsule, and portrait (poster) images from SteamGridDB for every shortcut added by decky-romm-sync.

## Scripts

| File | Where it runs | Purpose |
|---|---|---|
| `scripts/deck-sgdb-art.py` | On the Deck | Core logic — parse shortcuts.vdf, search SGDB, download images |
| `scripts/deck-sgdb-art.ps1` | Windows (this machine) | Upload + run wrapper; handles SSH ASKPASS |

## Invocation

```powershell
# Full pass — all three art types for anything missing
.\scripts\deck-sgdb-art.ps1

# Specific types only
.\scripts\deck-sgdb-art.ps1 --types hero,wide
.\scripts\deck-sgdb-art.ps1 --types poster

# Preview without downloading
.\scripts\deck-sgdb-art.ps1 --dry-run

# Remove portrait + wide art for ROM hacks whose names still have file
# extensions (.gba, .nds, etc.) — these got fuzzy fallback matches and the
# art is more confusing than helpful
.\scripts\deck-sgdb-art.ps1 --clean
```

## Prerequisites

- **sshd on the Deck**: `sudo systemctl start sshd` in Desktop Mode (off by default on SteamOS)
- **SSH password**: in Obsidian vault → `Homelab/ROM Library.md` → Access (SSH) section
- **SGDB API key**: `25431ca935008934cae436d78e9d451c` (hardcoded in script; also in vault)
- **Deck connection**: Tailscale IP `100.96.86.40` (default) or LAN `192.168.1.132`

## What the script does

1. Parses `~/.local/share/Steam/userdata/43872485/config/shortcuts.vdf` on the Deck
2. Filters to shortcuts whose `Exe` path contains `rom-launcher` (all decky-romm-sync games)
3. For each game missing the requested art type, searches SGDB by game name
4. Downloads the first result and saves to the Steam grid directory

## Steam grid file naming

| Type | Filename | SGDB dimensions |
|---|---|---|
| Wide capsule | `<appid>.png` | 460x215, 920x430 |
| Portrait / poster | `<appid>p.png` | 600x900, 342x482, 660x930 |
| Hero / background | `<appid>_hero.png` | 1920x620 |

`appid` is derived from the VDF raw value: `(raw_appid & 0xffffffff) | 0x80000000`

## Known gotchas

- **Cloudflare blocks urllib's default UA** — the script uses a Chrome UA for all SGDB requests; don't remove it
- **ROM hack names get fuzzy matches** — hacks with no SGDB entry fall back to the closest game (e.g. "Pokemon Emerald Azure" → Pokémon Emerald). Run `--clean` after a bulk pass to strip art from games whose names still contain a file extension, which is the reliable signal that igir didn't find a clean title match
- **`decky-steamgriddb` plugin is frontend-only** — the installed Decky plugin has no batch mode; it's UI-driven per game. The Python script here is the only way to bulk-update
- **vdf module** lives at `~/homebrew/plugins/decky-steamgriddb/py_modules` — the script loads it from there; no install needed
- **sshd is off by default** on SteamOS — must be started manually each session unless the user has added it to a startup script
- **Steam user ID** for shortcuts and grid is `43872485`. The `22396545` userdata dir also exists but has no `shortcuts.vdf`