跳到內容

CLI 命令完整參考

本頁完整列出 NBTExplorerCLI(nbtcli.exe)註冊的所有命令與子命令,內容與自動化測試驗證的機器命令表(nbtcli.command-surface 版本 1)完全同步。

  • 單行 JSON 標準輸出:所有指令皆會在標準輸出(stdout)回傳單一 UTF-8 JSON 信封物件(schemaFamily: "nbtcli.cli",schemaVersion: 1)。
  • 介面顯示語言(--ui-locale):可於指令前後加上 --ui-locale zh-TW(預設)或 --ui-locale en-US,僅改變說明與錯誤訊息文字,不影響地圖翻譯與資源包的語言設定(--source-language、--target-language、--lang、--original-lang、--target-lang)。
  • 參數語法:帶值參數支援 --option value 或 --option=value 兩種寫法;布林旗標不帶值。若檔案路徑以連字號開頭,可使用 -- 結束旗標解析。
  • 支援的簡寫別名(Aliases):
    • 根命令 --help 與 -h 等同於 help。
    • 根命令 --version 與 -v 等同於 version。
    • 所有命令皆支援以 -h 查詢該命令的 --help 說明。

結構化檔案與標準輸入(-)格式對照

Section titled “結構化檔案與標準輸入(-)格式對照”

當指令透過檔案路徑或標準輸入(-)讀取 JSON 時,皆會先驗證對應的 schemaFamily 與 schemaVersion:

輸入 JSON Schema Family 使用該格式的指令與參數
nbtcli.typed-nbt set --value <json> 或 set --value-file <檔案|->
nbtcli.operations batch <檔案|-> --world <世界目錄> 或 plan <世界目錄> --request <檔案|->
nbtcli.patch-plan apply <世界目錄> --plan <檔案|->
nbtcli.session-reply translate submit --reply <檔案|-> 或 translate advance --reply <檔案|->
nbtcli.session-command translate jump、note、glossary 或 reset 搭配 --request <檔案|->
nbtcli.agent-questionnaire agent submit <世界目錄> --request <檔案|->

查閱與搜尋命令(Inspection & Query)

Section titled “查閱與搜尋命令(Inspection & Query)”

用於檢查版本、查詢參數說明、讀取 NBT 節點、檢視區塊與搜尋資料包 JSON 的唯讀命令。

nbtcli help [command]安全查閱:不改存檔

以 JSON 格式列出可用的命令、子命令與接受的參數選項。

必要輸入參數無(可選填命令或子命令名稱)
執行結果與下一步回傳用法與參數清單。在執行不熟悉的指令前可先查詢。
支援的參數選項
--help--ui-locale
nbtcli version安全查閱:不改存檔

輸出產品名稱(nbtcli)與目前版本號(1.0.0)。

必要輸入參數無
執行結果與下一步用於解壓縮發行包後確認執行檔可正常啟動。
支援的參數選項
--help--ui-locale
nbtcli get <world-or-file>安全查閱:不改存檔

讀取指定的 NBT 節點、JSON 屬性或區塊資料,不修改任何檔案。

必要輸入參數目標世界資料夾,或單一 NBT / JSON / 壓縮檔路徑
執行結果與下一步加上 --types 可取得完整型別資訊(typed-nbt)與精確來源位址,供後續 set 或 batch 編輯使用。
支援的參數選項
--path--pointer--segments--chunk--dimension--entry--compression--types--help--ui-locale
nbtcli list <world-or-file>安全查閱:不改存檔

列出世界的維度與區塊檔數量、區塊檔內已生成的區塊座標,或指定節點的直屬子項目。

必要輸入參數目標世界資料夾、NBT 檔案或區塊檔(.mca)
執行結果與下一步適合在執行 get、search 或 scan 之前,先盤點世界結構與維度清單。
支援的參數選項
--path--pointer--segments--chunk--dimension--entry--compression--types--limit--offset--help--ui-locale

世界文字掃描與驗證命令(Scanning & Validation)

Section titled “世界文字掃描與驗證命令(Scanning & Validation)”

用於掃描世界文字、抽取字串、驗證檔案完整性與查詢支援版本的唯讀命令。

