Skip to content

Safe Editing and Recovery

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.

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.

STEP 01
Inspect Node
get --types
STEP 02
Preview Plan
set / plan / batch
STEP 03
Apply Offline
apply --world-offline
STEP 04
Verify or Recover
status / recover
  1. Always test on a world copy (D:\WorldCopy) before modifying an important save.
  2. Close Minecraft and any other external tools (such as map editors or server processes) before running any command with --apply or apply.
  3. Never place --state-root or --output files inside the world folder. Keep plans, receipts, and state folders in a separate directory such as D:\Plans or D:\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.

First, inspect the target node with get --types:

Terminal window
.\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --types

The 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"
}
}
}

When targeting a node inside an NBT or JSON file, provide one selector format:

  • --pointer: Standard JSON Pointer syntax (/ separates keys; escape ~ as ~0 and / as ~1), such as --pointer /Data/LevelName or --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)”
Preview Mode — Generates a Plan File Without Touching the World

Creates a reviewable change plan or session file outside your world folder so you can check every change before writing.

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:

Terminal window
New-Item -ItemType Directory -Path 'D:\Plans' -Force | Out-Null
$read = .\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --types | ConvertFrom-Json
if (-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.operations JSON file (containing 1 to 100,000 operations with distinct IDs) to nbtcli plan 'D:\WorldCopy' --request 'D:\Plans\ops.json' --output 'D:\Plans\batch-plan.json' or nbtcli batch 'D:\Plans\ops.json' --world 'D:\WorldCopy' --output 'D:\Plans\batch-plan.json'.

Once you have reviewed the plan and confirmed that Minecraft is closed, commit the plan with apply and --world-offline:

Terminal window
.\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:

  1. Precondition & Hash Verification: Confirms that the target files in D:\WorldCopy still match the exact SHA-256 hashes recorded when the plan was created. If a file was modified externally, apply stops with exit code 3 (Conflict) before writing anything.
  2. Preimage Backup & Staging: Stores the original file bytes in the external objects/ repository and writes the updated data to temporary staged candidate files.
  3. Journal Publication & Atomic Replace: Records the operation in the external journals/ directory and replaces the target world files.
  4. Readback Verification: Re-reads the written files to prove their hashes match the planned postimages, then marks the receipt terminal ("receiptIsTerminal": true).

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):

Terminal window
.\nbtcli.exe status 'D:\WorldCopy' `
--plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Inspect 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.