Everything Coverly ROMs does.
Covers first, which is what it was made for; then everything that has grown around them. Each section can be seen drawn or in the real app.
This page describes version 0.5.2. The «since 0.5» tags mark what arrived in it.
Covers and art
It opens the card, shows which games have no cover and adds them, with a dry run first and undo after.
- libretro-thumbnails
- SteamGridDB
- The game itself
In the app

The library counts what is missing.

Fill shows the plan before it writes.

Each doubtful match says why it was picked.

A job running, with its report and undo.

In the game panel, the cover is changed by hand.

The audit, system by system.
- Audit Counts, per system, which games lack a cover, screenshot or title screen. Read-only, and exports to CSV or JSON from Reports.
- Fingerprint identification CRC32, MD5 or SHA1 against libretro-database, or else the name. Arcade short names through the MAME and FBNeo DATs.
- Which image it picks The one for the ROM's region (the default), the one from your source order or the most voted on SteamGridDB.
- Dry run The wizard shows the whole plan before writing: nothing has been written yet.
- Review queue Doubtful matches wait in a queue you walk with the keyboard, and each says why it was picked.
- Jobs with undo They pause, resume, cancel and undo. Backups and logs go to the app's data folder, not to the card.
- Leaves your art alone It does not replace an image you already have unless you ask, and then it keeps a copy first.
- Change it by hand In the game panel, the cover, screenshot and title screen open a workspace: candidates, title search, from a file or remove.
- Clean images They are re-encoded, so they carry no metadata, and written one at a time.
- gamelist.xml In the Batocera, Knulli and EmulationStation layout it updates it, and Undo puts it back as it was.
- Art sources libretro-thumbnails, no account, and SteamGridDB, only with your own key, kept in the system keychain.
- The game's own cover If no source has one, it uses the icon the game carries on PS3, PS Vita, Wii U, 3DS and Xbox 360. On PS4, PS5, Xbox One and Xbox Series it tries that first.
- Names RetroArch finds Titles with “&” or “:” are saved the way RetroArch looks for them.
- Pace and time left While it fills, you see covers per minute and what's left.
Writes where your handheld looks
Detects your firmware or frontend and saves each image in the folder and under the name it expects.
- Anbernic stock
Imgs/ - ES-DE
downloaded_media/…/ covers/ - RetroArch
thumbnails/…/ Named_Boxarts/
In the app

A custom profile, with its path template.

On open, the card or the folder.
- Eight layouts, detected Anbernic stock, GarlicOS, Onion OS, MinUI and NextUI, muOS, ES-DE, Batocera, Knulli and EmulationStation, and RetroArch.
- Your own layout For other firmware, path templates with a live preview, in Settings → Profiles.
- Names the card accepts File names that work on FAT and exFAT, and it never writes outside the folder you opened.
- Each system's folder Each built-in layout knows which folder it uses for every system.
| Layout | Cover | Screenshot | Title |
|---|---|---|---|
| Anbernic stock | |||
| GarlicOS | |||
| Onion OS | |||
| MinUI and NextUI | |||
| muOS | |||
| ES-DE | |||
| Batocera, Knulli and EmulationStation | |||
| RetroArch | |||
| Your own profile, with a preview of the path | Whichever you choose | ||
On Batocera, Knulli and EmulationStation it also updates gamelist.xml, with undo.
133 systems, each with its icon
From the Atari 2600 to the PS5, each system with its folder and its icon: the RetroArch Assets silhouette or, where there is no neutral one, its short label.
Coverly is not affiliated with or endorsed by Nintendo, Sony, Microsoft, Sega or any other maker. System names are trademarks of their owners, used here only to say what it works with. System icons adapted from RetroArch Assets (XMB Monochrome theme), © libretro contributors, CC BY 4.0. Changes: recoloured, optimised and cropped.
In the app

Every system, with its icon, in the sidebar and on each shelf.

