unity-cli

Unity CLI

除非另有说明要求使用特定版本，否则始终使用最新版本的 Unity CLI。 新版本会定期添加这些文档所述的命令和输出字段，因此使用过时的 CLI 时，可能出现看起来像是文档有误的情况。使用 unity self-update --check --format json 检查。

查找命令：使用搜索，不要用 grep 搜索帮助

切勿使用 grep 过滤 unity --help 或某个命令组的帮助内容。 帮助信息很长，使用 grep 搜索时，可能会漏掉匹配项或其上下文。请使用 CLI 自带的搜索功能：

unity commands --grep license                 # built-in commands, plugins and the connected Editor's Pipeline commands
unity command --query screenshot              # the same search

unity commands --grep <pattern> 和 unity command --query <term> 使用同一套搜索功能。它会搜索 CLI 内置命令、插件目录（无论是否已安装），以及当前已连接 Editor 的 Pipeline 命令，并按最佳匹配优先排序。普通词语可以按任意顺序匹配；正则表达式字符则会被视为正则表达式。每一行都会说明如何运行（invoke）：unity projects link cloud、unity command create_gameobject、unity <id>（针对已安装的插件），或 unity plugin install <id>（针对尚未安装的插件）。在 --format json 下，每一行还会包含 kind（command、plugin、pipeline）、path、description 和 matchedOn（name、description 或 option），因此请依据 invoke 执行，而不要解析表格。

• 使用 unity command --query <term> 搜索指定的 Editor（--project-path <project>）或 Player（--runtime <pattern>，例如 unity command --query screenshot --runtime MyGame）。
• commands --grep 最多等待 Editor 3 秒；command --query 则会一直等待。如果未搜索 Editor，末尾会说明原因（没有 Editor、未能及时获得响应、存在多个 Editor）以及应运行的命令。请先等待 Editor 就绪，使用 unity status --until-ready --project-path <project>：在 Editor 连接之前，没有 Pipeline 结果并不能证明相关命令不存在。

字段和标志：integration-advanced.md。

驱动正在运行的 Unity Editor（如果已打开）

如果这台机器上打开了 Unity Editor，此 CLI 就能实时控制它——创建和修改 GameObject、编辑场景和资源、检查层级结构，以及运行任意 C# 代码——通过项目的 Pipeline 包（com.unity.pipeline）实现。这完全在本地机器上以你自己的用户帐户运行，并作用于你自己打开的 Editor：这不是远程访问，也不会赋予你在终端中本来没有的权限。Editor 可用时，请直接驱动它，而不是手动编辑场景或资源文件。

unity status                    # confirm a connected Editor (look for state "ready")
unity command                   # list the commands the Editor exposes
unity command editor.playmode start   # run one — e.g. enter Play mode
# Run arbitrary C# — e.g. add a GameObject named "Joe" — when the Editor exposes script eval:
unity command script eval 'new UnityEngine.GameObject("Joe");'

要验证正在运行的游戏，而不只是编辑场景？ 进入 Play 模式只是准备工作，并不能证明游戏正在运行： 如果 Editor 未处于焦点状态，或桌面已锁定，画面可能会冻结在第 1 帧，而 unity status 仍会报告游戏正在运行；截图也可能渲染出看似活动的冻结画面，或纯色画面。关于如何按步骤运行游戏、确认游戏确实在推进、捕获视图、读取控制台，以及使用 script eval 实时调整，详见 playmode-verification-loop.md。

同时打开了多个 Editor？请传入 --project-path

每条驱动 Editor 的命令都接受 --project-path <path>。只要可能同时运行多个 Editor，就务必传入此参数——若不传，CLI 会选中项目包含当前目录的 Editor，因此目标会随 shell 的当前工作目录而变化：

unity command editor.playmode start --project-path /path/to/MyProject

如果多个 Editor 使用同一项目（工作树、重复项目、Multiplayer Play Mode 玩家），要固定指定其中一个，unity command、list、job 和 mcp 也接受 --port <number>、--pid <number> 或 --instance <name>（MPPM 实例名称或 vpId）；如果指定值与任何正在运行的 Editor 都不匹配，命令会以退出码 12 结束，并返回 EDITOR_NOT_RUNNING。unity status 实例的 project 字段就是 --project-path 接受的值。对于 unity command/list/job/mcp，如果没有匹配的正在运行项目，命令会失败并返回 AMBIGUOUS_EDITOR，同时列出候选项。详情。 在多个 worktree 或 Agent 会话中工作？每个 worktree 使用一个 Editor。 使用 unity vcs git worktree add <branch> --into <path> 创建每个 worktree，这样就能选择其位置。--into 是可选的：--format json 会报告实际的 worktree 和项目路径；只有人类可读的输出会在主目录路径中隐藏账户名称。如果 Unity 项目位于仓库根目录，则为 <path>；否则为 <path>/<its folder>。使用 unity open <project> 打开该项目自己的 Editor。然后，将所有会访问 Editor 的调用固定到该项目：传入 --project-path <full project path>，或像这样在调用前设置变量：UNITY_PROJECT_PATH=<full project path> unity command editor status。大多数 Agent 工具会在新的 shell 中运行每条命令，因此一次调用中的 export 或单独赋值不会传递到下一次调用。调用时不传路径，unity open、status、command、list、job 和 mcp 会读取该变量。recompile、close 和 mcp configure 不会读取它：请为这些命令传入路径。如果没有设置变量，直接运行 unity open 会打开当前目录对应的项目，也就是你的源代码检出目录。每次都使用同一个完整路径指定该 Editor，包括 unity status --until-ready --project-path <project>。已存在的路径只会匹配该项目，而不带路径的名称也会匹配路径中包含该名称的同级项目。切勿操作项目不属于你自己的代码检出目录（或其 Multiplayer Play Mode 克隆）的 Editor。同级 worktree 中打开的 Editor 会像你的 Editor 一样响应每条命令。向它发送命令会修改该检出目录中的场景，而它的 Play 模式、重新编译和资源导入也会针对该检出目录中的代码运行。如果你自己的 Editor 未打开，请打开它。如果它已关闭，请告知用户，而不要借用正在运行的 Editor。

需要项目包含 com.unity.pipeline 包（Unity 6.0+）——运行一次 unity pipeline install 即可添加。完整详情——启动无头 Editor 并驱动它、使用 unity list 发现工具，以及编写自定义 [CliCommand] 工具——请参阅 integration-advanced.md。

该包还附带一个更深入的 unity-pipeline Agent 技能；对于客户端而言，它在 Library/PackageCache 中不可见——在包含该包的项目中，运行一次 unity skill install <client> --local，即可将其复制到此技能所在目录。