nbtcli scan <world>安全查閱:不改存檔

掃描世界中的告示牌、書本、物品、實體、指令方塊與資料包文字,並建立外部快取索引。

必要輸入參數目標世界資料夾
執行結果與下一步回報各來源檔案狀態與文字統計,後續可銜接 extract 或 translate start。
支援的參數選項
--path--dimension--region--types--limit--offset--summary--show-items--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-locale
nbtcli extract <world>安全查閱:不改存檔

抽取解碼後的文字與精確來源位址,支援以 --unique 合併相同文字預覽或用正規表示式篩選。

必要輸入參數目標世界資料夾
執行結果與下一步將結果輸出至標準輸出,或透過 --output 另存為世界資料夾外的新檔案。
支援的參數選項
--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>安全查閱:不改存檔

檢查世界目錄結構(--quick)或完整解碼所選文字來源,提前發現損壞或不支援的資料格式。

必要輸入參數目標世界資料夾
執行結果與下一步明確區分正常檔案、尚未支援的格式(退出碼 4)與損壞無法讀取的檔案(退出碼 5)。
支援的參數選項
--path--dimension--region--types--limit--offset--quick--refresh--no-cache--cache-root--workers--verbose--debug--help--ui-locale
nbtcli capabilities安全查閱:不改存檔

列出已註冊的命令清單,以及各 Minecraft DataVersion 支援組合的宣告支援程度。

必要輸入參數無
執行結果與下一步在處理新版本存檔前可先查詢 read、extract、plan、write 與 recover 的支援狀態。
支援的參數選項
--help--ui-locale

安全編輯、備份與復原命令(Editing, Backup & Recovery)

Section titled “安全編輯、備份與復原命令(Editing, Backup & Recovery)”

用於預覽修改計畫、離線套用變更、建立備份與從中斷狀態復原世界的命令。

nbtcli set <world> --path <rel-path> (--value <json> | --value-file <file>)預覽模式:僅產出計畫

以明確型別的 typed-nbt JSON 替換指定節點的值。預設為預覽模式,不會直接修改世界,除非加上 --apply --world-offline。

必要輸入參數目標世界、--path、節點選擇器(--pointer 或 --segments)以及 --value 或 --value-file(typed-nbt 格式)
執行結果與下一步預覽會產生修補計畫(patch-plan),可用 --output 存成檔案再交由 apply 寫入,或直接加上 --apply --world-offline。
支援的參數選項
--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>預覽模式:僅產出計畫

對目標世界預覽或批次套用多筆結構化編輯操作(nbtcli.operations)。

必要輸入參數操作清單 JSON 檔案(或 - 代表標準輸入)與 --world <world>
執行結果與下一步預設僅預覽計畫;可搭配 --output 匯出計畫檔,或搭配 --apply --world-offline 離線寫入。
支援的參數選項
--world--apply--world-offline--state-root--output--help--ui-locale
nbtcli plan <world> --request <file-or-dash>預覽模式:僅產出計畫

根據操作請求建立並驗證不可變的修補計畫(patch-plan),完全不更動世界存檔。

必要輸入參數目標世界與 --request <操作請求檔或標準輸入>
執行結果與下一步使用 --output <plan.json> 儲存計畫檔,檢查無誤後再執行 apply。
支援的參數選項
--request--state-root--output--help--ui-locale
nbtcli apply <world> --plan <file-or-dash> --world-offline修改存檔:請先關遊戲並備份

執行已驗證的修補計畫,自動建立寫前備份、暫存驗證、日誌紀錄(Journal)與寫後讀回校驗。

必要輸入參數目標世界、--plan <計畫檔> 與 --world-offline
執行結果與下一步回傳寫入回執(Receipt)。若寫入中斷(退出碼 7),請先查閱 status 再執行 recover。
支援的參數選項
--plan--world-offline--state-root--output--help--ui-locale
nbtcli status <world> --plan-hash <hash>安全查閱:不改存檔

查詢特定計畫的執行日誌與回執狀態,判斷寫入是否已完成、需要復原,或已回滾。