PC arcade in Shelves: Cave CV1000 and Taito Type X, which says it runs only on PC.
- An icon for every system The RetroArch Assets silhouette (CC BY 4.0) or, where there is no neutral one, a plate with its short label. In the sidebar, the filters, the game panel and the reports.
- 133 systems Consoles 50, handhelds 20, computers 27, arcade 17 and engines and ports 19. These are the ones it recognises: not every layout has a folder for each, and Xbox Series is catalogued only.
- PC arcade Taito Type X: each folder inside
type-x/is one game, recognised only by where it is, with nothing inside opened. It runs only on PC, not on ARM handhelds, and only the ES-DE layout has its folder. Cave CV1000 goes in Batocera and Knulli'scave3rd/folder. since 0.5
See every system
Consoles 50
Nintendo 10
- Nintendo Entertainment System
- Famicom Disk System
- Nintendo 64
- Super Nintendo
- Nintendo 64DD
- Nintendo Satellaview
- Nintendo GameCube
- Nintendo Wii
- Nintendo Wii U
- Nintendo Switch
Sega 8
- Sega Dreamcast
- Sega Mega Drive / Genesis
- Sega CD / Mega-CD
- Sega Saturn
- Sega 32X
- Sega Master System
- Sega SG-1000 / SC-3000
- Sega Pico
Atari 5
- Atari 2600
- Atari 5200
- Atari 7800
- Atari Jaguar CD
- Atari Jaguar
Sony 5
- Sony PlayStation
- Sony PlayStation 2
- Sony PlayStation 3
- Sony PlayStation 4
- Sony PlayStation 5
NEC 4
- PC Engine / TurboGrafx-16
- PC Engine CD / TurboGrafx-CD
- NEC PC-FX
- PC Engine SuperGrafx
Microsoft 4
- Microsoft Xbox
- Microsoft Xbox 360
- Microsoft Xbox One
- Microsoft Xbox Series X|S
Commodore 2
- Commodore Amiga CD32
- Commodore CDTV
Other makers 12
- Neo Geo CD
- 3DO Interactive Multiplayer
- Philips CD-i
- ColecoVision
- Mattel Intellivision
- GCE Vectrex
- Magnavox Odyssey² / Videopac
- Fairchild Channel F
- Emerson Arcadia 2001
- Epoch Super Cassette Vision
- Bandai Sufami Turbo
- Uzebox
Handhelds 20
Nintendo 8
- Game Boy
- Game Boy Advance
- Game Boy Color
- Game & Watch
- Nintendo DS
- Pokemon Mini
- Virtual Boy
- Nintendo 3DS
SNK 2
- Neo Geo Pocket
- Neo Geo Pocket Color
Sony 2
- Sony PSP
- Sony PlayStation Vita
Bandai 2
- WonderSwan
- WonderSwan Color
Other makers 6
- Sega Game Gear
- Atari Lynx
- Watara Supervision
- Tiger Game.com
- Mega Duck / Cougar Boy
- Arduboy
Computers 27
Commodore 6
- Commodore Amiga
- Commodore 64
- Commodore VIC-20
- Commodore Plus/4
- Commodore PET
- Commodore 128
Atari 3
- Atari 8-bit
- Atari ST
- Atari XE / XEGS
MSX 3
- MSX
- MSX2
- MSX turbo R
Sinclair 2
- Sinclair ZX Spectrum
- Sinclair ZX81
Sharp 2
- Sharp X68000
- Sharp X1
NEC 2
- NEC PC-98
- NEC PC-88
Other makers 9
- DOS
- Fujitsu FM Towns
- Amstrad CPC
- Acorn BBC Micro
- Thomson MO/TO
- Dragon 32/64
- Tandy TRS-80 Color Computer
- Texas Instruments TI-99/4A
- Apple II
Arcade 17
- Arcade (various)
- Atomiswave
- Capcom Play System
- Capcom Play System II
- Capcom Play System III
- Cave CV1000
- FinalBurn Neo
- HBMAME
- IGS PGM2
- MAME
- Namco Sega Nintendo Triforce
- Neo Geo
- Sega Model 2
- Sega Model 3
- Sega NAOMI
- Sega NAOMI 2
- Taito Type X
Engines, ports and fantasy consoles 19
- Cave Story (NXEngine)
- Dinothawr
- Doom (PrBoom)
- EasyRPG
- Flashback (REminiscence)
- LowRes NX
- Lutro
- Mr. Boom
- ONScripter
- OpenBOR
- PICO-8
- Quake
- Rick Dangerous (XRick)
- ScummVM
- Solarus
- TIC-80
- Vircon32
- WASM-4
- Wolfenstein 3D (ECWolf)
No system goes by that name. Try the console’s name or its folder (gba, snes…).
Your library, six ways
Six views to see what you have and what is missing, with one keyboard. Updates, DLC and demos sit inside their game.
In the app