无法连接 / 命令超时？先检查是否处于 Safe Mode。 项目存在 C# 编译错误时，Editor 会以 Safe Mode 启动，此时 Pipeline 包不会加载，因此 unity command、unity list 和 unity recompile 都无法连接（unity status 不会通过连接来判断这一点：它会读取 Editor 的日志并报告 Safe Mode）。具体来说，unity recompile 会报告你在已经运行的 Editor 中引入的错误；但如果 Editor 启动时代码就已损坏，它便不会加载该包，因此无从查询，并会以退出码 7 结束，而不是报告错误。不要退而求其次，盲目编辑文件：运行 unity status（它会报告 Safe Mode 并列出编译错误；使用 --format json 时，错误位于 safeMode.compileErrors），然后修复错误：编译通过后，Editor 就会退出 Safe Mode。完整的恢复流程请参阅 integration-advanced.md → 从 Safe Mode 恢复（因编译错误而无法连接）。

以沙盒化的编码 Agent 身份运行，且 unity status 报告没有实例？ 限制严格的沙盒可能会让 CLI 无法看到实际正在运行的 Editor——不要仅凭这一点就认定 Editor 已关闭。详情请参阅 integration-advanced.md → 沙盒化 Agent 工具可能会隐藏正在运行的 Editor。 调用超时，或 Editor 的生命周期出错？请告知用户，不要默默绕过问题。 首先排除 Safe Mode、沙盒，以及仍在导入或加载的 Editor。在 --format json 输出中读取 errors[0].code，并为较慢的导入延长 --timeout。如果仍然出现以下情况之一，请如实报告：

• 命令超时
• Editor 在 unity status --until-ready 下始终未达到 ready 状态（退出代码 6）
• 连接在命令执行期间中断
• Editor 在你操作期间退出或重启
• unity open 始终未能启动 Editor

不要悄悄循环重试、切换到另一个 Editor，或退而手动编辑场景和资源文件。说明你运行了什么、哪里失败了，以及已经尝试过什么。然后可以提出使用 unity bug --area pipeline-package 提交问题（如果是 Editor 自身退出或未能启动，则使用 --area editor），并先征求用户同意：unity bug 会将日志发送给 Unity，因此切勿自行运行。

安装 CLI（如果尚未安装）

首先检查 CLI 是否可用：

which unity && unity --version

如果未找到，请安装：

macOS / Linux

curl -fsSL https://unity.com/install.sh | bash

Windows（PowerShell）

irm https://unity.com/install.ps1 | iex

安装后，打开新的 shell，让 unity 出现在 PATH 中，然后使用 unity --version 验证。如果安装脚本失败或仍然找不到二进制文件，请告知用户并停止；如果命令本身因权限错误或崩溃而失败，则安装可能已损坏——建议重新运行安装脚本。

---

全局标志

这些标志适用于所有命令：

标志	描述
--format <fmt>	输出格式：human（默认）、json、tsv、ndjson、github。也可通过 UNITY_FORMAT 环境变量设置。
--json	--format json 的全局简写，所有命令均可使用（例如 unity status --json、unity doctor --json）。若同时指定不同的 --format（例如 --json --format tsv），则属于用法错误（退出码为 2）；--json 优先于 UNITY_FORMAT。
--no-banner	隐藏品牌标头——可用于脚本
--no-header	在 tsv 表格中省略表头行。表头行是列名，与 json 行使用的键相同（version、upgradeTo……）。空的 tsv 结果仅包含表头行，因此使用 --no-header 时将没有任何输出。
--no-pager	关闭分页。适用于两个分页器：长列表的外部分页器（unity command、releases、editors、changelog、logs），以及 unity projects list 中的交互式分页器。也可通过 UNITY_NO_PAGER 设置（基于变量是否存在——任何值，包括 0，都会禁用分页）。
--non-interactive	禁用所有交互式提示——可用于 CI
--quiet	隐藏 human 和 tsv 输出中的通知、警告和进度信息。错误和退出码不变。json 输出始终不变；ndjson 输出也不变，但少数列表仍会省略其行（见说明）。
--verbose	失败时打印完整错误详情（堆栈跟踪和原因链）。也可通过 UNITY_VERBOSE 设置。
--proxy <url>	此次调用使用的 HTTP/HTTPS/SOCKS/PAC 代理 URL。也可通过 UNITY_PROXY 设置。其优先级高于标准的 HTTPS_PROXY/HTTP_PROXY/ALL_PROXY 环境变量和已持久化的 proxy.json 设置。
--proxy-disable	禁用此次调用的代理，忽略所有来源（环境变量、已持久化配置、系统设置）。
--log-proxy	为每个出站请求在 proxy-request.json 中记录一条已脱敏的条目——用于复现代理问题。也可通过 UNITY_LOG_PROXY=1 或 proxyRequestLogging 设置启用。
--no-log-proxy	当全局启用代理请求日志记录时，为单次调用选择退出。
--color <auto|always|never>	控制此次调用的彩色输出，覆盖 NO_COLOR/FORCE_COLOR 和 TTY 自动检测。适用于所有会输出 ANSI 内容的界面（帮助、表格、旋转指示器、错误），而不仅是 human 输出。
--no-color	--color never 的简写。命令行中最后出现的 --color/--no-color 生效。

需要以编程方式解析输出时，始终使用 --format json。 如果改为读取 tsv，请按表头名称选择列，而非按位置选择：命令的 tsv 列名和顺序保持不变，添加信息的标志（例如 editors --long）只会在末尾追加列。tsv 中的失败信息会输出到 stderr，因此 stdout 仅包含数据。

--accelerator <host:port> 和 --no-accelerator 不是根级全局标志——它们仅适用于 run、test 和 build，且必须放在命令名称之后。参见 build-run-test.md。

unity projects list 是唯一会在进程内分页的命令。 它每屏显示 10 个项目，并在屏幕之间等待按键；且仅当 stdout 是终端时才会分页。stdout 被重定向时，以及使用 --format json、--format ndjson、--all、--watch 或 --no-pager / UNITY_NO_PAGER 时，分页会关闭。

并非所有机器可读格式都会避开这一分页行为。 只有 json 和 ndjson 使用各自的非交互式渲染；在终端上，--format tsv 和 --format github 会回退到 human 表格，并像 human 一样分页——因此在 TTY 上使用 --format tsv，既不会得到 TSV，也不会得到无分页输出。请重定向 stdout（机器可读格式的常见用法），或传入 --no-pager。请注意，这与下方仅适用于 human 的外部分页器恰恰相反：两种机制在此处有所不同，而 projects list 的行为尤其出人意料。 较长的列表会通过外部分页器翻页，类似 git log。 unity command（不带参数的列表）、unity releases、unity editors、unity changelog 和 unity logs 在终端上会将人类可读的输出通过 less -RFX；如果输出不超过一屏，-F 会自动退出。$UNITY_PAGER 和 $PAGER 可依次覆盖分页器选择，并通过 shell 运行，因此 PAGER="less -S" 可以正常工作；空值会被忽略，而不会被视为禁用分页器。与 projects list 的分页器不同，此分页器仅用于 human 格式，且在标准输出重定向、使用任何机器格式（json、tsv、ndjson、github）、启用 --quiet、TERM=dumb、处于流式模式（editors --watch、logs --follow）、使用带名称的 unity command <name>，或在 unity shell 内时，绝不会启用。分页器故障只会导致无法分页，不会丢失输出：如果 $PAGER 指定的程序不存在，会在启动任何程序之前完成检查；如果分页器启动后退出，则会根据其退出状态将输出重新打印到终端（正常退出表示用户按了 q，输出会丢弃；失败状态则会重新打印）。分页器如果未读取输出就以状态码 0 退出（PAGER=true），则无法与按下 q 区分，因此输出会丢失。仅仅等待的分页器并不算故障；CLI 会等待它。

