Skip to content

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

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) to stdout.
  • Global Display Locale (--ui-locale): Pass --ui-locale zh-TW (default) or --ui-locale en-US before 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 value or --option=value. Boolean flags take no value. Use -- to end option parsing when a path begins with a hyphen.
  • Root and Option Aliases:
    • Root --help and -h invoke help.
    • Root --version and -v invoke version.
    • -h is accepted as --help on any command.

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

Read-only commands for checking version, command options, NBT tags, region chunks, and datapack JSON files.

nbtcli help [command]Safe to Inspect

Displays available commands, subcommands, and exact accepted options in JSON.

Required InputsNone (optional command or subcommand name)
Result and Next StepReturns usage and option list. Run before constructing scripts or unfamiliar commands.
Accepted Options
--help--ui-locale
nbtcli versionSafe to Inspect

Prints the product name (nbtcli) and release version (1.0.0).

Required InputsNone
Result and Next StepConfirms binary integrity after extracting the release ZIP.
Accepted Options
--help--ui-locale
nbtcli get <world-or-file>Safe to Inspect

Reads a specific NBT tag, JSON property, or chunk payload without changing any file.

Required InputsTarget world folder or standalone NBT/JSON/archive file
Result and Next StepPass --types to get reversible typed-nbt JSON and exact source addresses for later set/batch edits.
Accepted Options
--path--pointer--segments--chunk--dimension--entry--compression--types--help--ui-locale
nbtcli list <world-or-file>Safe to Inspect

Lists world dimensions and region counts, populated chunks in a region, or immediate child nodes.

Required InputsTarget world folder, NBT file, or region file
Result and Next StepUse to explore world layout before running targeted get, search, or scan commands.
Accepted Options
--path--pointer--segments--chunk--dimension--entry--compression--types--limit--offset--help--ui-locale

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

Scans the world for translatable or inspectable text across signs, books, items, entities, command blocks, and datapacks.

Required InputsTarget world folder
Result and Next StepReports per-source status and text counts. Follow with extract or translate start.
Accepted Options
--path--dimension--region--types--limit--offset--summary--show-items--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-locale
nbtcli extract <world>Safe to Inspect

Extracts decoded text entries and their exact source locations, optionally deduplicating identical strings or filtering by regex.

Required InputsTarget world folder
Result and Next StepExports inspection JSON to stdout or a new file outside the world via --output.
Accepted Options
--path--dimension--region--types--limit--offset--all--unique--match-pattern--output--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-locale
nbtcli validate <world>Safe to Inspect

Verifies world catalog headers (--quick) or decodes all selected text sources to detect corrupt or unsupported data early.

Required InputsTarget world folder
Result and Next StepDistinguishes clean sources, unsupported features (exit 4), and corrupted files (exit 5).
Accepted Options
--path--dimension--region--types--limit--offset--quick--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-locale
nbtcli capabilitiesSafe to Inspect

Lists registered CLI commands and declared support levels for each Minecraft DataVersion profile.

Required InputsNone
Result and Next StepCheck before working on a new Minecraft version to see read/extract/plan/write/recover declarations.
Accepted Options
--help--ui-locale

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 Only

Replaces a specific NBT value using explicit typed-nbt JSON. Runs in preview mode by default unless --apply --world-offline is given.

Required InputsTarget world, --path, node selector (--pointer or --segments), and --value / --value-file (typed-nbt JSON)
Result and Next StepPreview outputs a patch-plan; save it with --output and commit via apply, or pass --apply --world-offline.
Accepted Options
--path--pointer--segments--chunk--dimension--compression--value--value-file--operation-id--apply--world-offline--state-root--output--help--ui-locale
nbtcli batch <file-or-dash> --world <world>Preview Only

Previews or applies a batch of versioned typed operations against a world.

Required InputsOperations JSON file (or - for stdin) and --world <world>
Result and Next StepPreviews by default; pass --output to save the plan or --apply --world-offline to commit.
Accepted Options
--world--apply--world-offline--state-root--output--help--ui-locale
nbtcli plan <world> --request <file-or-dash>Preview Only

Builds and verifies an immutable patch-plan from an operations request without modifying the world.

Required InputsTarget world and --request <operations-file-or-dash>
Result and Next StepSave the plan with --output <plan.json> and inspect before running apply.
Accepted Options
--request--state-root--output--help--ui-locale
nbtcli apply <world> --plan <file-or-dash> --world-offlineModifies World Save

Executes a verified patch-plan with automatic preimage backup, staging, journal tracking, and readback verification.

Required InputsTarget world, --plan <plan.json>, and --world-offline
Result and Next StepReturns a durable apply receipt. If interrupted (exit 7), check status and run recover.
Accepted Options
--plan--world-offline--state-root--output--help--ui-locale
nbtcli status <world> --plan-hash <hash>Safe to Inspect

Inspects the journal and receipt state of a plan to determine whether a write finished, needs recovery, or rolled back.

Required InputsTarget world and --plan-hash <sha256> (with the same --state-root)
Result and Next StepRead-only check; use its output to decide whether to run recover or recover --rollback.
Accepted Options
--plan-hash--state-root--output--help--ui-locale
nbtcli recover <world> --plan-hash <hash> --world-offlineModifies World Save

Safely completes an interrupted apply or rolls back to the verified pre-edit state (--rollback).

Required InputsTarget world, --plan-hash <sha256>, and --world-offline
Result and Next StepRestores world consistency and emits a terminal receipt (exit 0 for forward completion, exit 8 for rollback).
Accepted Options
--plan-hash--world-offline--rollback--state-root--output--help--ui-locale
nbtcli backup <world> [--suffix <name>]Safe to Inspect

