Skip to content

Backups and State Files

Safe to Inspect — Does Not Modify Your World

Commands in this mode only read files or display information. Your Minecraft world save remains completely untouched.

NBTExplorerCLI keeps all tool metadata, scan caches, translation sessions, backup blobs, and recovery journals outside your Minecraft world folder. This guarantees that inspecting a world, caching a scan, or working on a translation session never pollutes your save folder with extra files.

1. How the External State Root Works (--state-root)

Section titled “1. How the External State Root Works (--state-root)”

By default, world-scoped state is stored under your local Windows application data folder:

%LOCALAPPDATA%\nbtcli\worlds\<world-id>\

You can also specify a dedicated folder outside the world with --state-root 'D:\NbtState\MyWorld'. Make sure to pass the same --state-root across related plan, apply, status, recover, backup, restore, translate, and agent commands.

The standalone scan, extract, and regular validate commands default to %LOCALAPPDATA%\nbtcli\scan\<world-id> and accept an external --cache-root. Translation and writing workflows have a separate cache under the state root.

Subfolder / File Purpose Can It Be Deleted or Rebuilt?
cache/ Stores the local cache used by translation and writing workflows. Rebuildable: Manage it separately from the standalone scan cache.
sessions/ Stores translation sessions (translate start, submit, note, glossary, seal). Keep while translating: Contains your translation progress, slot replies, and glossary history.
agent/ Stores external assistant questionnaire settings (agent setup / submit). User configuration: Keep to retain default language and page-size preferences for that world.
objects/ Content-addressed store (by SHA-256) holding verified preimage files and backup blobs. Critical for restore & rollback: Required by restore and recover to reconstruct original world files.
journals/ Stores active and completed write journals and receipts for apply, status, and recover. Critical for recovery: Never delete while an edit is in progress or requires recovery (exit code 7).
backup_<suffix>_*.json Named backup manifests created when you run backup --suffix <name>. Keep with objects/: Records the exact file paths and SHA-256 hashes of a world backup.

<world-id> is the tool’s world identifier without hyphens. Assign an explicit, separate state root to each world copy. If you recreate or copy a world folder, scan the selected folder and generate a fresh plan for it. Use the same world path and state root when resuming an existing journal.

2. Creating a Verified World Backup (backup)

Section titled “2. Creating a Verified World Backup (backup)”

Run backup before major edits to capture a verified, content-addressed snapshot of the entire world (or pass --path <relative-path> to back up a single file):

Terminal window
New-Item -ItemType Directory -Path 'D:\Backups' -Force | Out-Null
.\nbtcli.exe backup 'D:\WorldCopy' `
--suffix before-translation `
--output 'D:\Backups\before-translation-manifest.json'

Example response:

{
"schemaFamily": "nbtcli.cli",
"schemaVersion": 1,
"success": true,
"command": "backup",
"outcome": "Success",
"data": {
"manifestHash": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
"stateRoot": "C:\\Users\\Player\\AppData\\Local\\nbtcli\\worlds\\4a8b9c...",
"backupPath": "C:\\Users\\Player\\AppData\\Local\\nbtcli\\worlds\\4a8b9c...\\backup_before-translation_20261118T070000Z_a1b2c3.json",
"namedManifestPublished": true
},
"error": null
}

[!IMPORTANT] A backup manifest JSON file (before-translation-manifest.json) is an index of file paths and SHA-256 hashes; the actual file contents live inside the objects/ subfolder of stateRoot. Keep both the manifestHash and the stateRoot directory intact so you can restore later.

Modifies World Save — Close Minecraft and Back Up First

Writes changes to the selected world folder. Always test on a world copy, close Minecraft and other tools first, and pass --world-offline.

restore uses the verified backup manifest and the objects/ store to restore your world (or a single --path). Even if a target file in the world is currently corrupted or missing on disk, restore can replace it cleanly.

Run restore without --apply first to inspect the restoration plan:

Terminal window
.\nbtcli.exe restore 'D:\WorldCopy' `
--manifest-hash 4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a `
--output 'D:\Backups\restore-plan.json'

Close Minecraft and apply the saved plan using the same world and state root as the preview. Apply checks the recorded preimage and refuses to overwrite changes made after preview.

Terminal window
.\nbtcli.exe apply 'D:\WorldCopy' `
--plan 'D:\Backups\restore-plan.json' `
--world-offline

If you used --state-root for the preview, pass that same option here. To restore a single file, add --path level.dat to the preview command, review the output plan, and then apply that file.