Unity 品牌页眉（徽标、字标、CLI 版本）会显示在启动界面上：裸命令 unity、unity --help / -h、unity help，以及首次运行的许可提示上方。它仅在 TTY 上显示，最多打印一次；在窄终端、无法使用 Unicode 或设置了 NO_COLOR 时，会简化为紧凑的无颜色文本。管道输出不受影响。使用 --no-banner 可在脚本中隐藏页眉。裸命令 unity 会打印用法信息并以状态码 0 退出。

环境变量

所有 CLI 环境变量都使用 UNITY_ 前缀。CLI 标志始终优先于对应的环境变量。

变量	对应标志	说明
UNITY_FORMAT	--format	输出格式（human、json、tsv、ndjson、github）。HUB_FORMAT 是已弃用的别名。
UNITY_EDITOR_VERSION	--editor-version	Editor 版本（例如 2023.3.0f1、latest、lts）。
UNITY_ARCHITECTURE	--architecture	芯片架构（x86_64、arm64）。
UNITY_PROJECT_PATH	路径参数	未传入路径时使用的项目路径。适用于 open（以及 projects open）、连接到 Editor 的命令 status、command、list、job 和 mcp，以及 pipeline install/upgrade 和 collaboration 命令。recompile、close（以及 projects close）或 mcp configure 不会读取此变量。
UNITY_QUIET	--quiet	隐藏非必要输出。
UNITY_VERBOSE	--verbose	失败时显示完整错误详情。
UNITY_NON_INTERACTIVE	--non-interactive	禁用交互式提示。
UNITY_NO_BANNER	--no-banner	隐藏品牌横幅。
UNITY_NO_PAGER	--no-pager	关闭分页器，包括用于长列表的外部分页器和 unity projects list 的交互式分页器。按是否存在判断：任何值都算，包括 0。
UNITY_PAGER	—	长列表使用的分页器，优先于 $PAGER 和默认值 less -RFX。通过 shell 运行，因此支持标志（less -S）。空值会被忽略，不会禁用分页器。
PAGER	—	与 UNITY_PAGER 相同，仅当后者未设置或为空时才会读取。
LESS / LV / LESSCHARSET / MORE	—	仅在未设置时传递给分页器，默认值分别为 FRX、-c、utf-8 和 FRX。如果区域设置未声明 UTF-8，LESSCHARSET 可确保多字节字形清晰可读；设置 MORE 是因为 macOS/BSD 上的 more 实际上是另一个名称的 less，并会读取 $MORE，因此如果不设置它，即使只有一行，PAGER=more 也会等待按键。
UNITY_RUN_TIMEOUT	--timeout	unity run 的超时时间，单位为秒。
UNITY_TEST_TIMEOUT	--timeout	unity test 的超时时间，单位为秒。
UNITY_CLOUD_ORG	--cloud-org	单次调用使用的当前 Unity Cloud 组织 ID 或名称。
UNITY_CLOUD_PROJECT	--cloud-project	Cloud 项目 ID 或名称（服务帐户需要使用 ID）；用于 Cloud Build 清单。Pipeline Automation 清单按组织范围管理。
UNITY_NO_CLOUD	--no-cloud	在 projects create 和 projects upgrade 时拒绝关联 Unity Cloud。按是否存在判断：任何值都算，包括 0。在 projects create 和 projects upgrade 中，显式指定的 --cloud、--cloud-project、--cloud-org 或 --coppa 优先于此变量。设置此变量后，除非使用其中一个标志覆盖，否则会拒绝执行 projects create --vcs uvcs。
UNITY_SERVICE_ACCOUNT_ID	—	用于非交互式（CI）身份验证的服务帐户客户端 ID。
UNITY_SERVICE_ACCOUNT_SECRET	—	用于非交互式（CI）身份验证的服务帐户客户端密钥。
UNITY_PROXY	--proxy	HTTP/HTTPS/SOCKS/PAC 代理 URL。优先于 HTTPS_PROXY/HTTP_PROXY/ALL_PROXY 和持久化的 proxy.json 设置。
UNITY_NO_UPDATE_CHECK	—	禁用后台“有可用更新”检查（参见 unity config update-check）。
UNITY_NO_AGENT_HINTS	—	不再建议 AI Agent 运行 unity 时安装 Unity 的 Agent 插件或技能，包括 Claude Code 的安装提示、unity setup codex / unity setup grok 提示，以及 unity skill install 提示（在 --format json 下，信封的 notifications 中会出现 AGENT_PLUGIN_AVAILABLE 条目）。按是否存在判断：任何值都算。提示会要求先征得用户同意，再运行相应命令。
UNITY_NO_CONSENT_PROMPT	—	隐藏首次运行时的一次性分析数据授权提示，但不记录选择——适用于必须确保提示不会被脚本接收的交互式终端包装脚本。分析数据收集会保持关闭，直到运行 unity analytics opt-in。与 UNITY_NON_INTERACTIVE 不同，此变量不会改变命令行为的其他方面。
UNITY_NO_CRASH_REPORT	—	完全禁用匿名崩溃/错误报告（Sentry）。
UNITY_LOG_PROXY	--log-proxy	在 proxy-request.json 中为每个出站请求记录一条已脱敏的日志。真值：1、true。
UNITY_ACCELERATOR	--accelerator	Unity Accelerator 端点（host:port）。优先于持久化的 accelerator.json；--accelerator 标志优先于此变量。
UNITY_NO_ELEVATE	--no-elevate	Windows：跳过 install / install-modules 的提权（UAC）安装助手，使安装服务以非提权方式运行。如果 Windows 要求你的帐户提权，Editor 的 NSIS 安装程序仍会按需请求提权——管理员令牌始终需要提权；标准用户则从不需要。
UNITY_INSTALL_RETRIES	--retries（仅限 install-modules）	install 和 install-modules 在 Editor 或模块下载传输失败或验证失败时的重试次数。0 表示禁用重试；unity install 没有 --retries 标志，因此请在此命令中设置该变量。
UNITY_NO_AUTH_BROKER	—	跳过驻留式身份验证代理，直接从操作系统密钥环读取凭据。默认情况下，每个需要令牌的命令都会通过按需启动并在空闲两分钟后退出的代理（参见 auth-license-cloud.md）。
UNITY_CLI_HOME	—	安装脚本和 unity self-install 的安装根目录，适用于所有平台，包括 Windows：二进制文件会安装到 <UNITY_CLI_HOME>/bin，而不是默认位置。
UNITY_NO_EDITOR_IDENTITY_SERVER	—	禁用后台身份助手；当 Hub 未运行时，unity open 会启动此助手来响应 Editor 的登录查询（参见 projects-templates.md）。按是否存在判断。
UNITY_EXPERIMENTAL_FEX_EMU	无	仅限 Linux arm64，实验性功能且不受支持：通过 FEX-Emu 运行 x86_64 Editor。设置为 1、true 或 yes 即可启用，且仅在已安装 FEX-Emu 和 x86_64 RootFS 时生效（unity doctor 会进行检查）。已知 C# 脚本编译会在 FEX-Emu 下崩溃。参见 editors-install.md。
CI 服务账户身份验证： 设置 UNITY_SERVICE_ACCOUNT_ID 和 UNITY_SERVICE_ACCOUNT_SECRET，即可跳过浏览器 OAuth 流程——这样可避免将密钥暴露在进程参数列表和 shell 历史记录中。这两个变量分别对应 unity auth login 的 --client-id / --secret-from-stdin 输入，但从环境变量读取凭据并不等于完成登录：它不会运行交互式流程，也不会将凭据保存到密钥环中。

