Command Reference
This page lists every registered command and subcommand in NBTExplorerCLI (nbtcli.exe), aligned with the verified command surface contract (nbtcli.command-surface, version 1).
Global CLI Rules
Section titled “Global CLI Rules”For subcommand help, append --help to its invocation, for example nbtcli translate start --help.
- Single JSON Output: Every command writes exactly one newline-delimited UTF-8 JSON envelope (
schemaFamily: "nbtcli.cli",schemaVersion: 1) tostdout. - Global Display Locale (
--ui-locale): Pass--ui-locale zh-TW(default) or--ui-locale en-USbefore or after any command to select the language of error and help messages. It does not affect translation source/target locales (--source-language,--target-language,--lang,--original-lang,--target-lang). - Option Syntax: Value options accept
--option valueor--option=value. Boolean flags take no value. Use--to end option parsing when a path begins with a hyphen. - Root and Option Aliases:
- Root
--helpand-hinvokehelp. - Root
--versionand-vinvokeversion. -his accepted as--helpon any command.
- Root
File and Standard Input (-) Schemas
Section titled “File and Standard Input (-) Schemas”Commands that read structured JSON from a file or standard input (-) validate the exact schemaFamily and schemaVersion before executing:
| Input Schema Family | Accepted By |
|---|---|
nbtcli.typed-nbt |
set --value <json> or set --value-file <file|-> |
nbtcli.operations |
batch <file|-> --world <dir> or plan <dir> --request <file|-> |
nbtcli.patch-plan |
apply <dir> --plan <file|-> |
nbtcli.session-reply |
translate submit --reply <file|-> or translate advance --reply <file|-> |
nbtcli.session-command |
translate jump, note, glossary, or reset via --request <file|-> |
nbtcli.agent-questionnaire |
agent submit <dir> --request <file|-> |
Inspection and Query Commands
Section titled “Inspection and Query Commands”Read-only commands for checking version, command options, NBT tags, region chunks, and datapack JSON files.
nbtcli help [command]Safe to InspectDisplays available commands, subcommands, and exact accepted options in JSON.
--help--ui-localenbtcli versionSafe to InspectPrints the product name (nbtcli) and release version (1.0.0).
--help--ui-localenbtcli get <world-or-file>Safe to InspectReads a specific NBT tag, JSON property, or chunk payload without changing any file.
--path--pointer--segments--chunk--dimension--entry--compression--types--help--ui-localenbtcli list <world-or-file>Safe to InspectLists world dimensions and region counts, populated chunks in a region, or immediate child nodes.
--path--pointer--segments--chunk--dimension--entry--compression--types--limit--offset--help--ui-localenbtcli search <world-or-file>Safe to InspectSearches NBT or JSON subtrees by value text, key name, or tag type with pagination.
--path--pointer--segments--chunk--dimension--entry--compression--types--limit--offset--query--name--type--help--ui-localeWorld Text Scanning and Validation Commands
Section titled “World Text Scanning and Validation Commands”Read-only commands for indexing world text occurrences, extracting strings, validating world sources, and checking supported Minecraft profiles.
nbtcli scan <world>Safe to InspectScans the world for translatable or inspectable text across signs, books, items, entities, command blocks, and datapacks.
--path--dimension--region--types--limit--offset--summary--show-items--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-localenbtcli extract <world>Safe to InspectExtracts decoded text entries and their exact source locations, optionally deduplicating identical strings or filtering by regex.
--path--dimension--region--types--limit--offset--all--unique--match-pattern--output--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-localenbtcli validate <world>Safe to InspectVerifies world catalog headers (--quick) or decodes all selected text sources to detect corrupt or unsupported data early.
--path--dimension--region--types--limit--offset--quick--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-localenbtcli capabilitiesSafe to InspectLists registered CLI commands and declared support levels for each Minecraft DataVersion profile.
--help--ui-localeEditing, Backup, and Recovery Commands
Section titled “Editing, Backup, and Recovery Commands”Commands for previewing changes, applying verified plans offline, managing backups, and recovering from interrupted writes.
nbtcli set <world> --path <rel-path> (--value <json> | --value-file <file>)Preview OnlyReplaces a specific NBT value using explicit typed-nbt JSON. Runs in preview mode by default unless --apply --world-offline is given.
--path--pointer--segments--chunk--dimension--compression--value--value-file--operation-id--apply--world-offline--state-root--output--help--ui-localenbtcli batch <file-or-dash> --world <world>Preview OnlyPreviews or applies a batch of versioned typed operations against a world.
--world--apply--world-offline--state-root--output--help--ui-localenbtcli plan <world> --request <file-or-dash>Preview OnlyBuilds and verifies an immutable patch-plan from an operations request without modifying the world.
--request--state-root--output--help--ui-localenbtcli apply <world> --plan <file-or-dash> --world-offlineModifies World SaveExecutes a verified patch-plan with automatic preimage backup, staging, journal tracking, and readback verification.
--plan--world-offline--state-root--output--help--ui-localenbtcli status <world> --plan-hash <hash>Safe to InspectInspects the journal and receipt state of a plan to determine whether a write finished, needs recovery, or rolled back.
--plan-hash--state-root--output--help--ui-localenbtcli recover <world> --plan-hash <hash> --world-offlineModifies World SaveSafely completes an interrupted apply or rolls back to the verified pre-edit state (--rollback).
--plan-hash--world-offline--rollback--state-root--output--help--ui-localenbtcli backup <world> [--suffix <name>]Safe to InspectCaptures a hash-verified, content-addressed snapshot of the world (or a single --path) inside the external state repository.
--path--suffix--state-root--output--help--ui-localenbtcli restore <world> --manifest-hash <hash>Preview OnlyPreviews or applies a restoration from a verified backup manifest, even if current world files are damaged or missing.
--manifest-hash--path--apply--world-offline--state-root--output--help--ui-localeTranslation, Conversion, and Agent Commands
Section titled “Translation, Conversion, and Agent Commands”Root commands for one-shot key conversion, paginated translation sessions, and external assistant preferences.
nbtcli convert <world> --lang <locale>Preview OnlyConverts in-world literal text into translation keys and bundles the matching language file/resource pack.
--lang--prefix--keepdup--no-backup--language-output--apply--world-offline--state-root--output--path--dimension--region--types--match-pattern--workers--verbose--help--ui-localenbtcli translate <subcommand> <world> [options]Preview OnlyManages paginated translation sessions, terminology glossaries, translation plans, resource packs, and completion sealing.
--help--ui-localenbtcli agent <setup|submit|status|help> <world>Preview OnlyConfigures default source/target languages and page-size preferences for external translation tools or AI assistants.
--help--ui-localetranslate Subcommands Reference
Section titled “translate Subcommands Reference”All translate subcommands (except translate help) take the target <world> path and accept --state-root, --output, --help, and --ui-locale.
nbtcli translate start <world>Preview OnlyScans the selected scope and opens a new translation session with paginated text slots.
--session-id--state-root--output--help--source-language--target-language--operation-id--page-size--page-bytes--match-pattern--types--path--dimension--region--standalone--no-group--ui-localenbtcli translate status <world>Safe to InspectChecks session translation progress and verifies whether the world files have changed since the session started.
--session-id--state-root--output--help--ui-localenbtcli translate export <world>Safe to InspectExports a specific page of text slots along with a structured reply template.
--session-id--state-root--output--help--page--operation-id--no-group--ui-localenbtcli translate advance <world>Preview OnlyOptionally validates and saves a completed reply file, then returns the next pending page.
--session-id--state-root--output--help--reply--no-group--ui-localenbtcli translate submit <world>Preview OnlyValidates and saves a translated reply JSON file (or stdin) for the current revision and returns the next pending page.
--session-id--state-root--output--help--reply--no-group--ui-localenbtcli translate get <world>Safe to InspectInspects a single translation slot, its source text, format rules, and current translated value.
--session-id--state-root--output--help--slot-id--ui-localenbtcli translate jump <world>Preview OnlyUpdates the manual page pointer using a versioned session-command request.
--session-id--state-root--output--help--request--ui-localenbtcli translate note <world>Preview OnlyReads or updates translator context notes attached to the session.
--session-id--state-root--output--help--request--limit--offset--ui-localenbtcli translate glossary <world>Preview OnlyReads or updates the session terminology glossary to keep recurring names consistent.
--session-id--state-root--output--help--request--limit--offset--ui-localenbtcli translate reset <world>Preview OnlyPreviews or confirms resetting selected slots back to pending while preserving historical records.
--session-id--state-root--output--help--request--confirm--ui-localenbtcli translate groups <world>Safe to InspectLists context groups of related text occurrences across the world.
--session-id--state-root--output--help--limit--offset--ui-localenbtcli translate memory <world>Safe to InspectQueries compatible translation candidates from other local sessions.
--session-id--state-root--output--help--slot-id--source-sessions--glossary-version--limit--offset--ui-localenbtcli translate plan <world>Preview OnlyGenerates a verified world PatchPlan in either --direct (replace text in-place) or --keys (convert to translation keys + language file) mode.
--session-id--state-root--output--help--direct--keys--prefix--language-output--revision--operation-id--synchronize-references--ui-localenbtcli translate export-lang <world>Preview OnlyPreviews or writes standalone original/target language JSON files from frozen session values without modifying gameplay NBT.
--session-id--state-root--output--help--revision--original-lang--target-lang--prefix--plan-output--apply--world-offline--ui-localenbtcli translate create-pack <world>Preview OnlyPreviews or builds a standalone Minecraft resource pack (ZIP or directory), optionally merging with an existing pack.
--session-id--state-root--output--help--revision--original-lang--target-lang--prefix--plan-output--apply--world-offline--name--format--merge--pack-format--ui-localenbtcli translate seal <world>Preview OnlyMarks the translation session as completed after verifying the durable world apply receipt and plan hash.
--session-id--state-root--output--help--revision--operation-id--plan-hash--ui-localenbtcli translate helpSafe to Inspect--help--ui-localeagent Subcommands Reference
Section titled “agent Subcommands Reference”nbtcli agent setup <world>Preview Only--state-root--output--help--source-language--target-language--operation-id--ui-localenbtcli agent submit <world>Preview Only--state-root--output--help--request--ui-localenbtcli agent status <world>Safe to Inspect--state-root--output--help--ui-localenbtcli agent helpSafe to Inspect--help--ui-locale