Install and Inspect
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:
Get-FileHash .\nbtcli-win-x64.zip -Algorithm SHA256Get-Content .\SHA256SUMS.txtExtract 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:
Expand-Archive -Path .\nbtcli-win-x64.zip -DestinationPath .\nbtcliSet-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.
2. Check Version and Command Help
Section titled “2. Check Version and Command Help”Run --version and --help to confirm the binary launches cleanly:
.\nbtcli.exe --version.\nbtcli.exe --helpExample 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>:
.\nbtcli.exe help get --ui-locale en-US.\nbtcli.exe help translate --ui-locale en-US3. Prepare a World Copy
Section titled “3. Prepare a World Copy”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.
4. Inspect a Single Value with get
Section titled “4. Inspect a Single Value with get”Use get to read a specific NBT tag, region chunk, or datapack JSON property.
Read DataVersion from level.dat
Section titled “Read DataVersion from level.dat”.\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:
.\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --typesOther Ways to Select Targets with get
Section titled “Other Ways to Select Targets with get”# 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.sword5. Explore World Structure with list and search
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:
.\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):
.\nbtcli.exe list 'D:\WorldCopy' --path 'region/r.0.0.mca' --limit 20.\nbtcli.exe search 'D:\WorldCopy' --path level.dat --name Spawn --limit 106. 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:
# 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]
scanstores a fast, rebuildable cache outside your world folder (under%LOCALAPPDATA%\nbtcli\scan\<world-id>by default, or in a custom--cache-rootoutside the world). Pass--refreshto force re-parsing, or--no-cacheto 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:
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.