获取帮助

在任意级别的命令或子命令后追加 -h 或 --help：unity --help、unity projects create --help。

不确定该用哪个命令？搜索，而不是在帮助中 grep。unity --help 和未知命令错误的末尾也会显示该提示。每次搜索结束时都会指出它跳过的来源，以及用于搜索该来源的命令（JSON 中的 data.hint）：在断定不存在相关内容之前，请先按照提示操作。

退出代码

先根据退出代码判断，再查看 JSON 或 NDJSON 信封中的 errors[0].code。重试表示原样再次运行同一命令是否可能成功。unity commands --json 会在 exitCodes 中提供此表，以及对应各退出代码的错误代码。6 适用于没有更具体代码名称的所有失败；缺少项目、Editor 未运行、未知 Editor 命令和超时分别有自己的代码（11 至 14）。

Code	Name	Retry	Meaning
0	SUCCESS	否	命令成功。
1	ERROR	否	出现意外或不受支持的状态。
2	BAD_ARGS	否	用法错误：命令或选项未知，或值无效。
3	AUTH_ERROR	否	尚未登录、会话已过期，或权限遭到拒绝。
4	NEEDS_CONFIG	否	缺少设置项：必需的工具、设置或链接。
6	COMMAND_FAILED	否	命令失败，且没有更具体的代码名称。
7	NETWORK_UNREACHABLE	是	无法连接到必需的服务。
8	TESTS_FAILED	否	测试已运行，但部分测试失败。
9	INSTALL_LOCKED	是	另一个进程持有安装锁。
10	READY_TIMEOUT	是	Editor 未能在规定时间内就绪。
11	NOT_FOUND	否	命令指定的对象不存在：项目、版本或模块。
12	EDITOR_UNREACHABLE	是	没有正在运行的 Editor 响应：没有 Editor 正在运行、没有匹配项，或 Editor 拒绝了连接。
13	REMOTE_COMMAND_FAILED	否	Editor 已响应，但没有名为该名称的命令。
14	TIMEOUT	是	操作超时：Editor 请求、HTTP 请求或批处理运行。
130	INTERRUPTED	是	被 Ctrl-C (SIGINT) 中断。
141	OUTPUT_CLOSED	否	stdout 的读取方关闭了管道。
143	TERMINATED	是	被 SIGTERM 终止。

8 仅用于 unity test：测试已运行，但部分测试失败。未能完成的运行会以 6 退出，超时的运行会以 14 退出，因此 CI 可以重试这些运行，而不会盲目地重新运行失败的测试。9：同一次安装中较早的条目可能已经就位（data.completedUids）。10 仅用于 unity open --until-ready；Editor 仍在运行。

命令

各命令的完整参考资料（语法、标志和示例）按分组存放在 references/ 下的文件中。请阅读所需命令组对应的文件；上文列出的所有全局 标志、环境变量和退出代码均适用于所有命令。每个命令也支持 -h / --help（参见获取帮助）。

命令	参考文件
auth（login / logout / status / list / switch / default / consumers / revoke）、license（activate / return / server）、cloud（org / project）	auth-license-cloud.md
pipeline cloud-build（目标，包括 groups / builds / project / tooling）、pipeline automation（apps / pipelines / jobs / automations / bots / profiles / templates，以及 apps versions、pipelines versions、jobs stats）	cloud-automation.md
editors（list / running / add / default / path / install-path / info / upgrade / prune / verify / module）、install、uninstall、modules、install-modules、terms（accept / status）	editors-install.md
projects（list / create / new / clone / open / link / require / upgrade / export / import / pin / size / clean / exec；其帮助说明为“创建、打开、升级和关联本地 Unity 项目（Unity Cloud、GitHub/GitLab）”，因此将文件夹关联到 Unity Cloud 应使用 projects link cloud，而不是 cloud）、open、close、releases、templates（list / info / create / pack / delete）、assets（inspect / export）	projects-templates.md
config（proxy / update-check / accelerator / get / set / list / unset / resolve）、context（save / use / list / current / delete）、hub install	config-hub.md
run、test、build（以及 build run）、recompile、watch（test）	build-run-test.md
logs、doctor、env、version、cache、ci init、analytics、changelog、docs（以及 toc）、language、completion、bug、self-update、self-uninstall、diagnose proxy、diagnose accelerator、diagnose update	diagnostics-maintenance.md。查找、引用并匹配 Unity 文档版本： docs-workflow.md
mcp（以及 configure）、setup claude / codex / grok / antigravity、skill（install / refresh / show）、plugin（install / remove / upgrade / list / changelog）、本地 pipeline（install / upgrade / list / list-versions）、command / commands / status / list、job（status / wait / cancel）、回答已打开的模态对话框（command editor.dialog list / answer / dismiss）、shell	integration-advanced.md
vcs — setup / status / sync / switch / doctor / providers / merge-setup / conflicts / explain / resolve / diff / blame / summarize / affected / hooks、vcs git（migrate-lfs / worktree）、vcs uvcs（locks / changesets / review）	version-control.md
collaboration（别名 collab）— annotations / attachments / thumbnail / reactions / read / subscribe / jira	collaboration.md

常见工作流

检查云构建或 Pipeline Automation 资源

请阅读 cloud-automation.md，了解两组中的所有只读 命令、上下文/身份验证、各命令的筛选条件和排序、输出字段、分页（包括拒绝 --page/--limit 而非忽略这些参数的叶级命令）、错误和脱敏规则。pipeline cloud-build 读取 Build Automation； pipeline automation 读取 Pipeline Automation。两者都不需要正在运行的 Editor 或本地 Pipeline 包。服务账户请使用数字组织 ID。 这些命令不会触发构建/作业、获取日志/制品或更改配置。

JSON/NDJSON 会在 data 下返回完整的 API 形状结果，与 Collab 一样；NDJSON 只有一个最终结果，没有项目帧。保留原生字段和自由格式元数据，但须遵守参考文档中有限范围的机密信息保护和公共 API 脱敏假设。表格投影仍然独立。显式的本地构建目标会保留 _local；缺失的目标不属于本地目标。这些约定也适用于后续的 cloud-automation 工作。

编辑场景、GameObject 或资源——先运行 unity status

编辑任何场景、GameObject、预制件或资源之前，先运行 unity status，检测是否有已连接的 Editor。 如果可以连接，就用实时命令驱动它，而不是直接操作项目文件——Editor 会将更改应用到当前实际激活的场景，并保持内存状态同步。

