Skip to content

Install and Inspect

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.

This guide walks you through downloading NBTExplorerCLI, verifying the archive checksum, extracting the self-contained runtime, and running your first read-only inspection commands (get, list, search, scan, and extract) on a copy of a Minecraft Java Edition world.

1. Download and Verify the Windows x64 Package

Section titled “1. Download and Verify the Windows x64 Package”

You can obtain the Windows x64 archive (nbtcli-win-x64.zip) from two official sources:

  • GitHub Releases: Official tagged releases (v1.0.0) that have passed the release publication workflow.
  • GitHub Actions Candidates: Automated build artifacts (nbtcli-windows-x64) produced and smoke-tested in an SDK-free Windows Server Core container for a specific commit before a release tag is published.

Before extracting, verify that the ZIP file’s SHA-256 hash matches the value in the accompanying SHA256SUMS.txt file:

Terminal window
Get-FileHash .\nbtcli-win-x64.zip -Algorithm SHA256
Get-Content .\SHA256SUMS.txt

Extract the entire archive into a new, dedicated directory. The package is self-contained and bundles the pinned .NET runtime (10.0.15) and required libraries (ICSharpCode.SharpZipLib.dll). Always keep nbtcli.exe in the same folder as its accompanying .dll and .json files:

Terminal window
Expand-Archive -Path .\nbtcli-win-x64.zip -DestinationPath .\nbtcli
Set-Location .\nbtcli

[!TIP] Each release package also includes candidate.json, which records the exact build version (1.0.0), Git commit revision, pinned SDK (10.0.404), dependency versions, and the individual SHA-256 digest of every bundled file.

Run --version and --help to confirm the binary launches cleanly:

Terminal window
.\nbtcli.exe --version
.\nbtcli.exe --help

Example JSON response from --version:

{
"schemaFamily": "nbtcli.cli",
"schemaVersion": 1,
"success": true,
"command": "version",
"outcome": "Success",
"data": {
"product": "nbtcli",
"version": "1.0.0"
},
"error": null
}

To inspect the accepted options for any specific command or subcommand, run help <command>:

Terminal window
.\nbtcli.exe help get --ui-locale en-US
.\nbtcli.exe help translate --ui-locale en-US

Even though inspection commands never modify world files, it is best practice to make a dedicated copy of your Minecraft world (for example, D:\WorldCopy) before testing queries, scans, or edits. Make sure Minecraft is closed while copying the save folder so all region and level files are flushed to disk.

Use get to read a specific NBT tag, region chunk, or datapack JSON property.

Terminal window
.\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/DataVersion
{
"schemaFamily": "nbtcli.cli",
"schemaVersion": 1,
"success": true,
"command": "get",
"outcome": "Success",
"data": {
"representation": "display-json",
"pointer": "/Data/DataVersion",
"value": 3953
},
"error": null
}

Display JSON vs. Reversible Typed NBT (--types)

Section titled “Display JSON vs. Reversible Typed NBT (--types)”

By default, get returns human-friendly display-json. If you plan to use the output as input to set or batch later, add --types to obtain a reversible nbtcli.typed-nbt envelope that preserves exact NBT tag types (such as Byte, Short, Int, Long, Float bits, and typed arrays) along with the exact source address:

Terminal window
.\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --types
Terminal window
# Inspect a datapack JSON property inside the world
.\nbtcli.exe get 'D:\WorldCopy' --path 'datapacks/custom/data/quest/advancement/root.json' --pointer /display/title
# Inspect a specific chunk inside a region file
.\nbtcli.exe get 'D:\WorldCopy' --path 'region/r.0.0.mca' --chunk 0,0 --dimension minecraft:overworld --pointer /Status
# Inspect an entry inside a ZIP resource pack or datapack
.\nbtcli.exe get 'D:\WorldCopy\resources.zip' --entry 'assets/custom/lang/en_us.json' --pointer /item.custom.sword
Section titled “5. Explore World Structure with list and search”

Run list on a world directory to discover its declared dimensions, terrain region counts, and entity region counts:

Terminal window
.\nbtcli.exe list 'D:\WorldCopy'

Run list on an .mca region file without --chunk to list all populated chunk coordinates, or run search to find nodes by text value (--query), tag name (--name), or NBT tag type (--type):

Terminal window
.\nbtcli.exe list 'D:\WorldCopy' --path 'region/r.0.0.mca' --limit 20
.\nbtcli.exe search 'D:\WorldCopy' --path level.dat --name Spawn --limit 10

6. Scan and Extract World Text with scan and extract

Section titled “6. Scan and Extract World Text with scan and extract”

Use scan to index translatable and inspectable text across signs, hanging signs, books, items, entities, containers, command blocks, functions, scoreboards, bossbars, advancements, and language files:

Terminal window
# Quick summary of text sources across the world
.\nbtcli.exe scan 'D:\WorldCopy' --summary
# Scan a single dimension and include decoded text items in the output
.\nbtcli.exe scan 'D:\WorldCopy' --dimension minecraft:overworld --show-items --limit 25

[!NOTE] scan stores a fast, rebuildable cache outside your world folder (under %LOCALAPPDATA%\nbtcli\scan\<world-id> by default, or in a custom --cache-root outside the world). Pass --refresh to force re-parsing, or --no-cache to run without saving a persistent cache.

To export decoded text entries along with their exact source locations to a file outside the world, use extract:

Terminal window
New-Item -ItemType Directory -Path 'D:\Exports' -Force | Out-Null
.\nbtcli.exe extract 'D:\WorldCopy' --unique --output 'D:\Exports\world-text-unique.json'

Now that you can safely inspect NBT nodes and scan world text, continue to Safe Editing and Recovery to learn how to preview and apply changes safely.