必要輸入參數目標世界與 --plan-hash <計畫雜湊值>(若原本有自訂 --state-root 需一併帶入)
執行結果與下一步純唯讀檢查;根據回傳狀態決定要執行 recover 繼續完成,或加上 --rollback 退回原狀。
支援的參數選項
--plan-hash--state-root--output--help--ui-locale
nbtcli recover <world> --plan-hash <hash> --world-offline修改存檔:請先關遊戲並備份

安全接續完成被中斷的寫入作業,或加上 --rollback 將世界完整還原至修改前的狀態。

必要輸入參數目標世界、--plan-hash <計畫雜湊值> 與 --world-offline
執行結果與下一步確保世界檔案恢復一致狀態並產出最終回執(繼續完成為退出碼 0,回滾至原狀為退出碼 8)。
支援的參數選項
--plan-hash--world-offline--rollback--state-root--output--help--ui-locale
nbtcli backup <world> [--suffix <name>]安全查閱:不改存檔

在外部狀態目錄中建立經雜湊驗證的世界快照(亦可透過 --path 指定單一檔案),不更動世界本身。

必要輸入參數目標世界資料夾
執行結果與下一步請保存回傳的 manifestHash(以及使用的 state-root),以便隨時透過 restore 還原。
支援的參數選項
--path--suffix--state-root--output--help--ui-locale
nbtcli restore <world> --manifest-hash <hash>預覽模式:僅產出計畫

從已驗證的備份清單預覽或還原世界檔案,即使目前世界內的目標檔案已損壞或遺失也能修復。

必要輸入參數目標世界與 --manifest-hash <備份清單雜湊值>
執行結果與下一步預設為預覽模式;確認無誤後加上 --apply --world-offline 即可實際還原檔案。
支援的參數選項
--manifest-hash--path--apply--world-offline--state-root--output--help--ui-locale

地圖翻譯、轉換與外部助手設定命令(Translation & Agent)

Section titled “地圖翻譯、轉換與外部助手設定命令(Translation & Agent)”

用於單次翻譯鍵轉換、分頁式翻譯工作階段以及外部翻譯助手偏好設定的根命令。

nbtcli convert <world> --lang <locale>預覽模式:僅產出計畫

將世界內的原始文字結構化轉換為翻譯鍵(Translation Keys),並同步產生對應的語言檔與資源包。

必要輸入參數目標世界與 --lang <語言代碼>(例如 zh_tw 或 en_us)
執行結果與下一步預設為預覽模式;可透過 --output 匯出計畫,或加上 --apply --world-offline 直接完成轉換。
支援的參數選項
--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]預覽模式:僅產出計畫

管理分頁式地圖翻譯工作階段、術語表、翻譯計畫生成、獨立資源包匯出與完成封存(seal)。

必要輸入參數子命令(start、status、export、advance、submit、get、jump、note、glossary、reset、groups、memory、plan、export-lang、create-pack、seal、help)
執行結果與下一步所有翻譯進度皆儲存在世界資料夾外;唯有將產出的計畫交由 apply 執行時才會修改世界。
支援的參數選項
--help--ui-locale
nbtcli agent <setup|submit|status|help> <world>預覽模式:僅產出計畫

建立與管理外部翻譯工具或 AI 助手的預設來源/目標語言及每頁筆數偏好設定。

必要輸入參數子命令(setup、submit、status 或 help)與目標世界
執行結果與下一步偏好設定儲存於外部狀態目錄,不會主動連網,也不會修改任何世界檔案。
支援的參數選項
--help--ui-locale

除 translate help 外,所有 translate 子命令皆需指定目標 <world> 路徑,並支援 --state-root、--output、--help 與 --ui-locale。

nbtcli translate start <world>預覽模式:僅產出計畫