unity status                       # is an Editor connected? (look for state "ready")
unity command                      # discover the scene/GameObject commands THIS Editor exposes
# then drive it with the commands it lists — for example, if your Editor exposes them:
unity command gameobject create   # act on the live, active scene
unity command scene save          # persist the active scene

命令名称由 Editor 定义，因此请运行 unity command（或 unity list）查看准确的命令集——不要想当然地猜命令名称。

只要实时 Editor 可连接，就绝不要手动编辑 .unity、.prefab 或 .asset YAML 文件。 直接编辑文件：

• 容易出错——fileID 和 GUID 需要手动分配，很容易出错；
• 对正在运行的 Editor 不可见，直到重新导入才会生效，因此更改可能会悄无声息地失效；以及
• 容易改错文件——例如，在 Editor 实际激活的场景是 Demo2.unity 时，却写入 SampleScene.unity，生成的 YAML 看似有效，实际却不会改变用户看到的内容。

在断定无法连接到 Editor 之前，先排除两种假阴性——它们看起来都和 Editor 确实已关闭时完全一样，而且时间紧迫时很容易误判：

• 安全模式。 如果此项目的 Editor 正在运行，但 unity command 无法连接，它可能是因编译错误而停在了安全模式，而不是真的不存在。运行 unity status：如果报告了安全模式（STATUS_SAFE_MODE，并显示编译错误），正确做法是编辑 C# 源文件以修复编译错误，而不是采用后备方案。参见 integration-advanced.md → 从安全模式恢复。
• 沙盒化的 Agent shell。 如果你的 shell 命令在受限沙盒中运行——这类编码 Agent 通常如此——沙盒可能会像 unity status 一样隐藏一个实际正在运行的 Editor。这适用于所有进入此预检流程的场景/GameObject/预制件/资源任务，而不只是那些显然需要实时 Editor 的任务：原本无需 CLI 即可完成的任务（例如通过常规 Editor API 生成资源），也可能因此被引导到“没有 Editor”的结论上，导致任务偏离正轨。不要把“没有实例”当作 Editor 已关闭的证据，也不要悄悄另辟蹊径——例如启动一个独立的无头 Editor 进程，试图模拟实时连接的效果——来替代明确告知用户的文件编辑操作。请明确说明沙盒可能屏蔽了你对实际 Editor 的访问，并在采用后备方案前询问 Editor 是否确实已打开。完整说明： integration-advanced.md → 沙盒化的 Agent 工具可能会隐藏正在运行的 Editor。

只有排除以上两种情况后，才可以改为直接编辑文件——并明确说明（“未检测到实时 Editor，直接编辑文件”）。

生成资产、纹理、精灵、图像或 3D 模型：检查是否有 ai 目录插件

在用其他方式近似处理“为我的项目生成纹理／精灵／图像／3D 模型”的请求之前，请先检查是否已安装 Unity AI Generators 插件（ai）。 这是 Unity 自有的目录插件，专门用于处理这类请求，使用它几乎总是更好的选择。以下相同的三步模式（识别意图、检查目录、安装前征求同意）适用于 CLI 附带的任何目录插件，而不只限于这个插件；unity plugin list 始终会显示完整目录，无论插件是否已安装，因此也可以用它来了解还有哪些插件可用。

1. 检查是否已安装。

   unity plugin list --format json
   

   找到 id 为 "ai" 的条目，并读取其 installed 字段（true / false）。

2. 尚未安装？告知用户，然后征求同意，绝不要静默安装。 明确告知 Unity 提供了可满足此需求的 AI Generators 插件，然后等待用户同意后再运行：

   unity plugin install ai
   

   用户拒绝是正常的答复：改用原本会采用的方案，并且在同一对话中不要再次询问。

   ai 目前处于 alpha 阶段，在 alpha 期间仅限 Unity 员工通过 Unity 内部网络使用。普通用户运行 unity plugin install ai 时，可能会看到登录提示（“Unity AI Generators is currently limited to Unity staff. Sign in with a Unity staff account…”）；即使通过这一步，如果你所在的网络无法访问所需资源，也可能会遇到普通的下载失败。这两种情况都不是请求本身有问题：报告提示信息并改用其他方案，与用户拒绝时的处理方式相同。

3. 在同一会话中获取它的 Agent 技能。 目录插件可以在其载荷中附带自己的 Agent 技能（ai 就有），而安装插件本身并不会让你看到该技能；必须像镜像本技能一样将其镜像：

   unity skill install <client>     # e.g. claude-code, first time this session
   unity skill refresh              # already mirrored earlier? re-render it fresh
   

   unity plugin install 的最后一行会直接告诉你该怎么做：安装附带技能的副本后，它会提示运行 unity skill install；如果技能已镜像，但插件副本刚刚发生变更，则会提示运行 unity skill refresh。使用 unity skill list --format json 确认技能的存放位置（查找 skill 字段中列出插件自带技能名称的行，例如 unity-ai，并读取其 path），然后先阅读该文件，再运行插件命令。不要根据本技能猜测插件有哪些命令；本技能只介绍 unity 本身。

如果在此之前调用命令（直接输入 unity ai …，或凭记忆提出该命令），则会失败并返回清晰、可操作的信息，明确指出准确的安装命令（unity plugin install ai）；人类可读和机器可读（--format json / --format ndjson）输出都会如此，稳定错误代码为 TOOL_NOT_INSTALLED。请阅读该提示，不要猜测命令为何没有执行；目录工具因另外两种原因无法运行时，也会返回相同格式的信息，错误代码分别为 TOOL_UNSUPPORTED_PLATFORM 和 TOOL_RUNTIME_NOT_INSTALLED。

从零开始搭建新项目

如需引导式端到端体验——包括概念问题、规划期间在后台安装 Editor、选择包，以及移交变现流程——请使用 new-unity-project 技能。本节是该技能所依据的原始 CLI 操作步骤；如果只需要命令，请直接使用本节。

仅使用 CLI，将一个创意变成可运行且纳入版本控制的项目。先确定目标平台——它们决定了你需要在步骤 2 中安装哪些 Editor 模块。你可以稍后添加模块（unity install-modules），但项目只有在安装了相应平台模块后才能为该平台构建，因此最好预先确定。

# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md).
unity --version
unity auth status --format json      # if signed out:      unity auth login
unity license status --format json   # if none active:      unity license activate

# 2. Pick and install an Editor with the modules your target platforms need.
#    Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream
#    release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as
#    evaluation-only, never for a project you intend to ship. A deadline argues for LTS.
#    (lts / latest aliases work almost everywhere a version is accepted — `templates` is the
#     exception; see step 3.)
unity releases --stream lts --limit 5 --format json
unity install lts --module android --module ios --yes --accept-eula   # add --module webgl, etc.
unity editors --installed --format json                               # confirm it landed

