Repository navigation
Import Export
Tonkatsu Box uses .xcollx files to share collections. A single file contains all items, metadata, covers, canvas layouts, and settings.
- Open a collection
- Tap the menu (⋮) → Export
- Choose where to save the
.xcollxfile - Done - the file includes everything: items, covers, ratings, statuses, canvas
- All collection items with their metadata
- Cover images (embedded in the file)
- Your ratings and statuses
- Author comments
- Canvas layout - items, text notes, connections, positions
- Canvas images
- Your tags and which items carry them
When exporting, an optional "Include personal data" checkbox is available. When enabled, the export also includes:
- User status and dates (started, completed, last activity)
- Personal notes (user comments)
- Episode progress (current season, current episode)
- Watched-episode marks - which exact episodes you ticked off, re-applied to the target collection on import
- Likes and notes on episodes, seasons, chapters and the other units
- Sort order and date added
Files with personal data have a user_data: true flag in the header. On import, personal data is automatically restored when present. Files without the flag import as before (backward compatible).
- Wishlist items
- API keys or app settings
- Go to Collections tab
- Tap Import (or menu → Import)
- Select a
.xcollxfile - Choose: create a new collection or add to an existing one
- Import runs - items are matched against the database and added
Full export (.xcollx): All items, covers, metadata, canvas layout, and tier lists. Works offline on import.
Light export (.xcoll): Items and metadata only, smaller file size. Requires API keys on import to fetch covers and details. Each item is refetched from the provider it came from, so TVmaze shows, Kitsu and MangaDex titles and books all come back with their own source, not only TMDB and AniList items.
Light files exported by versions before 0.40 do not carry the provider id for books and MangaDex manga: those arrive unresolved and a Refresh from source on the item fixes them.
When importing into an existing collection, duplicates are updated (author comment, rating) instead of skipped. Tier lists and tags from the file are imported normally. Canvas layout is skipped to avoid duplication (canvas items have no unique constraint).
- Collection is created (or selected)
- Items are added with their statuses and ratings
- Cover images are extracted and saved locally
- Canvas layout is restored (if present)
- If media data is not embedded - it's fetched from the API
If an import fails, the app now shows the full error text with a copy button, instead of cutting it short. You can read exactly what went wrong and copy it to share when you ask for help.
Download ready-made collections directly from the app: Settings > Import > Browse Online Collections. The catalog includes 45+ collections across 32 platforms, plus movies and anime.
If you keep a list somewhere else, or you script your own, you can load cards straight from a JSON or CSV file: Settings → Import → Custom cards. Only a title and a type are required; everything else - year, genres, cover, platform, your status, rating, notes, dates and tags - is optional.
In addition to file export, you can copy your collection as formatted text to the clipboard:
-
Copy as List: Quick copy using the default template
{name} ({year})- one click, no dialog - Copy as Text…: Opens a dialog with a customizable template, token chips, sort options, and a live preview
Available tokens: {name}, {year}, {rating}, {myRating}, {platform}, {status}, {genres}, {notes}, {type}, {link}, {#}
{link} outputs the item's page on its source - IGDB for games, TMDB for movies and shows, AniList for anime and manga, your own link for custom items. {type} prints the type a custom item is displayed as (Game, Anime, ...) rather than a flat "Custom". An empty token is dropped together with its separator.
Your custom template is saved between sessions.
.xcollx is a ZIP archive containing JSON data and embedded images. It's an open format - you can unzip and inspect the contents. See RCOLL_FORMAT.md for the full specification.
Back up everything in one click: Settings → Backup → Backup All Data. The backup .zip includes:
- All collections, with your ratings, statuses, notes, canvas boards, and saved covers
- Your tags
- Tier lists and mood grids
- Wishlist items
- Episode watch progress for TV shows and anime
- Your releases follow list and calendar entries
- RetroAchievements and Steam tracker progress
- App settings
Older backups made before some of these were added still restore fine; they simply won't bring in the parts they never had.
A restore keeps the original dates: when each collection was created and when each item was added, so the "added by month" history in Statistics survives the round trip. Mood-grid caption and cell-label templates come back too.
To restore: Settings → Backup → Restore from Backup → select the .zip file. A confirmation dialog shows a manifest preview (collection count, item count, wishlist count) with checkboxes for restoring wishlist and settings. Collections are always created as new (no merge). Wishlist entries are deduplicated by text.
When you start a restore, the app opens a window over the rest of the interface: "Restoring from backup, do not close the app. This may take several minutes for large copies." It shows a counter of restored collections.
While restore is running:
- The back button does nothing.
- On desktop, closing the window via the taskbar or Alt+F4 is cancelled.
- The counter only goes up after a collection is fully saved.
At the very end the screen shows a Finishing up… stage. The window closes only after the data is actually written. You don't see "done" while the app is still saving.
- Use Full Backup for a complete snapshot - it's faster than exporting collections individually
- Share
.xcollxfiles with friends - they can import them directly - Pre-made collections work without any API keys
- Browse Online Collections - download pre-made collections from the catalog
- Trakt Import - import movies and TV shows from Trakt.tv
- Steam Import - import your Steam game library
- RetroAchievements Import - import retro games with achievement progress
- MyAnimeList Import - import anime and manga lists from MAL
- AniList Import - import anime and manga lists from AniList
- IGDB List Import - import a game list exported from IGDB.com
- Kinorium Import - import movie and TV lists from Kinorium
- Custom Cards Import - load your own cards from a JSON or CSV file