Safe Editing and Recovery
NBTExplorerCLI is designed so that you never overwrite a Minecraft world blindly. Every modification follows a strict Preview -> Plan -> Offline Apply -> Verify workflow, backed by automatic pre-write backups and a crash recovery journal stored outside your world folder.
get --typesset / plan / batchapply --world-offlinestatus / recover1. Golden Rules Before Editing
Section titled “1. Golden Rules Before Editing”- Always test on a world copy (
D:\WorldCopy) before modifying an important save. - Close Minecraft and any other external tools (such as map editors or server processes) before running any command with
--applyorapply. - Never place
--state-rootor--outputfiles inside the world folder. Keep plans, receipts, and state folders in a separate directory such asD:\PlansorD:\NbtState.
2. Selecting Nodes and Using Explicit Typed NBT
Section titled “2. Selecting Nodes and Using Explicit Typed NBT”To prevent accidental data corruption (such as turning a Byte or Short tag into an Int or String), set does not guess NBT types from plain strings. Instead, it accepts a versioned nbtcli.typed-nbt JSON document via --value or --value-file.
Step A: Read the Current Typed Value
Section titled “Step A: Read the Current Typed Value”First, inspect the target node with get --types:
.\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --typesThe response includes the exact typed-nbt representation inside data.value:
{ "schemaFamily": "nbtcli.typed-nbt", "schemaVersion": 1, "data": { "name": "", "root": { "tag": "string", "value": "Original Map Name" } }}Choosing a Node Selector
Section titled “Choosing a Node Selector”When targeting a node inside an NBT or JSON file, provide one selector format:
--pointer: Standard JSON Pointer syntax (/separates keys; escape~as~0and/as~1), such as--pointer /Data/LevelNameor--pointer /Data/Player/Inventory/0/id.--segments: Explicit JSON array of up to 256 key/index objects for keys that contain special characters or dots:--segments '[{"kind":"key","key":"Data"},{"kind":"key","key":"Custom.Key"}]'
For region files (.mca), also specify --chunk <x,z> (global chunk coordinates) and, when querying standalone region files, --dimension <namespace:id>.
3. Previewing an Edit (No World Files Modified)
Section titled “3. Previewing an Edit (No World Files Modified)”Save your replacement typed-nbt JSON to a file outside the world (for example, D:\Plans\new-level-name.json), then run set without --apply to generate a preview plan:
New-Item -ItemType Directory -Path 'D:\Plans' -Force | Out-Null$read = .\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --types | ConvertFrom-Jsonif (-not $read.success) { throw $read.error.message }$replacement = $read.data.value$replacement.data.root.value = 'Translated Map Name'$replacement | ConvertTo-Json -Depth 50 | Set-Content -Encoding utf8 'D:\Plans\new-level-name.json'
.\nbtcli.exe set 'D:\WorldCopy' ` --path level.dat ` --pointer /Data/LevelName ` --value-file 'D:\Plans\new-level-name.json' ` --output 'D:\Plans\level-name-plan.json'Because --apply was omitted, your world folder is completely untouched. The CLI outputs a preview envelope ("preview": true) and writes the immutable nbtcli.patch-plan file to D:\Plans\level-name-plan.json.
[!NOTE] For multi-node edits, you can pass a
nbtcli.operationsJSON file (containing 1 to 100,000 operations with distinct IDs) tonbtcli plan 'D:\WorldCopy' --request 'D:\Plans\ops.json' --output 'D:\Plans\batch-plan.json'ornbtcli batch 'D:\Plans\ops.json' --world 'D:\WorldCopy' --output 'D:\Plans\batch-plan.json'.
4. Applying the Plan Offline
Section titled “4. Applying the Plan Offline”Once you have reviewed the plan and confirmed that Minecraft is closed, commit the plan with apply and --world-offline:
.\nbtcli.exe apply 'D:\WorldCopy' ` --plan 'D:\Plans\level-name-plan.json' ` --world-offline ` --output 'D:\Plans\level-name-receipt.json'During apply, the engine performs four safety steps in order:
- Precondition & Hash Verification: Confirms that the target files in
D:\WorldCopystill match the exact SHA-256 hashes recorded when the plan was created. If a file was modified externally,applystops with exit code3(Conflict) before writing anything. - Preimage Backup & Staging: Stores the original file bytes in the external
objects/repository and writes the updated data to temporary staged candidate files. - Journal Publication & Atomic Replace: Records the operation in the external
journals/directory and replaces the target world files. - Readback Verification: Re-reads the written files to prove their hashes match the planned postimages, then marks the receipt terminal (
"receiptIsTerminal": true).
Understanding the Nine Operation Outcomes
Section titled “Understanding the Nine Operation Outcomes”Every apply receipt accounts for all requested operations across nine mutually exclusive outcome counters:
| Outcome Field | Plain-Language Meaning |
|---|---|
applied |
The change was written and verified on disk. |
unchanged |
The target already had the requested value; verified with no physical write needed. |
skipped |
Pre-commit validation rejected the plan before any world file was touched. |
failed |
An operation failed during preparation or execution. |
conflict |
The target file or node changed since the plan was created, or had a competing edit. |
unsupported |
The operation targets a format or structure that is not supported for writing. |
cancelled |
The operation was recorded as cancelled (exit code 130). |
recoveryRequired |
The write was interrupted mid-commit; run status and recover (exit code 7). |
rolledBack |
Recovery restored the world to its verified pre-edit state (exit code 8). |
5. How to Judge and Recover After an Interrupted Write
Section titled “5. How to Judge and Recover After an Interrupted Write”If the CLI returns exit code 7 (RECOVERY_REQUIRED), keep the game closed and inspect the journal before retrying. A process that is terminated may produce no response. Use the saved plan hash and the same state root in either case. Recovery has been tested after process termination on Windows NTFS. Recovery after power loss has not been verified.
An abridged recovery response can look like this:
{ "schemaFamily": "nbtcli.cli", "schemaVersion": 1, "success": false, "command": "apply", "outcome": "RecoveryRequired", "data": { "planHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "recovery": { "world": "D:\\WorldCopy", "stateRoot": "C:\\Users\\Player\\AppData\\Local\\nbtcli\\worlds\\4a8b9c..." } }, "error": { "code": "RECOVERY_REQUIRED", "message": "World write requires recovery before further use." }}Step 1: Do Not Open the World in Minecraft
Section titled “Step 1: Do Not Open the World in Minecraft”Opening a partially updated world in Minecraft can overwrite chunk timestamps and prevent clean recovery. Keep the game closed.
Step 2: Inspect the Journal State with status
Section titled “Step 2: Inspect the Journal State with status”Run status with the exact same world path, --plan-hash, and --state-root (if you used a custom state root):
.\nbtcli.exe status 'D:\WorldCopy' ` --plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08Inspect the exit code, journal phase, receipt and repair guidance. journalMayBeAbsent: true means the CLI could not confirm the journal. receiptIsTerminal: false leaves the outcome unresolved. Keep the game closed and preserve the original plan, backup and state root. If a journal is missing or unreadable, investigate before proceeding. Use recover only after confirming the original journal and plan identity.
Step 3: Run recover (Forward Complete or Roll Back)
Section titled “Step 3: Run recover (Forward Complete or Roll Back)”You have two safe choices with recover:
-
Complete the planned edit forward (using the staged postimages stored in the journal):
Terminal window .\nbtcli.exe recover 'D:\WorldCopy' `--plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 `--world-offline -
Roll back to the exact original world files (using the verified preimage backups stored before the write began):
Terminal window .\nbtcli.exe recover 'D:\WorldCopy' `--plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 `--rollback `--world-offline
A successful rollback returns exit code 8 (RolledBack) so automated scripts never mistake a rollback for a forward edit, and your world files are restored byte-for-byte to their pre-edit state.