# 3. List the real template ids this Editor offers — don't guess them — and pick by RENDER
#    PIPELINE, not just by 2D/3D. Default to the URP templates:
#      3D → com.unity.template.urp-blank      ("Universal 3D")
#      2D → com.unity.template.universal-2d   ("Universal 2D": URP + the 2D packages)
#    com.unity.template.3d and com.unity.template.2d are the Built-in Render Pipeline templates
#    (displayName "… (Built-In Render Pipeline)"): deprecated from Unity 6.5, gone in 6.7. Use
#    them only when the user explicitly asks for Built-in. Confirm the pick with the JSON
#    `renderPipeline` field — it is blank for universal-2d on current releases, so match that
#    one by id.
#    NOTE: `templates` does NOT resolve the lts / latest aliases — unlike `install` and
#    `projects create`, it passes --editor straight through and rejects anything that is not a
#    concrete 6000.x.y. Use the version you just installed (read it from `editors --installed`).
unity templates list --editor <6000.x.y> --type core --format json

# 4. Create the project. The first positional arg is the NAME; --path sets the parent directory.
#    All options supplied, so it won't prompt; add --non-interactive in CI.
#    (To publish it to a remote in the same step, use the source-control forms below instead.)
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.urp-blank

# 5. Add the Pipeline package BEFORE the first open. `unity command`, `unity status` and
#    `unity command script eval` all need it, and templates don't include it. The Editor reads
#    Packages/manifest.json when it loads the project, so installing first means the package
#    is live from the first open.
unity pipeline install --project-path ~/UnityProjects/MyGame

# 6. Open the project and wait until its Editor is ready to take commands. Pass the project's
#    full path: a path that exists matches that project's Editor only, so an Editor open on a
#    sibling checkout such as ~/UnityProjects/MyGame-lighting can't end the wait.
cd ~/UnityProjects/MyGame
unity open .
unity status --until-ready --project-path ~/UnityProjects/MyGame --format json

然后在运行中的 Editor 中构建场景，而不是使用批处理模式。 使用 unity command script eval（或 Editor 自带的 unity command 工具），针对正在运行的 Editor 创建 GameObject、连接组件并设置资源引用，然后用同样的方式读取结果。每一步都可以在进行下一步之前检查。通过 unity run -- -executeMethod 运行脚本，是在无法让 Editor 保持打开时（例如 CI、无头构建机器）的备用方案。它无法查看生成的内容：即使保存的引用为 null（例如没有 PanelSettings 的 UIDocument），也仍会报告成功。如果确实使用了批处理模式，请在运行中的 Editor 中打开结果并检查，然后再宣布工作完成。如何获取可供驱动的 Editor： integration-advanced.md → 获取可供驱动的 Editor。

源代码管理——由用户选择。 CLI 可通过任意提供商一步将新项目发布到全新的远程仓库。始终通过 stdin 传递令牌（--git-token-from-stdin），避免机密出现在 shell 历史记录或进程列表中。根据项目选择，不要默认使用某一种方案：

• Git — GitHub / GitLab（--vcs github / --vcs gitlab）。应用广泛。对于资源繁多的游戏，添加 Git LFS（--git-lfs），避免大型二进制文件撑大历史记录。
• Unity Version Control — UVCS（--vcs uvcs）。Unity 自家的 VCS，专为大型二进制游戏资源打造：它可原生处理这些资源（无需 LFS），并支持文件锁定——对于美术资源繁多的项目或较大的团队，往往更合适。使用 Unity 登录信息进行身份验证；--vcs-region 用于选择区域。

# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you
# want to add packages/assets BEFORE the first commit (see the new-unity-project flow).
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.urp-blank \
  --vcs github --git-namespace my-org --git-repo my-game \
  --git-visibility private --git-default-branch main --git-token-from-stdin --git-lfs

# Unity Version Control (UVCS) — handles binaries natively, so no LFS:
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.urp-blank \
  --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>

从机密存储中向 --git-token-from-stdin 提供令牌，切勿直接写入明文——例如 … --git-token-from-stdin <<<"$GIT_TOKEN"，其中 $GIT_TOKEN 来自 CI／机密管理器（UVCS 使用 Unity 登录信息，因此无需令牌）。

日常使用 UVCS 工作区：少数读取操作经过封装，其余操作直接转发给 cm。 这种划分是有意为之，值得说明，因为猜错会浪费用户时间：

• unity vcs uvcs <verb> 封装了那些将 cm 数据与项目关联起来的读取操作——locks（谁持有锁，以及哪些锁涵盖了你已更改的文件）、changesets 和 review。这些关联是 cm 无法替你完成的，而且封装格式稳定，因此凡是需要解析输出的场景，都应优先使用它们。
• unity uvcs <args> 会将整条命令行原样转发给 cm，包括 --help 和 --format。这是受支持的方式，而非权宜之计：这些命令用法由 cm 自行维护和更新，若加以封装，就会固定一套过时的转述。对于部分检出、搁置更改、获取或释放锁，以及由人工读取输出的场景，请使用此命令。

unity vcs uvcs locks                       # who holds what, and what collides with your changes
unity uvcs lock list                       # the raw listing, cm's own flags and output
unity uvcs partial update /Assets/Levels   # cm's own vocabulary, unchanged
unity uvcs shelve -c "wip: lighting pass"

所有动词、标志和注意事项：version-control.md。

unity cm <args> 是同一透传功能的另一种调用方式，使用 cm 自己的名称。两种方式都需要 cm 客户端；如果命令提示缺少该客户端，请使用 unity plugin install plastic 安装。

除项目初始化外，vcs 组还覆盖整个日常工作循环——status、sync、switch、merge-setup、conflicts / explain / resolve、diff、blame、summarize、affected、hooks、doctor、providers——而 Unity 语义正是优先使用它、而非原始 git 的原因。完整参考（包括标志和注意事项）： version-control.md。 **Git 令牌属于用户的凭据管理器，而非 CLI。**如果未提供令牌标志或环境变量，CLI 会调用 git credential fill，并使用配置的辅助程序返回的内容；它不会存储收到或获知的任何信息。不要建议 CLI 可以保存 Git 令牌；如果用户已有可用的凭据辅助程序，也不要使用令牌标志。如果用户希望每个组织使用不同的令牌，可以设置 git config --global credential.useHttpPath true，并使用 Git Credential Manager 等多账户辅助程序。CLI 会传递完整的仓库 URL，以便辅助程序区分不同账户，但绝不会安装或重新配置辅助程序。UNITY_GITHUB_TOKEN / UNITY_GITLAB_TOKEN 每个提供商只能使用一个令牌，因此跨多个组织的 CI 作业应在每次调用时改用 --git-token-from-stdin。完整的源代码管理标志集请参阅 references/projects-templates.md。如果使用纯本地 Git 仓库，请改为使用适用于 Unity 的忽略规则初始化 Git，确保数 GB 的 Library/ 和其他生成文件夹永远不会被提交：

cd ~/UnityProjects/MyGame
git init -b main
# Download (do not pipe to a shell) a maintained Unity .gitignore:
curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore

# Asset-heavy game? Keep large binaries out of git history with Git LFS:
git lfs install
git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png"   # adjust to your asset types
git add .gitattributes

git add -A
git status                             # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged
git commit -m "Initial Unity project: MyGame"
git ls-files | grep -c '^Library/'     # must print 0