The Covers view, with a summary of what each game holds under its cover.

The Details view, with each game opened as a tree.

The app's Columns view.

The Gallery view, with the DLC tray under the cover.

The app's Art slots view.

The app's Shelves view.
- Browser By folder, system, date or all at once, with filters for missing art, system, extension and region, and search. Tested with a generated library of 12,000 ROMs.
- Six views Covers, Details, Columns, Gallery, Art slots and Shelves, on ⌘/Ctrl+1 to 6.
- View options Five cover sizes, grouping, sorting, columns, row density and the inspector (⌘/Ctrl+I).
- One keyboard model Arrows, Home and End, type to jump, ⌥↑ and ⌥↓ between groups and Space for Quick look, in every view.
- Each library, its view It remembers the view and its options for the 20 latest libraries.
- Inside each game Updates, DLC, demos and revisions show inside their game in all six views: a summary such as «+3 DLC · v1.05» under the cover, the DLC tray in Gallery and a tree in Details. since 0.5
- Content filters «Has updates», «Missing the latest update», «Has DLC» and «Demos only», and a list of add-ons missing their base game. The status bar counts games: updates and DLC do not add to it. since 0.5
Sorts by system, archives too
From a downloads folder to a tidy library, with a dry run, resume and undo.
In the app

The Organise plan, before anything moves.

Extraction, track by track.

It asks before writing 10 GB or more.

Multi-disc games, with their .m3u.
- Sort a folder Each file goes to its system folder with a confidence and a reason; doubtful files stay where they are. It moves or copies without ever overwriting, with a dry run, resume and undo.
- Archives by their contents zip, 7z, tar, gz, bz2, xz, zst and lz4; RAR if the computer has
unrar, 7-Zip orbsdtar. - Disc games, extracted PlayStation, Saturn, Dreamcast, Sega CD, PC Engine CD and Neo Geo CD come out of the archive into their system folder, each track checked by size and CRC.
- What stays, and why Encrypted, too big to open safely, in several parts, unsafe path…: what it does not move says why.
- Games that are a folder PS3, Vita, Wii U, PS4, PS5, Xbox and others move as one item, from inside a zip or 7z too.
- Multi-disc with its .m3u Loose discs of one game are grouped, with a note when one is missing.
- Asks before 10 GB or more «Yes / Yes to all / No», with the size and the space left on the target.
- Extraction you can follow «Game 2 of 4 · Track 5 of 16», a bar by size, the speed and the time left.
- Updates and DLC with their game The plan lists them under their game, not as games of their own.
Current consoles, no keys
Switch, 3DS, PS3, PS4, PS5, Vita, Wii U and Xbox are recognised from what they carry in the clear. Coverly never reads or asks for keys.
In the app

Current consoles in the Organise plan.

