Documentation Overview
NBTExplorerCLI (nbtcli.exe, version 1.0.0) is a self-contained Windows x64 command-line tool built for Minecraft Java Edition worlds. It enables players, adventure map creators, localization teams, and tool developers to inspect NBT data, scan and translate in-world text, generate resource packs, and apply verified offline edits.
Understanding Operation Safety Levels
Section titled “Understanding Operation Safety Levels”Every guide and command in this documentation displays one of three plain-language safety labels so you always know whether an action can affect your Minecraft save files:
| Safety Badge | What It Means for Your World Save |
|---|---|
| Safe to Inspect | Reads files or checks external status logs only. Your Minecraft world folder is never modified. |
| Preview Only | Creates a change plan (nbtcli.patch-plan) or saves translation progress in an external directory outside your world. Your world files remain untouched. |
| Modifies World Save | Writes changes to your world folder. Always work on a world copy, close Minecraft and other editors first, and pass --world-offline. |
Six Core Workflows
Section titled “Six Core Workflows”Use the following guides in order to learn the complete workflow from first inspection to crash-safe editing and map localization:
- Install and Inspect
Verify the release ZIP SHA-256 checksum, extract the self-contained package, run
--versionand--help, and execute your first read-onlyget,list,search, andscancommands on a world copy. - Safe Editing and Recovery
Select exact NBT nodes with JSON Pointers or typed segments, preview changes with
set,batch, orplan, apply plans offline withapply --world-offline, and recover or roll back interrupted writes usingstatusandrecover. - Translation Workflow
Create paginated translation sessions (
translate start), export pages (export), submit validated replies (submit/advance), manage notes and glossaries, and complete world translation withplan,apply, andseal. - Resource Packs and References
Understand the difference between direct in-world text replacement (
--direct), translation key conversion (--keysandconvert), standalone language/resource pack exports (export-lang,create-pack), and reference synchronization (--synchronize-references). - Backups and State Files
Create and verify content-addressed world backups (
backupandrestore), and understand how external scan caches, sessions, object stores, and recovery journals are organized outside your world directory. - Support Scope and Troubleshooting
Check supported Minecraft Java Edition
DataVersionprofiles, inspect exit codes (0through8and130), understand parser verification versus live in-game verification boundaries, and resolve common errors.
Need to look up a specific command or option quickly? Go straight to the Command Reference.
One Predictable JSON Response Format
Section titled “One Predictable JSON Response Format”Every invocation of nbtcli.exe writes exactly one newline-delimited UTF-8 JSON object to standard output (stdout):
{ "schemaFamily": "nbtcli.cli", "schemaVersion": 1, "success": true, "command": "version", "outcome": "Success", "data": { "product": "nbtcli", "version": "1.0.0" }, "error": null}Interface Language vs. Translation Languages
Section titled “Interface Language vs. Translation Languages”NBTExplorerCLI strictly separates the language of CLI messages from the languages of your Minecraft world text:
- CLI Interface Language (
--ui-locale): Acceptszh-TW(default) oren-USbefore or after any command. It controls human-readableerror.messageand instruction text without changing JSON keys, machine error codes, or world data. - World & Resource Languages: Flags such as
--source-language,--target-language,--lang,--original-lang, and--target-langcontrol how Minecraft text and resource pack language files (such asen_usandzh_tw) are processed.
License and Third-Party Notices
Section titled “License and Third-Party Notices”NBTExplorerCLI is licensed under the MIT License (LICENSE in the repository and release archive). Bundled third-party components retain their respective terms and notices:
- SharpZipLib (
licenses/SharpZipLib.md) - Unicode Character Database (
licenses/Unicode.md) - .NET Runtime Licenses and Third-Party Notices (
licenses/dotnet-LICENSE.txtandlicenses/dotnet-THIRD-PARTY-NOTICES.txtin the Windows x64 release package)
Minecraft game assets and user-created worlds remain subject to their respective owners’ terms and licenses.