**CLI 能做什么和不能做什么。**CLI 负责编辑器、项目和源代码管理。它没有顶层的包命令。要添加模板之外的 UPM（Unity Package Manager）包，请使用 unity-package-management 技能：它会通过 unity command 运行 Pipeline package add 命令，并在不可用时回退到无头 C# 脚本。对于变现／后端工作，请交由专用技能处理：implement-in-app-purchases（IAP）、levelplay-unity-integration（广告）或 build-live-game（账户、云存档、经济系统、远程配置、排行榜）。完成上述第 5 步和第 6 步后，请在已打开的编辑器中继续操作。

**编辑器已打开时才安装了 Pipeline 包？**只有在编辑器下次刷新时，它才会读取清单更改。在此之前，unity status 会报告 STATUS_PIPELINE_LOAD_PENDING（或在该代码出现之前的 CLI 版本中报告 STATUS_NO_INSTANCES）。仍在启动或导入的编辑器也会报告相同的代码，直到完成为止，因此请先等待完成（unity status --until-ready）。CLI 无法自行触发刷新：如果编辑器已完成启动，请让用户切换到 Unity Editor 窗口，然后重新运行 unity status --until-ready。在首次打开前安装（第 5 步）即可完全避免此问题。

查找并安装缺失的编辑器

# 1. Check what's installed
unity editors --installed --format json

# 2. Browse available LTS versions
unity releases --lts --limit 5 --format json

# 3. Install
unity install 6000.0.47f1 --yes --accept-eula

使用正确的编辑器打开项目

# 1. Check the project's required editor version
unity projects info /path/to/MyProject --format json
# Look at "editorVersion" in the result

# 2. Confirm that editor is installed
unity editors --installed --format json

# 3. Open (warns if the editor version is missing)
unity open /path/to/MyProject

CI：激活许可证，然后构建

# 1. Activate a license without signing in; a service account cannot activate one.
#    A perpetual or legacy serial: store it as the CI secret UNITY_LICENSE_SERIAL
#    (the name `unity ci init` generates) and pass it to the step, e.g. in GitHub
#    Actions `env: { UNITY_LICENSE_SERIAL: ${{ secrets.UNITY_LICENSE_SERIAL }} }`.
#    A serial tied to a subscription needs a signed-in user, so for those seats use
#    --floating, or the offline --generate-request / --file path (see "Headless /
#    fleet license activation" in references/auth-license-cloud.md).
unity license activate --serial "$UNITY_LICENSE_SERIAL"   # or: unity license activate --floating

# 2. Only if the job also runs cloud commands: export UNITY_SERVICE_ACCOUNT_ID and
#    UNITY_SERVICE_ACCOUNT_SECRET from the CI secret store. Every later command reads
#    them directly, with no `unity auth login` and nothing written to a credential
#    store (which a headless runner may not have).

# 3. Build
unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

# 4. Return the license when done (serial or assigned seats)
unity license return --yes

CI：无头构建

优先使用专用的 unity build 命令（可处理批处理模式、日志记录和 CI 标志）：

unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

或者使用 unity run（会自动启用批处理模式——切勿传入 -batchmode / -quit）：

unity run /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --allow-install \
  -- -executeMethod Builder.PerformBuild -logFile build.log
echo "Exit code: $?"

要为播放器构建编写脚本？请将每个 MonoBehaviour 单独放在一个以其类名命名的 .cs 文件中。把多个类放在同一个文件中，可能在编辑器和 Play Mode 中运行正常，但构建后的播放器会在启动时崩溃，并提示场景文件（例如 level0）已损坏。请参阅 build-run-test.md。

CI：运行测试并发布结果

unity test /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --mode EditMode \
  --report-format junit \
  --output ./test-results.xml \
  --allow-install \
  --timeout 600
case $? in
  0) echo "All tests passed" ;;
  8) echo "Tests failed — report to developers, do not retry" ;;
  *) echo "Run did not complete — infrastructure failure, safe to retry" ;;
esac

退出码 8 表示运行已完成并报告了失败的测试；其他任何非零代码都表示未能得出结果。使用 --format json 时，errors[0].code 也会区分这两种情况：TESTS_FAILED 与 TEST_RUN_ERROR / TEST_TIMED_OUT。

--report-format junit 会将 --output 生成为 JUnit 格式的报告，GitHub Actions 和 GitLab 无需转换步骤即可将其作为原生测试结果导入。即使测试失败，也会写入报告。移除该标志即可使用默认的 NUnit3 格式，或者使用 --report-format nunit,junit，在一次运行中生成两种报告。添加 --coverage 可通过 Unity Code Coverage 包收集覆盖率；如果项目未安装该包，命令会发出警告并继续运行。请参阅 build-run-test.md。

是在迭代修改，而不是为流水线设置门禁？ 运行能检出此次修改问题的最轻量测试。先尝试 EditMode。在开发过程中使用 --filter、--affected 或 --rerun-failed。交还工作前，每种模式下都只针对最终代码运行一次完整测试套件。除非运行以 6 退出且未得出结果，否则不要对未发生变化的代码重新运行测试套件。这些运行请保留默认的 NUnit 格式，因为 --affected 和 --rerun-failed 无法读取上述 CI 示例生成的仅含 JUnit 格式的报告。build-run-test.md 说明了这一规则，以及各标志读取和写入的报告类型。若项目已在 Editor 中打开，unity test 会拒绝运行：不要为了腾出空间而关闭用户的 Editor，也不要在用户处于 Play Mode 时启动测试。

调试 CLI

# Check auth + installed editors + recent errors in one command
unity doctor --format json

# Follow live logs during an install
unity logs --follow --level info

---

通知

--format json 或 --format ndjson 的信封中可能包含 notifications 数组：这些通知提示的是用户环境相关事项，而不是你运行的命令相关事项。出现通知时，请告知用户——他们没有其他途径看到这些通知，因为面向用户的等效信息只会显示为终端横幅，而你无法看到横幅。

没有需要报告的内容时，该键会缺失，因此请按 envelope.notifications ?? [] 处理。

{
  "code": "CLI_UPDATE_AVAILABLE",
  "message": "A new version of the Unity CLI is available: 1.0.0-beta.8 → 1.0.0-beta.9",
  "data": { "current": "1.0.0-beta.8", "latest": "1.0.0-beta.9" },
  "remediation": { "command": "unity self-update", "requiresUserApproval": true }
}

请根据 code 进行分支处理；message 已本地化，供显示使用。data 的结构因 code 而异。

PLUGIN_UPDATE_AVAILABLE 表示已安装的插件有新版本。 data 的格式为 { "plugin": "<id>", "current": "…", "latest": "…" }，对应的处理命令是 unity plugin upgrade <id>。每个过期插件各有一条通知。

remediation 说明如何解决通知。该字段可能缺失，表示此通知仅供参考，无需运行任何命令。

FEX_EMU_EXPERIMENTAL 表示命令已通过或将通过 Linux arm64 上的 FEX-Emu 运行 x86_64 Editor。请告知用户，此功能处于实验阶段且不受支持，并且已知在此环境中 C# 脚本编译会崩溃。

