A free utility for updating openFPGA cores, firmware, and related assets on your Analogue Pocket. It can run as an interactive console menu or from the command line.

A browsable list of available cores is here: openFPGA cores inventory.

Please use the latest release before reporting issues; older builds are not supported.

---

Easy mode

Do not clone the repo if you only want to run the tool. Download the latest release, unzip it, place the executable for your OS on the root of your SD card (or another folder you use as the install path), and run it.

Use Settings from the main menu to walk through toggles, or edit pupdate_settings.json for advanced options. In the full-screen UI (--tui) the same options live on the Settings tab, grouped — see Settings.

macOS specific

In most macOS default installation setups, you will likely encounter issues running the script the "easy way". The following command will remove the quarantine from the pupdate script only. ⚠️ Use sparingly ⚠️

xattr -d com.apple.quarantine /path/to/pupdate

---

Interactive menu

The full menu tree is documented in MENU.md.

---

What Pupdate does (overview)

---

RTFM (quick links)

Update All · Update Firmware · Select Cores · Download Assets · Backup Saves & Memories · Pocket Setup · Pocket Maintenance · Pocket Extras · Plugins · Pin / unpin core version · Settings · Additional settings · Asset archives · CLI · Jotego beta · Analogizer · Troubleshooting · Developers

Update All

The “do everything” option. Steps marked with * follow your Settings toggles.

1. Check for firmware updates *
2. Compress and backup Saves and Memories *
3. Install/update every selected core
4. Download missing required assets for selected cores *
5. Remove cores you have not selected (when that option is enabled) *
6. Run the instance JSON builder for supported cores (e.g. PC Engine CD) when enabled *
7. Rename Jotego cores to friendly titles when enabled *

Pinned versions: If a core has pinned_version set in settings, the updater resolves that version from the inventory release list only. If the pin does not match any listed release, that core is skipped with a message and the run continues.

Update Selected

(Pocket Maintenance) — Pick installed cores to update.

Install Selected

(Pocket Maintenance) — Pick cores you do not have installed yet; installs them without running a full Update All.

Update Firmware

Checks for Pocket firmware updates only, then exits.

Select Cores

Asks how new cores should be handled:

• Yes — All current cores selected; new cores auto-install as they appear.
• No — New cores are not installed automatically; you are not prompted. You then choose from the full list which cores to manage.
• Ask — Each run can prompt for new cores; you still choose from the full list for your baseline.

Download Assets

Fetches missing assets (ROMs, BIOS, etc.) for selected cores from your configured archives.

You supply your own ROMs for non-arcade cores where the archive does not provide them.

Backup Saves & Memories

Zips the Pocket Saves and Memories folders to the path in settings (default: Backups next to the executable unless overridden).

---

Pocket Setup

Display modes

• Enable Recommended Display Modes — Applies the curated list from display_modes.json to the cores that reference those modes.
• Enable Selected Display Modes — You pick modes from the full list; they are applied to all installed cores that support them.
• Enable Selected Display Modes for Selected Cores — Same picker, then you choose which installed cores receive them.
• Reset All / Selected Customized Display Modes — Restore core defaults.
• Change Display Modes Option Setting — Merge (combine with core defaults), Overwrite (replace), or Ask each time.

To override the hosted display_modes.json, place a copy next to the executable and set use_local_display_modes to true.

Download Platform Image Packs

Lists image packs (from image_packs.json), downloads and extracts to Platforms/_images.

Download Pocket Library Images

• Spiritualized1997 (GB, GBC, GBA, GG) — hardcoded in the app: Library_Image_Set_v1.0.zip from your configured archive.
• All other submenu titles and items come from pocket_library_images.json (bundled next to the executable), same idea as Pocket Extras. Each group has a menu_title (submenu label) and entries with menu_label, id, github_user, github_repository, and sources: an array of release_asset (zip on the release), path_under_extract (folder path inside that zip to .bin files, /-separated), and dest_images_subfolder (under System/Library/Images/ on the device). Optional post_install_note is printed after a successful install (when any files were copied). Enable Use a local pocket_library_images.json file in Settings to read only the local copy instead of fetching the catalog from GitHub (see use_local_pocket_library_images in pupdate_settings.json).

