How to Connect RetroAchievements to RetroShelf
Connect your RetroAchievements profile to RetroShelf to import the games you have beaten and mastered, plus your points and rank, then keep them in sync automatically.
What you need
Connect your account
Open RetroAchievements settings on RetroShelf
Sign in to RetroShelf and go to Settings › RetroAchievements. Enter your RA username and click Start verification.
Copy the verification code
RetroShelf generates a short code that looks like RS-XXXXXX. Click Copy code to grab it.
This is a one-time ownership check. You do not need to provide an API key.
Paste the code into your RA User Motto
Click Open RA settings to jump to your RetroAchievements profile settings. Paste the code into your User Motto field and save.
If your motto already had something in it, do not worry. RetroShelf shows the previous value back to you after verification so you can paste it straight back.
Verify and import
Back on RetroShelf, click Verify and import. RetroShelf checks your motto against the code, and once it matches, the initial import begins automatically.
Restore your User Motto
After a successful verify, RetroShelf shows your previous motto with a one-click copy button. Pop back to RA settings, paste it in, and you are done.
What gets imported
Beaten games
Any game where RetroAchievements records a beaten or mastered award becomes a beaten entry in your RetroShelf library.
Mastery flair
Mastered titles are still beaten on RetroShelf, but the RA mastery is preserved as integration metadata for future profile flair and milestones.
Currently playing
Recent RA activity and partial progress without a beat or mastery seed your playing shelf so it reflects what you are actually working through.
Profile stats
Your RA points, rank, and mastery count appear in a compact RetroAchievements card on your RetroShelf profile.
What is not imported
To keep your library focused and trustworthy, RetroShelf intentionally leaves a few things out of the import:
- Individual achievements. RetroShelf does not mirror every per-game achievement. Mastery is preserved as a signal; the long tail is not.
- Total playtime and synthetic sessions. RA does not expose reliable session history, so RetroShelf will never invent journal entries, activity timeline rows, or playtime totals from RA data.
- "Want to Play" backlog. Importing your RA backlog requires more privileged access than the public reads RetroShelf currently uses, so it is deferred for now.
How ongoing sync works
Auto-sync every 6 hours
Once connected, RetroShelf re-pulls your RA progress on a background schedule. New beaten and mastered games show up without you doing anything.
Manual sync on demand
Use Sync now in Settings › RetroAchievements when you want fresh data immediately. Manual syncs cool down for 30 minutes between runs.
Local edits win
If you change a game's status on RetroShelf after the import, later RA syncs respect that change. Your library stays yours.
Profile metrics refresh
Your RA points, rank, and mastery count update on each sync, so the card on your profile stays current.
Manage the connection
You can manage everything from Settings › RetroAchievements:
- Sync now: pull the latest progress from RA. Useful right after earning a new mastery.
- Disconnect: stop future syncs and unlink your RA profile. Games already imported stay in your RetroShelf library.
- Reconnect to a different RA account: disconnect first, then start a fresh verification with the new username.
Troubleshooting
Verification keeps timing out
Confirm the code is pasted into the User Motto field on RA, not the bio or another text area, and that you clicked Save on the RA settings page. RA can take up to 30 seconds to propagate the change. Wait a few seconds and try Verify and import again. The same code stays valid until you restart verification.
"That RetroAchievements account is already linked to another RetroShelf user"
Each RA profile can only be linked to one RetroShelf account. If you control both accounts, disconnect RA from the other RetroShelf account first, then retry verification.
Sync shows "Needs attention"
Open Settings › RetroAchievements and read the error message under the status row. The most common cause is a temporary RA outage. Try Sync now in a few minutes. If the error persists, disconnect and reconnect to refresh the link.
Imported games have the wrong status
Local edits win on RetroShelf, so the simplest fix is to update the status yourself. Future RA syncs will not overwrite your change.
Ready to connect?
Bootstrap your library in under a minute
Verify your RA profile and watch your beaten and mastered games land on your shelf.
FAQ
Do I need a RetroAchievements API key to connect my account?
No. RetroShelf uses its own RetroAchievements API credentials for public profile reads. You only need your RA username and a one-time User Motto code to prove ownership of the account.
Will connecting RetroAchievements overwrite games I have already logged on RetroShelf?
No. Local edits always win. After the initial import, if you change a game's status on RetroShelf (say, from beaten back to playing), later RA syncs will not overturn that change.
Does RetroShelf import individual achievements from RetroAchievements?
Not in this version. The integration imports durable signals like beaten games, mastered titles, points, and rank. Per-achievement mirroring is intentionally out of scope to keep your library focused.
Why does RetroShelf ask me to set my RA User Motto?
It is a quick ownership check. Pasting a one-time code into your RetroAchievements User Motto proves you control the account without forcing you to share an API key. You can change the motto back as soon as verification succeeds.
My RA verification timed out. What should I do?
RetroAchievements can take up to 30 seconds to reflect a profile change. Make sure you saved the motto on RA, wait a moment, then click Verify and import again. The same code stays valid until you start a new verification.
How do I disconnect RetroAchievements from RetroShelf?
Go to Settings › RetroAchievements and click Disconnect. Imported games stay in your RetroShelf library. Disconnecting only stops future syncs and removes the link to your RA profile.
Related