Backups and State Files
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.
Directory Layout Inside a State Root
Section titled “Directory Layout Inside a 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. |
How World Scope Binding Works
Section titled “How World Scope Binding Works”<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):
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 theobjects/subfolder ofstateRoot. Keep both themanifestHashand thestateRootdirectory intact so you can restore later.
3. Restoring from a Backup (restore)
Section titled “3. Restoring from a Backup (restore)”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.
Step 1: Preview the Restoration
Section titled “Step 1: Preview the Restoration”Run restore without --apply first to inspect the restoration plan:
.\nbtcli.exe restore 'D:\WorldCopy' ` --manifest-hash 4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a ` --output 'D:\Backups\restore-plan.json'Step 2: Apply the Reviewed Plan Offline
Section titled “Step 2: Apply the Reviewed Plan Offline”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.
.\nbtcli.exe apply 'D:\WorldCopy' ` --plan 'D:\Backups\restore-plan.json' ` --world-offlineIf 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.