CLI (like pocket-extras): pocket-library-images alone installs Spiritualized. pocket-library-images -l lists catalog entry id values; -n <id> installs that entry; -n <id> -i prints details. Example: pocket-library-images -n codewario_boxarts.

Download GameBoy Palettes

Downloads palette packs maintained by davewongillies and others (see original palette credits in prior releases); large collection of official and community palettes.

Generating instance JSON files (PC Engine CD)

• Supported workflow is centered on PC Engine CD; put games under /Assets/{platform}/common, one game per folder (full game title as folder name).
• Games should be cue/bin. The generated JSON uses the cue file name as the base name—name the cue with the full title too.
• Update All or Generate Instance JSON Files walks common and builds launch JSONs.
• Disable in Update All with build_instance_jsons: false in settings.
• Optional: local ignore_instance.json with use_local_ignore_instance_json if you maintain exclusions.

Generate Game & Watch ROMs

Create:

• /Assets/gameandwatch/agg23.GameAndWatch/artwork
• /Assets/gameandwatch/agg23.GameAndWatch/roms

Put [game].zip in each; run the menu item to build. Game & Watch asset downloads are configured under archives (core-specific archive for agg23.GameAndWatch)—enable/configure there rather than a separate global toggle.

Super GameBoy aspect ratio

Apply 8:7 to chosen Spiritualized.SuperGB* cores, or restore 4:3.

Analogizer Config

Jotego vs Standard wizards for Analogizer JSON. See Analogizer setup.

Patreon Config

Submenu under Pocket Setup.

• Set Patreon Session Cookie (for JT Beta auto-fetch) — Stores your browser session_id cookie for experimental Patreon-based jtbeta.zip auto-fetch. See Jotego beta for full steps and caveats.
• Test Patreon Session Cookie — Verifies the cookie and whether the account is a Jotego patron (diagnostic only).

Directory Locations

Submenu under Pocket Setup.

• Set Backup Saves Location — Folder where Backup Saves & Memories writes zip files. Default Backups is a relative path (resolved from the process current directory when the tool runs; use an absolute path if you need a fixed location). Clearing the value when prompted resets to Backups. Same as config.backup_saves_location in JSON.
• Set Archive Cache Location — When Cache downloaded archive files locally is enabled, this overrides the default cache folder under your user LocalApplicationData pupdate\cache (Windows) / equivalent. Leave empty (or save an empty line) to use that default. Same as config.archive_cache_location.
• Set Temp Directory — Where pupdate extracts downloads and temporary files. Empty means the OS temp folder (Path.GetTempPath()). Same as config.temp_directory.

Set GitHub Token

Stores a personal access token for GitHub API calls (higher rate limits than anonymous requests). The current value is shown when you open this item. You can also set config.github_token in pupdate_settings.json.

Print openFPGA Category Structure

Prints a summary of platform categories and cores (debug / reference).

---

Pocket Maintenance

• Update Selected / Install Selected — See above.
• Reinstall All / Select Cores — Clean reinstall of core files (ROMs and saves are not removed).
• Uninstall Select Cores — Optional removal of core-specific Assets; ROMs/saves untouched.
• Manage ROM Set Archives — Sync and manage ROM set definitions (romsets.json).
• Prune Save States — Trims old save states under Memories.
• Clear Archive Cache — Deletes cached archive downloads when cache archive files is enabled.
• Pin/Unpin Core Version — See next section.

---

Pin / unpin core version

For installed cores with a GitHub-backed inventory entry:

1. Choose Unpin, Select from releases list, Enter version manually, or Go Back.
2. Select from releases list opens a paginated list of versions from the inventory (newest-first by release date). Pick one to pin.
3. Enter version manually stores any string; it must match a metadata.version value in the inventory’s releases array for updates to succeed.

Update behavior: The pinned ZIP URL is taken only from the inventory release that matches the pin (with simple v prefix normalization). There is no GitHub API fallback for pins. If the pin is missing from releases, the core is skipped for that run with a clear message.

---

Pocket Extras

Third-party bundles defined in pocket_extras.json. Each entry can show a description and links before install (show_menu_descriptions in settings); the --tui Extras tab shows them in an Install / Cancel dialog.

• Additional Assets — Needs the base core; extends ROMs or multi-game support.
• Combination Platforms — Multiple cores under one platform entry.
• Variant Cores — Alternate core packages alongside the original.

