Backups

Link Cable’s backup suite is the canonical recovery surface. Every backup is a full snapshot across all six sync lanes — party, PC, Cobblemon general, Pokedex, Molang, and the player-core lane (inventory, ender chest, hunger, XP, abilities, recipe book, plus Cardinal Components and Fabric Attachment API data) — written to canonical storage atomically. Restores rewrite the same lanes together, with watermarks updated so live caches and runtime state stay coherent.

All backup commands sit behind the linkcable.command.admin permission node (operator level 2 fallback).

Command Surface

Command	Effect
`/linkcable backup create <player> [reason]`	Take a full snapshot of the player and store it. `reason` is free-form text and defaults to `manual`.
`/linkcable backup list <player>`	Print every backup for the player, newest first, with id, timestamp, size, and reason.
`/linkcable backup browse <player>`	Open an in-game browser GUI for the player’s backups.
`/linkcable backup inspect <backupId>`	Print full detail for one backup, including lane sizes and timestamps.
`/linkcable backup party <backupId>`	Open a GUI showing the party in this specific backup.
`/linkcable backup pc <backupId>`	Open a GUI showing the PC contents in this specific backup.
`/linkcable backup restore <player> <backupId>`	Restore the backup onto the player. Offline-only.
`/linkcable backup delete <backupId>`	Delete a backup.
`/linkcable backup export <backupId> <path>`	Export the backup as an archive at the given filesystem path.
`/linkcable backup import <path>`	Import a previously-exported backup archive.

<player> autocompletes against known players, including offline players. <backupId> autocompletes against known backup ids — pasting the full id is rarely necessary.

Creating Backups

/linkcable backup create AsterAmo "before pasture cleanup"

The reason field is free-form text shown in list output and the browser GUI. Use it. Backups without a reason all read as manual in the listing, which makes finding the right one to restore harder than it needs to be.

Output looks like:

◆ Created backup 01HZJW…  ◆
2026-04-28 14:32:11 #01HZJW7Q v3 before pasture cleanup [Inspect] [Party] [PC] [Restore]

The header is the success message with the full backup id; the line below is the formatted summary — timestamp, an 8-character short id, the snapshot version, the reason text, and four clickable buttons ([Inspect], [Party], [PC], [Restore]). The buttons run the corresponding /linkcable backup … command without you having to type the id.

Listing and Browsing

/linkcable backup list AsterAmo

Prints up to backupMaxPerPlayer (default 20) entries, newest first. Each entry is a clickable summary — clicking opens an inspect view in chat.

/linkcable backup browse AsterAmo

Opens an in-game GUI showing the same set with richer navigation — you can click into any backup to see its party and PC contents directly, without needing to remember the id.

Inspecting a Backup

/linkcable backup inspect 01HZJ…

Prints lane-by-lane detail:

player UUID and last known name
creation timestamp and reason
sizes for party, PC, Cobblemon general, Pokedex, Molang, and player-core lanes
whether the backup includes pasture-tethered Pokémon (and which ones)

For visual inspection of the actual contents:

/linkcable backup party 01HZJ…
/linkcable backup pc 01HZJ…

Both open ConfigGUI-backed browsers showing the Pokémon as they were stored in the backup — species, form, level, ability, moves, held item, nickname.

Restoring

Restores are intentionally offline-only. The check rejects any player who’s currently CONNECTING, LOADING, ACTIVE, or HANDOFF_PENDING — in practice, anyone online or mid-transfer.

/linkcable backup restore AsterAmo 01HZJ…

What happens:

Link Cable confirms the player is in a restorable state (rejects with Player <uuid> is not offline otherwise).
If the player has an existing canonical snapshot, a pre-restore backup is taken automatically with reason pre-restore:<originalBackupId>.
The chosen backup is written into canonical snapshot storage.
The hot-cache entry for the player is updated to match.
The runtime record’s flushed-version and flushed-timestamp watermarks are updated so the next load sees the restored snapshot, not stale state.

The next time the player logs in (any backend), they spawn into the restored state.

If the restore fails partway through (storage error, etc.), the pre-restore backup is your rollback. Run /linkcable backup list <player> to find it — the reason will start with pre-restore:.

Deleting

/linkcable backup delete 01HZJ…

Hard-deletes the backup from canonical storage. There’s no undelete. The auto-prune system will eventually remove old backups based on backupMaxPerPlayer and backupMaxAgeDays (see Configuration) — prefer letting it run rather than manual deletion unless you specifically need a backup gone now (e.g. it contains data the player asked to be removed).

Deleting the most recent pre-restore backup is a way to lose a rollback. Don’t do it without confirming the restore that produced it was successful.

Export and Import

For moving backups between networks (staging → production, or one network → another), or for keeping cold storage:

/linkcable backup export 01HZJ… /path/to/archive.zip
/linkcable backup import /path/to/archive.zip

Export writes the backup to a single file. Import reads a file and registers a new backup with a new id (the player UUID is preserved). The archive is self-contained — no Mongo lookup is needed to import on the destination network as long as the format matches.

There’s no built-in transport. Move the file with whatever tooling you’d use for any other server file (rsync, S3, etc.).

Auto-Pruning

Pruning happens at backup-save time, not on a scheduler. Whenever a backup is created (manual, pre-restore, pre-migration, or import), the player’s full backup list is sorted newest-first and filtered against two rules:

Backups older than backupMaxAgeDays are dropped.
Of what remains, only the newest backupMaxPerPlayer are kept.

Both rules apply equally to manual backups, automatic backups, and pre-restore backups. The pruning is per-player; one player having many backups doesn’t affect another player’s retention.

If you need a specific backup to not be pruned, export it before it ages out.

Adjusting the pruning rules takes effect after a restart of any backend that creates backups — see Configuration for the field definitions.

When to Take a Backup

You don’t need to take backups for every routine event — the auto-flush and snapshot persistence handles normal play. Take a manual backup before:

A bulk economy or item change you’re not 100% sure about
A mass /give or admin command run that touches many players
A controversial restore (so you have a clean rollback if the player asks for the original state back)
A restore (Link Cable does this automatically, but a second one before the operation is fine)
Any one-off admin action where you’d want to be able to roll back to “right before this happened”

The cap of 20 manual backups per player gives you plenty of headroom for these.

Troubleshooting

backup create fails with a storage error : Mongo isn’t writable from this backend. Check Mongo connectivity and Ceremony’s storage configuration. Other backends may still work; the failing one needs investigation.

backup restore rejects with Player <uuid> is not offline : Working as intended. The check rejects any player whose runtime state is CONNECTING, LOADING, ACTIVE, or HANDOFF_PENDING. Have the player log out, wait for the runtime state to settle to OFFLINE, then retry.

A backup is missing party Pokémon that the player definitely had : Almost always means the player wasn’t actually fully synced when the backup was taken. Run /linkcable backup create <player> while the player is on the backend that owns them, or wait for the next periodic flush. Backups taken on a participant for a player whose owner is the orchestrator may capture an older snapshot than the live state.

Auto-prune isn’t removing old backups : Pruning runs at backup-save time, not on a schedule. If old backups are still present, no new backup has been saved that would have triggered the prune. Run /linkcable backup create <player> — the new backup’s save will prune the player’s list against the current backupMaxPerPlayer and backupMaxAgeDays.

backup browse opens an empty GUI : The player has no backups yet. Run /linkcable backup list <player> to confirm.

Next Steps

Commands Reference — the full command catalogue, including the dev-only commands.
UltraSync Migration — migrating off UltraSync into the player-core lane.
Beta and Production Rollout — production hardening notes.