Switch with the catalogue off: names come from the file.
- What is in the clear GameCube, Wii, Wii U, 3DS, Switch, Vita, PS3, Xbox and Xbox 360 are identified from their plain header, reading a few KB and never the whole game.
- PS4, PS5, Xbox One and Series From
sce_sys/orMicrosoftGame.config. Xbox Series is catalogued only. - «Encrypted», not a guessed name A Switch or 3DS name that needs the console's keys shows «Encrypted». Key and licence files are never opened.
- Switch name catalogue Optional, off until you turn it on; downloaded from blawar/titledb, at most once a week, and never shipped with the app.
- DSi and DSiWare Inside Nintendo DS, recognised from their header, without a separate system.
Duplicates set aside, nothing deleted
Finds the same game stored twice by its content, keeps one copy by your rules and sets the rest aside, with undo.
In the app

The Duplicates screen, before anything is set aside.

Copies by title ID and version, in the Organise plan.
- By content, never by name Exact copies under any name or container, the same disc in another format and, only with «One ROM per game», other versions.
- Rules for the one that stays A save, played, verified dump, region…: you reorder them or turn them off, and every pick says why.
- Set aside, not deleted To
_Duplicados/, with their saves, states, art andgamelist.xmlentries, or to the Trash if you choose; undo brings them back from there too. If two copies have different saves, it touches neither. - By title ID and version Of two versions of one game it suggests the newer, and an update is never a copy of its game. On Wii U, the .wua stays over its folder.
- Each copy, in full Region, revision, size, format, cover, whether it has a save and the rule that kept it, a button to show it in the Finder or Explorer, and keys: ↑/↓ and 1–9 to pick, J/K between games, X to leave one alone.
Each game in its folder, with its extras
Modern-console games, each in its own folder with its updates and DLC; mods, cheats and extras next to their game, and the music and manuals open in the app.
<Game>/Updates/DLC/<Game> (Demo)/
In the app

The game panel: the version you have and everything that goes with the game.

Organise shows each game's folder before moving it.

Mods and cheats in their game's folder; anything unclear stays put.

A game's extras, by category and with tags.