Captures a hash-verified, content-addressed snapshot of the world (or a single --path) inside the external state repository.

Required InputsTarget world folder
Result and Next StepRetain the returned manifestHash (and state root) so you can restore at any time.
Accepted Options
--path--suffix--state-root--output--help--ui-locale
nbtcli restore <world> --manifest-hash <hash>Preview Only

Previews or applies a restoration from a verified backup manifest, even if current world files are damaged or missing.

Required InputsTarget world and --manifest-hash <sha256>
Result and Next StepPreviews by default; add --apply --world-offline to write the restored files.
Accepted Options
--manifest-hash--path--apply--world-offline--state-root--output--help--ui-locale

Translation, 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 Only

Converts in-world literal text into translation keys and bundles the matching language file/resource pack.

Required InputsTarget world and --lang <locale> (for example zh_tw or en_us)
Result and Next StepPreviews by default; pass --output to save the plan or --apply --world-offline to commit.
Accepted Options
--lang--prefix--keepdup--no-backup--language-output--apply--world-offline--state-root--output--path--dimension--region--types--match-pattern--workers--verbose--help--ui-locale
nbtcli translate <subcommand> <world> [options]Preview Only

Manages paginated translation sessions, terminology glossaries, translation plans, resource packs, and completion sealing.

Required InputsSubcommand (start, status, export, advance, submit, get, jump, note, glossary, reset, groups, memory, plan, export-lang, create-pack, seal, help)
Result and Next StepStores session progress outside the world; world edits only happen when you apply a generated plan.
Accepted Options
--help--ui-locale
nbtcli agent <setup|submit|status|help> <world>Preview Only

Configures default source/target languages and page-size preferences for external translation tools or AI assistants.

Required InputsSubcommand (setup, submit, status, or help) and target world
Result and Next StepSaves preferences in the external state root; never calls external networks or modifies the world.
Accepted Options
--help--ui-locale

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 Only

Scans the selected scope and opens a new translation session with paginated text slots.

Accepted Options
--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-locale
nbtcli translate status <world>Safe to Inspect

Checks session translation progress and verifies whether the world files have changed since the session started.

Accepted Options
--session-id--state-root--output--help--ui-locale
nbtcli translate export <world>Safe to Inspect

Exports a specific page of text slots along with a structured reply template.

Accepted Options
--session-id--state-root--output--help--page--operation-id--no-group--ui-locale
nbtcli translate advance <world>Preview Only

Optionally validates and saves a completed reply file, then returns the next pending page.

Accepted Options
--session-id--state-root--output--help--reply--no-group--ui-locale
nbtcli translate submit <world>Preview Only

Validates and saves a translated reply JSON file (or stdin) for the current revision and returns the next pending page.

Accepted Options
--session-id--state-root--output--help--reply--no-group--ui-locale
nbtcli translate get <world>Safe to Inspect

Inspects a single translation slot, its source text, format rules, and current translated value.

Accepted Options
--session-id--state-root--output--help--slot-id--ui-locale
nbtcli translate jump <world>Preview Only

Updates the manual page pointer using a versioned session-command request.

Accepted Options
--session-id--state-root--output--help--request--ui-locale
nbtcli translate note <world>Preview Only

Reads or updates translator context notes attached to the session.

Accepted Options
--session-id--state-root--output--help--request--limit--offset--ui-locale
nbtcli translate glossary <world>Preview Only

Reads or updates the session terminology glossary to keep recurring names consistent.

Accepted Options
--session-id--state-root--output--help--request--limit--offset--ui-locale
nbtcli translate reset <world>Preview Only

Previews or confirms resetting selected slots back to pending while preserving historical records.

Accepted Options
--session-id--state-root--output--help--request--confirm--ui-locale
nbtcli translate groups <world>Safe to Inspect

Lists context groups of related text occurrences across the world.

Accepted Options
--session-id--state-root--output--help--limit--offset--ui-locale
nbtcli translate memory <world>Safe to Inspect

Queries compatible translation candidates from other local sessions.

Accepted Options
--session-id--state-root--output--help--slot-id--source-sessions--glossary-version--limit--offset--ui-locale
nbtcli translate plan <world>Preview Only

Generates a verified world PatchPlan in either --direct (replace text in-place) or --keys (convert to translation keys + language file) mode.

Accepted Options
--session-id--state-root--output--help--direct--keys--prefix--language-output--revision--operation-id--synchronize-references--ui-locale
nbtcli translate export-lang <world>Preview Only

Previews or writes standalone original/target language JSON files from frozen session values without modifying gameplay NBT.

Accepted Options
--session-id--state-root--output--help--revision--original-lang--target-lang--prefix--plan-output--apply--world-offline--ui-locale
nbtcli translate create-pack <world>Preview Only

Previews or builds a standalone Minecraft resource pack (ZIP or directory), optionally merging with an existing pack.

Accepted Options
--session-id--state-root--output--help--revision--original-lang--target-lang--prefix--plan-output--apply--world-offline--name--format--merge--pack-format--ui-locale
nbtcli translate seal <world>Preview Only

Marks the translation session as completed after verifying the durable world apply receipt and plan hash.

Accepted Options
--session-id--state-root--output--help--revision--operation-id--plan-hash--ui-locale
nbtcli translate helpSafe to Inspect
Accepted Options
--help--ui-locale
nbtcli agent setup <world>Preview Only
Accepted Options
--state-root--output--help--source-language--target-language--operation-id--ui-locale
nbtcli agent submit <world>Preview Only
Accepted Options
--state-root--output--help--request--ui-locale
nbtcli agent status <world>Safe to Inspect
Accepted Options
--state-root--output--help--ui-locale
nbtcli agent helpSafe to Inspect
Accepted Options
--help--ui-locale