Exact menu labels are built at runtime; see MENU.md for a current snapshot.

---

Plugins

Pupdate can install and run plugins distributed as GitHub repos. Each plugin is a small program that can drive its own interactive flow inside pupdate. To install ROM packs, configure something on your Pocket, fetch external content, etc.

Installing a plugin

Pocket Extras → Plugins → Install from GitHub... and paste either:

• a short slug like owner/repo, or
• a full URL like https://github.com/owner/repo

pupdate downloads the latest release of that repo. Example to try: openfpga-library/pocket-plugin.

Running a plugin

After installing, the plugin appears in the same Pocket Extras → Plugins menu by its name. Select it and follow its prompts. Pick Cancel at any prompt to stop the plugin.

Updating and uninstalling

• Check for updates - checks every installed plugin against its source repo and offers to update any that have a newer release.
• Uninstall a plugin... - pick one from the list and confirm.

Creating a plugin

See openfpga-library/pocket-plugin for the plugin contract, sample code, and release format. Distribute your plugin as a GitHub release that includes plugin.wasm and plugin.json as release assets. The release tag becomes the version pupdate uses for update checks.

---

Settings

In the full-screen UI (--tui), ↑/↓ stay inside the current list, ←/→ switch tabs, and A–G jump straight to one. Those single-key shortcuts stand down while a text box has focus, so the Cores tab's Filter box takes every key - press / from the core table to jump into it and Esc to clear it.

Toggles exposed in the Settings menu (stored in pupdate_settings.json):

Game & Watch (and other core-specific archives) are enabled in the archives array in JSON, not via a separate Settings row.

---

Additional settings

Edit pupdate_settings.json for keys that are not bool menu toggles:

Asset blacklist

blacklist.json lists filenames not downloaded as assets. Entries support * and ? wildcards; matching applies to the full slot path and to the file name alone (useful for paths like subfolder/game.bin).

AI generated core filter (Experimental)

pupdate can mark or filter out cores that appear to be AI-generated, using the openFPGA AI check report built by neil-morrison44. Each core is given a score from 0 to 1. The closer to 1, the more likely it is to be AI generated.

How the score is calculated: An automated tool (openfpga-library/openfpga-ai-check) regularly looks through each core's public development history for signs that AI tools were used. For example, how often "co-authored by Claude" appears in commit messages. The more signs detected, the higher the score. A core that looks entirely AI made scores near 1, one that only had occasional AI help scores lower. Older cores from before AI tools were common are given a 0. Keep in mind this is an educated guess and it can be inaccurate. Core devs will be able to submit requests to fix incorrect detections. Use at your own risk (the risk really just being you will have some cores hidden from you with false positives)

• Set the cutoff with Settings → Set AI Filter Threshold (Settings → Core Filtering → AI score threshold in --tui) - a percentage (0–100, defaults to 100). Cores that score over the threshold are labeled or hidden. Example: a threshold of 50 targets cores scoring above 0.50.
• Filter off (default): over-threshold cores are left in place but marked as (AI) on the Select Cores screen, so you can spot them and manually deselect the ones you don't want.
• Filter on (turn on Hide and uninstall AI-generated cores (Experimental) in the Settings menu): over threshold cores are removed from Select Cores, updates, and asset downloads, and any that are already installed are uninstalled during the next Update All.
• Cores that aren't scored at all are never marked or hidden. Set the threshold to 100 to turn everything off (nothing scores above 1.0), including the labels.
• In the full-screen UI (--tui), the Cores tab's details popup (Enter, or click [view]) shows the full report for that core: its score against your threshold, each individual check with the evidence it recorded (e.g. "Of the last 100 commit messages 97 mention Claude"), and when it was last analyzed. Cores missing from the report show as not scored.

---

Asset source archives

The archives array in pupdate_settings.json defines where assets come from. Stock config includes a default archive.org archive and a Retrodriven custom archive; you can switch via Use custom archive or edit JSON.

Types

• internet_archive — name, archive_name (archive.org identifier).
• custom_archive — name, url, index (index format per archive.org JSON API).
• core_specific_archive — Same as internet_archive but scoped to one core name; optional file_extensions or files (not both); optional one_time.
• core_specific_custom_archive — Like core-specific but with url + index.