The image viewer, without leaving the app.
- One folder per game On modern consoles, Organise moves each game with its updates and DLC into
<System>/<Game>/, withUpdates/andDLC/, and it can be undone. Demos go to a<Game> (Demo)folder of their own; retro revisions are grouped in the library, but stay as they are on disk. since 0.5 - Mods, patches and cheats with their game They are linked to their game and, with the Coverly layout, go into its
Mods/andCheats/folders. It can also follow the folder layout your emulator or frontend expects. A translation patch named after its ROM plus a tag such as[T-En]is linked to that ROM. Anything that fits no single game stays where it is, and the plan says why. since 0.5 - The version you have The game panel compares the installed version with the newest one your library holds, next to its DLC, the demo and the revisions. since 0.5
- 3DS region The region or country comes from the product code and is added to the name only when it has none; an unknown letter is flagged and nothing is guessed. since 0.5
- Each game's extras Soundtrack, manuals, artwork, videos, themes and guides in the game's
Extras/folder, by category and with tags. «Add files» copies and checks each one, and the originals stay where they are. Every change can be undone; what you remove goes to the Trash and is never deleted. since 0.5 - What it knows about each extra
extras.json, insideExtras/, keeps each file's kind, whether it is official or yours, where it came from and its tags. A file moved or renamed outside the app is found again with its tags. since 0.5 - Official extras and ripped music PS3, Vita, PSP and Xbox 360 themes and avatars and 3DS soundtracks are recognised without any key and, with the Coverly layout, Organise puts them in
Extras/. A music rip (SPC, NSF, GBS, VGM, PSF) whose tags name a game in your library is suggested for its soundtrack. since 0.5 - Player and viewer Music plays in a mini player that keeps going while you browse other games; videos, images with zoom, PDF manuals and text files such as
.nfoopen in a viewer. It all works from the keyboard, and PDFs are shown without running their scripts. since 0.5
All of it, from the terminal
The coverly command does what the app does, and you can script it.
# What's missing (read-only)
$ coverly audit /Volumes/SD --missing-only
FOLDER SYSTEM ROMS MISSING-COVER
…
TOTAL 18 systems 12000 4553
# The plan, nothing written
$ coverly fill /Volumes/SD
Dry run: nothing was written. Re-run with --apply…
# Now for real, skipping the doubtful ones
$ coverly fill /Volumes/SD --apply --auto-only
Job 20261113T101500Z-1a2b-0001: filled 4401, …# A downloads folder, onto the card
$ coverly organize ~/Downloads --target /Volumes/SD
Dry run: nothing was written. Re-run with --apply to organise 212 files.
# Apply, and leave 10 GB or more for later
$ coverly organize ~/Downloads --target /Volumes/SD --apply --skip-large
extract item 2/4 files 5/16
Organised: moved 205, copied 0, skipped 0, failed 0 (job …)# Repeated copies, by their contents
$ coverly dedupe /Volumes/SD
38 extra copies across 17 games, 1,204,551,680 bytes. Dry run: nothing moved.
# Set them aside, delete nothing
$ coverly dedupe /Volumes/SD --apply
Set aside 38 copies in /Volumes/SD/_Duplicados: …# The last job
$ coverly undo
Undid dedupe job 20261113T102500Z-1a2b-0003: moved back 38, …
# An earlier one, and those that came after
$ coverly undo --job 20261113T101500Z-1a2b-0001 --include-later
Undid organise job 20261113T102000Z-1a2b-0002: moved back 205, …
Undid job 20261113T101500Z-1a2b-0001: removed 4401, restored 0An illustration with example numbers.
Real output
Audit and fill ROM cover art Usage: coverly <COMMAND> Commands: audit Report which ROMs of a library lack cover, screenshot or title art (read-only) catalog Manage the optional, downloaded name catalogues (the Switch one today: status, update, remove) dedupe Find the same game stored more than once inside one system, show which copy stays and set the others aside (dry run unless --apply) fill Fill missing art from the enabled sources (dry run unless --apply) integrations Manage the accounts and keys of online services (values are never printed) organize Sort a pile of loose ROMs into one folder per system (dry run unless --apply) profiles List the built-in and custom layout profiles systems List the known systems and their folder aliases undo Undo the last job (fill or organise), or the one given with --job update Check for a newer coverly, or install it (verified with minisign) help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print version
coverly --help from version 0.5.2, as printed.
auditCounts what is missing, read-only; the report comes out as CSV or JSON.fillFills covers, screenshots and title screens; a dry run until you add--apply.organizeSorts by system, like Organise in the app; a dry run until--apply. Since 0.3, writing 10 GB or more needs--yes-large, and--skip-largeleaves it where it is.dedupeSets repeated copies aside, or sends them to the Trash with--trash; a dry run until--apply.undoUndoes the last job, or the one you name with--job, and with--include-laterthe ones after it too.catalogcatalog switchdownloads, checks or removes the Switch name catalogue.integrationsLists, tests, saves or forgets keys. The secret comes from stdin or a variable, never an argument, and no output prints it.profilesLists the built-in layouts and your own.systemsLists the known systems and the folder names of each.updateChecks for and installs updates, verified with minisign.- A single binary For macOS, Windows and Linux, x64 and ARM64.
Your keys, in one place
One card per service, with its status, «Test connection» and the official page to get the key. Keys live in the OS keychain.
In the app

Integrations, with the SteamGridDB key already saved.

Nothing set up yet: where to start.
- One card per service SteamGridDB, ScreenScraper and the Switch catalogue, each with what it is for and what is sent, plus the «Coverly updates» card. ScreenScraper shows as «Not available» in published releases: it does not identify or download anything yet.
- Status and «Test connection» Not set up, saved, connected, error and what to do, or off. «Test connection» sends one request, only when you press it; «How to get the key» leads to the service's own account page. You can turn it off without deleting the key, or forget its credentials.
- In the system keychain A saved key is never shown again, and never appears in logs, reports or the settings you export. If the keychain is locked or does not answer, it says what to do on macOS, Windows or Linux.
- Notices that lead to its card When a key is missing or refused, or the Switch catalogue is off, Fill and Organise link to its card.
- From the terminal too
coverly integrationslists, tests, saves and forgets. It reads the key from standard input or a variable, never from an argument, and no output shows it. - Coming later, as a list only IGDB, RetroAchievements, TheGamesDB and other services appear in a list that asks for no key yet.
No Coverly account, undo, signed updates
No Coverly account, no telemetry. A dry run before writing, undo after, and updates signed with minisign.
3 covers added. The one you replaced is copied off the card.
In the app