掃描指定範圍並建立新的翻譯工作階段,將世界文字切分為可分頁處理的翻譯槽位(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-locale
nbtcli translate status <world>安全查閱:不改存檔

查看目前的翻譯進度,並檢查世界檔案自工作階段建立以來是否曾被外部修改。

支援的參數選項
--session-id--state-root--output--help--ui-locale
nbtcli translate export <world>安全查閱:不改存檔

匯出指定頁碼的待譯文字與結構化回覆範本(Reply Template)。

支援的參數選項
--session-id--state-root--output--help--page--operation-id--no-group--ui-locale
nbtcli translate advance <world>預覽模式:僅產出計畫

可選擇同時提交並驗證已完成的回覆檔,接著自動回傳下一個待處理的分頁。

支援的參數選項
--session-id--state-root--output--help--reply--no-group--ui-locale
nbtcli translate submit <world>預覽模式:僅產出計畫

驗證並儲存翻譯回覆 JSON(支援檔案或標準輸入),更新工作階段版本號並回傳下一頁。

支援的參數選項
--session-id--state-root--output--help--reply--no-group--ui-locale
nbtcli translate get <world>安全查閱:不改存檔

查詢單一翻譯槽位(Slot)的原文、格式限制與目前儲存的譯文。

支援的參數選項
--session-id--state-root--output--help--slot-id--ui-locale
nbtcli translate jump <world>預覽模式:僅產出計畫

透過版本化的 session-command 請求切換目前手動檢視的目標頁碼。

支援的參數選項
--session-id--state-root--output--help--request--ui-locale
nbtcli translate note <world>預覽模式:僅產出計畫

查閱或新增工作階段內的譯者備註與背景說明。

支援的參數選項
--session-id--state-root--output--help--request--limit--offset--ui-locale
nbtcli translate glossary <world>預覽模式:僅產出計畫

查閱或更新專有名詞術語表,確保地圖內重複出現的人名、地名與物品譯名一致。

支援的參數選項
--session-id--state-root--output--help--request--limit--offset--ui-locale
nbtcli translate reset <world>預覽模式:僅產出計畫

預覽或確認將指定的槽位重置回待翻譯狀態(保留歷史紀錄,不會刪除已寫入世界的檔案)。

支援的參數選項
--session-id--state-root--output--help--request--confirm--ui-locale
nbtcli translate groups <world>安全查閱:不改存檔

分頁列出世界內具相同語境關聯的文字群組。

支援的參數選項
--session-id--state-root--output--help--limit--offset--ui-locale
nbtcli translate memory <world>安全查閱:不改存檔

從本機其他翻譯工作階段中查詢相容的歷史翻譯記憶候選詞。

支援的參數選項
--session-id--state-root--output--help--slot-id--source-sessions--glossary-version--limit--offset--ui-locale
nbtcli translate plan <world>預覽模式:僅產出計畫

根據已完成的翻譯產生修補計畫:可選擇 --direct(直接替換世界文字)或 --keys(轉為翻譯鍵並附加語言檔)。

支援的參數選項
--session-id--state-root--output--help--direct--keys--prefix--language-output--revision--operation-id--synchronize-references--ui-locale
nbtcli translate export-lang <world>預覽模式:僅產出計畫

從工作階段匯出獨立的原文/譯文語言檔(.json),不修改世界內的遊戲 NBT 資料。

支援的參數選項
--session-id--state-root--output--help--revision--original-lang--target-lang--prefix--plan-output--apply--world-offline--ui-locale
nbtcli translate create-pack <world>預覽模式:僅產出計畫

預覽或建立獨立的 Minecraft 資源包(ZIP 或資料夾格式),支援與既有資源包安全合併(--merge)。

支援的參數選項
--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>預覽模式:僅產出計畫

在確認世界已完成 apply 寫入並核對 plan-hash 後,將翻譯工作階段正式封存為已完成狀態。

支援的參數選項
--session-id--state-root--output--help--revision--operation-id--plan-hash--ui-locale
nbtcli translate help安全查閱:不改存檔
支援的參數選項
--help--ui-locale

如需個別子命令的說明,請在該子命令後加上 --help,例如 nbtcli translate start --help。

nbtcli agent setup <world>預覽模式:僅產出計畫
支援的參數選項
--state-root--output--help--source-language--target-language--operation-id--ui-locale
nbtcli agent submit <world>預覽模式:僅產出計畫
支援的參數選項
--state-root--output--help--request--ui-locale
nbtcli agent status <world>安全查閱:不改存檔
支援的參數選項
--state-root--output--help--ui-locale
nbtcli agent help安全查閱:不改存檔
支援的參數選項
--help--ui-locale