requiresUserApproval: true 表示不要自行运行 remediation.command。 请告知用户该通知及相关命令，并由用户决定是否执行。

---

说明

• 同时使用 --non-interactive 和 --yes 可禁止所有提示——在 CI 中请同时使用两者。
• 短选项在所有命令中含义一致：凡是有 --yes 的命令，-y 都表示 --yes；-a 表示 --architecture。unity projects list 和 unity projects size 用 --all 表示“每个项目”；请使用该选项，而非 -a。CLI 仍接受一些旧写法（-a，以及 status 上的 --project、--template-version、--hub-version、--package-version、--list-components、--install-dir、--childModules、--wait-timeout、--git-token-stdin、command 上的 --group_by、collaboration annotations 上的 --local-space、collaboration 上的 --project-id 和 --organization-id、projects list 上的 -v、releases 和 vcs git migrate-lfs 上的 --since），但使用时会打印警告，指出应使用的写法。editors 和 projects list 上的 --verbose 也会发出警告；它仍会显示所有列，但现在应写作 --long。在 --format json 下，警告会出现在信封的 warnings 中。请使用新写法，以免警告出现在你要解析的日志中。
• 所有命令的 --timeout 都接受以数字表示的整数秒（--timeout 600）；UNITY_BUILD_TIMEOUT、UNITY_RUN_TIMEOUT 和 UNITY_TEST_TIMEOUT 也一样。使用单位、小数或指数（30s、5m、1.5、1e3）会导致用法错误（退出码 2），因此请自行将分钟换算为秒。
• --format json 始终生成机器可读的输出；请优先使用它，而不是解析面向用户的文本。错误信封采用与成功信封相同的 2 个空格缩进进行美化打印。
• 仅当退出码为 0 时，success 才为 true。 状态命令给出的答案为否时（unity auth status 显示已退出登录、unity license status 没有许可证、unity status 没有就绪的 Editor），命令会失败：success: false，errors[0].code 会指出具体答案，报告仍保留在 data 中。未找到任何内容的列表命令（例如没有 Editor 时运行 unity editors running）则会成功，并返回空列表。
• 从 stdout 而非 stderr 读取失败信息。 命令失败时仍会向 stdout 写入完整文档：在 --format json 下为包含 success: false 和已填充 errors 数组的信封（errors[0].code 是用于分支判断的稳定标记）；在 --format ndjson 下为常规的终止 {"type":"result","success":false,…} 帧。每个 ndjson 流末尾都恰好有一个终止 {"type":"result"} 帧，成功时也一样，因此没有该帧就表示流被截断。表格形式的列表（unity editors、unity editors upgrade --check、unity templates list、unity releases、unity projects list、unity context list、unity auth list、unity modules list、unity list、unity doctor、unity cloud org list、unity cloud project list）会先逐行写出列表，每行没有 type 字段，随后写出一个终止帧，其 data 为 {"count": N}。单条记录的结果（如 unity version、unity language、unity config proxy、unity cache info）只有该帧，其 data 与 --format json 下相同；unity env 则先写出各行，再写出该帧。--quiet 不会改变 json 输出，也不会改变 ndjson 输出，但有一个已知错误例外：unity editors upgrade、unity editors module list、unity install-modules、unity build --list-targets、unity build --list-profiles 和 unity env 在 --quiet 下仍会省略各行（终止帧保留）；需要这些行时，请不要使用 --quiet。两种格式下的警告都只出现在 warnings 中，绝不会写入 stderr。--watch 列表只有在按下 Ctrl-C 时才会结束，因此不会写出终止帧。少数命令（包括 unity install-modules --list）仍会在成功的 ndjson 流末尾省略终止帧，这是一个已知错误。请根据 success 分支判断，绝不要根据 data 判断——失败时 data 通常为 null，但并非总是如此：unity editors add 部分失败时会为每个路径返回一行；unity auth switch 遇到歧义时会在 data.candidates 中提供候选项供你进一步判断。请检查 success 和退出码——绝不要将 stdout 为空视为失败信号，也不要解析 stderr；在这些格式下，stderr 只包含面向用户的诊断信息。如果非零退出时 stdout 为空，这是该命令的已知错误，并非你应当针对其编码的输出形式。
• unity <version> [path] 是 unity open [path] --editor-version <version> 的简写。可使用 lts、latest 或完整版本字符串，例如 6000.0.47f1。
• CLI 支持 kubectl 风格的插件：PATH 上的任何 unity-<name> 二进制文件都可通过 unity <name> 调用。
• CLI 已加固终端输出，以防服务器提供的值（项目标题、Editor 版本、模块名称）注入控制字符或转义序列——表格、列表和树状输出中的 C0 控制字符及非 SGR 转义序列都会被剥除；现在，Commander 用法错误、unity bug 日志归档警告，以及 unity projects add/remove 机器（tsv）输出中的此类字符也会被剥除，同时保留 SGR 颜色／样式代码。
• CLI 会通过 Sentry 报告匿名崩溃和错误，以帮助修复问题（不含 IP 地址或主机名；发送前会清理主目录路径和类似令牌的值），与 Unity Hub 的做法一致。选择加入分析后还会附加匿名化的机器 ID；选择退出的用户仍完全匿名。设置 UNITY_NO_CRASH_REPORT 可完全禁用报告。除此之外，每次运行都会发送一条匿名的 cli telemetry 使用情况 ping，不受分析／同意状态影响——请参阅 diagnostics-maintenance.md。
• unity --version 会打印当前安装的版本。unity self-update --check --format json 会报告当前安装渠道上是否有更新版本（测试版会跟随测试版）。例如，在 GA 发布后从测试版切换时，可使用 unity self-update --check --channel stable --format json 检查稳定版发布情况。
• 除非明确要求使用特定版本，否则请始终使用最新版本的 Unity CLI。 新版 CLI 会定期添加本文档所述的命令和输出字段，因此过时版本可能会以看似文档有误的方式失败。
• 从 0.1.0-beta.8 起，CLI 会在后台检查是否有新版本，并显示不显眼的“有可用更新”通知（仅限交互式会话；不会延迟命令）。可通过 unity config update-check off 或 UNITY_NO_UPDATE_CHECK 环境变量关闭。
• 同一项检查也适用于 CLI 安装的插件（unity plugin install）：有新版本时，会显示通知，指出插件名称并建议运行 unity plugin upgrade，每天最多一次。使用上述同样的两种开关即可关闭。
• 在 --format json 和 --format ndjson 下，同一通知会通过信封中的 notifications 数组送达——请参阅下方的 Notifications。通过 MCP 时，它会在每个会话中送达一次，以文本形式出现在服务的 initialize instructions 中。
• 所有 CLI 命令的出站 HTTP 请求都会遵循解析得到的代理（请参阅 unity config proxy）。无效的 --proxy 值（格式错误的 URL 或不受支持的协议）会导致用法错误（退出码 2），而不会被静默忽略。可通过 unity env --format json 或 unity doctor --format json 查看 CLI 实际解析出的配置——两者都会显示当前代理 URL、其来源以及身份验证来源。