Example core_specific_archive:

{
    "name": "Spiritualized.2600",
    "type": "core_specific_archive",
    "archive_name": "htgdb-gamepacks",
    "files": [
      "@Atari 2600 2021-04-06.zip"
    ],
    "enabled": true,
    "one_time": true
}

---

Internet Archive credentials

Some items need login. Add to pupdate_settings.json:

"credentials": {
  "internet_archive": {
    "username": "me@something.com",
    "password": "12345"
  }
}

---

CLI commands and parameters

  menu                     Interactive main menu (default)
    -p, --path                Absolute path to Pocket install / SD root
    -s, --skip-update         Open menu without checking for pupdate self-update

  fund                     List sponsor / funding links
    -p, --path
    -c, --core                Optional core id filter

  update                   Run Update All (respects settings)
    -p, --path
    -c, --core                Optional single core id
    -r, --clean               Clean reinstall cores
    -u, --updated-assets-only Only check/download assets for cores updated this run
    -y, --yes                 Non-interactive: assume defaults for all prompts (CI/cron)

  uninstall                Remove a core
    -p, --path
    -c, --core                Required
    -a, --assets              Also remove Assets/{platform}/{core}

  assets                   Download assets only
    -p, --path
    -c, --core                Optional core id

  firmware                 Check firmware
    -p, --path

  images                   Download a platform image pack
    -p, --path
    -o, --owner               Repo owner
    -i, --imagepack           Repo name
    -v, --variant             Optional variant

  instance-generator       Run instance JSON generation (PC Engine CD workflow)
    -p, --path

  backup-saves             Backup Saves & Memories
    -p, --path
    -l, --location            Backup folder (required)
    -s, --save                Persist location in config for Update All

  gameboy-palettes         Download Game Boy palette pack
    -p, --path

  pocket-library-images    Download Pocket library images
    -p, --path
    -n, --name                Catalog entry id (omit for Spiritualized archive)
    -i, --info                Show details for -n
    -l, --list                List catalog ids (Spiritualized = no -n)

  pocket-extras            Install a Pocket Extra by id
    -p, --path
    -n, --name                Extra id (required for install)
    -i, --info                Show details for name
    -l, --list                List all extras

  display-modes            Apply **recommended** display modes (same as curated menu action)
    -p, --path

  prune-memories           Prune old save states (Memories)
    -p, --path
    -c, --core                Optional core id

  analogizer-setup         Run Analogizer setup wizard
    -p, --path
    -j, --jotego              Jotego-specific wizard

  clear-archive-cache      Clear cached archive downloads (same as Pocket Maintenance → Clear Archive Cache)
    -p, --path
    -y, --yes                Required confirmation flag

  validate-cores           Check installed cores for missing or invalid JSON
    -p, --path
    -f, --fix                Reinstall (clean) any cores with missing or invalid JSON

  update-self              Check for pupdate updates

  help                     Help for a verb

  version                  Print version

Non-interactive use (-y / --yes): a global flag. With it, pupdate assumes the default/affirmative answer to every prompt (install new cores, display modes, etc.) and skips the self-update prompt, so it can run unattended (CI, cron, containers). pupdate also returns a non-zero exit code when an update fails or an unhandled error occurs, so scripts can detect failures.

Examples

pupdate -p /path/to/sdcard/
pupdate update -c boogermann.bankpanic
pupdate update -p /path/to/sdcard/ --yes      # unattended; non-zero exit on failure
pupdate assets -c jotego.jtcontra
pupdate images -i pocket-platform-images -o dyreschlock -v home
pupdate validate-cores
pupdate validate-cores --fix

---

Jotego beta cores

Place jtbeta.zip from Patreon on the root of the SD card (exact name). Update All copies the beta key into the folders that need it. Do not rename the file.

Auto-fetching jtbeta.zip (optional)

Pupdate can download the latest jtbeta.zip for you. Manual placement (putting jtbeta.zip on the SD root yourself) always wins — auto-fetch only runs when no manual key is present. Two optional sources are supported; if both are enabled, GitHub is tried first and Patreon is the fallback.

Option A — GitHub (recommended):