The new-version notice; the number is an example.

Jobs: each with its report and its undo.

Searching the settings (⌘F or Ctrl+F).
- A dry run first, undo after First you see the whole plan and nothing is written; afterwards each job can be undone from Jobs, and
coverly undo --include-lateralso undoes what came after it. - No account, no telemetry There is no telemetry. It only connects to the art sources you turn on, the catalogues it identifies games with, the Integrations services when you test or use a key, the Switch catalogue if you turn it on, and the update check.
- Signed updates (minisign) Verified with minisign before they install; stable and beta channels, and it never restarts mid-job. The installer does not carry an Apple or Microsoft certificate yet, so the first launch shows a warning.
- Settings with search In tabs, with the advanced options folded; ⌘F or Ctrl+F finds any setting.
- One download per computer Mac Apple silicon or Intel, Windows x64 and ARM64, Linux x64 and ARM64.
- Spanish and English And light, dark or the system's.
Credits
Coverly builds on the work of 64 projects, and the app names every one: what it uses from each, its licence and the credit it asks for.
- Cover and metadata sources 5
- Databases and DATs 9
- Technical docs and wikis 19
- Frontend and firmware conventions 7
- Libraries 19
- Fonts and icons 5
In the app

Credits in the app, with its search box.
Where Coverly is ahead, and where it is not
Compared with what people usually use for a handheld's covers. The last block is theirs.
| Feature | Coverly ROMs | Skraper | Skyscraper | ARRM | Mini Scraper |
|---|---|---|---|---|---|
| Windows | Yes, x64 and ARM64 (beta) | Yes | — | Yes | Yes, x64 |
| macOS | Yes, Apple silicon and Intel | No native build | Build it yourself | No | Apple silicon only |
| Linux | x64 and ARM64 | Through Mono | Build it yourself | No | x64 |
| Desktop app | Yes | Yes | No, terminal | Yes | Yes |
Anbernic layout (Imgs/) | Built in | With setup | With setup and renaming | With setup | Built in |
| Account | No | ScreenScraper, in practice | Recommended | Recommended | No |
| Dry run and undo for covers, sorting and duplicates | Yes | — | — | — | — |
| Identifies by fingerprint | CRC32, MD5 and SHA1 | Yes, CRC, MD5 and SHA1 | Yes, with ScreenScraper | — | — |
| Reviews doubtful matches, with the reason | Yes | — | — | — | — |
| A cover even when no database has one | The game's own icon, on consoles whose games carry one | — | — | — | — |
Where they are ahead
Skraper, Skyscraper and ARRM use ScreenScraper and bring videos, image mixes, logos and metadata. ScreenScraper is not yet an art source in published releases. Mini Scraper and ROMCover also work without an account on Mac and ship the Anbernic layout.
Sources: skraper.net, github.com/Gemba/skyscraper, jujuvincebros.fr, github.com/tzubertowski/mini-scraper-cfw and github.com/Drafffffff/ROMCover.
Small things
- Settings in tabs, with search (⌘F or Ctrl+F).
- Spanish and English; light, dark or the system's.
- One download per computer: Mac Apple silicon or Intel, Windows x64 and ARM64, Linux x64 and ARM64.
- Copies across drives are verified.
- It stops when the disk is full and goes on when there is room.
- Organise logs are kept at least 90 days.
What it does not do yet
- Copy games to your handhelds or manage your saves: that is on the roadmap.
- Edit metadata or verify ROMs.
- Use ScreenScraper: published releases show it as “Not available”.
- Download videos, mixed images, logos or metadata.
- Run on the handheld itself.
- It has not been tested on real handhelds yet.