Jotego distributes jtbeta.zip via a private GitHub repo (JTFPGA/jtbeta). Per Jotego's own Beta Files FAQ, access is granted to GitHub Sponsors of Jotego — and since Jotego's GitHub Sponsors page accepts Patreon as a payment route, existing Patreon patrons can get the same sponsor status (and therefore the repo invite) by linking their Patreon to their GitHub account.

1. Make sure you have an active paid Jotego subscription. Either:
   • Subscribe directly on Jotego's GitHub Sponsors page, or
   • If you're already a Patreon patron, link your Patreon account to GitHub so GitHub recognizes your Patreon subscription as a sponsorship.
2. Accept the invite to JTFPGA/jtbeta once it arrives.
3. Create a GitHub Personal Access Token with read access to private repos (classic PAT with repo scope, or a fine-grained PAT with Contents: Read on JTFPGA/jtbeta).
4. Set github_token in pupdate_settings.json to that PAT.
5. Enable Auto-fetch Jotego jtbeta.zip from GitHub in the Settings menu (Settings → Accounts in --tui).

Option B — Patreon session cookie (experimental, fallback):

Experimental and flaky. This uses Patreon's undocumented frontend API with your browser session cookie, not a supported public API. Cookies expire (usually in weeks, sooner if you log out or clear cookies), and Patreon can change response field names without notice. Prefer Option A if you have any way to. Treat this as a best-effort fallback, not a stable integration.

pupdate will never use your Patreon session cookie for anything other than making HTTP requests to patreon.com to locate and download jtbeta.zip (and, if you run the diagnostic, to verify your login and Jotego membership). It's stored locally in pupdate_settings.json and is never sent to any third party, telemetry endpoint, or server that isn't patreon.com.

1. Open https://www.patreon.com in your browser and log in.
2. Open DevTools (F12 or ⌘⌥I) → Application (Chrome/Edge/Brave) or Storage (Firefox) → Cookies → https://www.patreon.com.
3. Copy the value of the session_id cookie.
4. In pupdate: Pocket Setup → Patreon Config → Set Patreon Session Cookie (Settings → Accounts → Patreon session cookie in --tui), paste the value.
5. Enable Auto-fetch Jotego jtbeta.zip from Patreon in the Settings menu (Settings → Accounts in --tui).

Use Pocket Setup → Patreon Config → Test Patreon Session Cookie (Settings → Accounts → Test Patreon session cookie in --tui) to verify the cookie works and whether your account is currently a Jotego patron.

Notes:

• Your subscription/access must actually grant beta privileges — pupdate will tell you if it doesn't.
• Auto-fetch failures never break an update run; you can always fall back to placing jtbeta.zip on the SD root manually.

---

Analogizer setup

Pocket Setup → Analogizer Config — choose Standard (RndMnkIII) or Jotego flow. For problems with generated files, ask the core author. Supported cores.

---

Troubleshooting

• Slow assets — Try Use custom archive or another archive entry in archives.
• Error in framework RS: bridge not responding — Run pupdate on a local disk, then copy results to the SD card.
• Missing ROM ID [1] in _alternatives — Turn off “Skip alternative ROMs” if you need those files installed.
• Pinned core skipped — Pin must match a version string present in the core’s inventory releases list.
• GitHub API rate limit — Add a token via Pocket Setup → Set GitHub Token or config.github_token in pupdate_settings.json.
• Failure processing application bundle / Default extraction directory ... is not accessible — Happens when running in a container (or any environment) where $HOME points to a directory that does not exist or is not writable. Either set DOTNET_BUNDLE_EXTRACT_BASE_DIR (or HOME) to a writable path, or download pupdate_linux_container*.zip from the release instead of pupdate_linux*.zip. The container variant places the native libs next to the binary so no runtime extraction is needed. Extract the whole archive and run pupdate from there.

---

Developers

• .NET — dotnet restore, dotnet build, dotnet run --project pupdate.csproj -- [verb] [options].
• Layout — src/Program.cs, src/partials/, src/services/, src/models/, src/options/, src/tui/ (the --tui interface).

---

Submitting new cores

openfpga-cores-inventory / analogue-pocket

---

Credits

Thanks to neil-morrison44 — this project builds on his original script.

With special thanks to
Michael Hallett · RetroDriven · dyreschlock · espiox

---

Other updaters

• Pocket_Updater (GUI, more features)
• pocket-sync (cross-platform)