unity-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity CLI

Step 1: Install the CLI (if not already installed)

步骤1：安装CLI（如果尚未安装）

First check if the CLI is available:

bash

which unity && unity --version

If not found, install it:

macOS / Linux

bash

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

Windows (PowerShell)

powershell

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

After installing, open a new shell so

unity

is on PATH, then verify:

bash

unity --version

If the install script fails or the binary is still not found, tell the user and stop.

首先检查CLI是否可用：

bash

which unity && unity --version

如果未找到，请安装：

macOS / Linux

bash

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

Windows (PowerShell)

powershell

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

安装完成后，打开新的Shell窗口，确保

unity

已加入PATH，然后验证：

bash

unity --version

如果安装脚本失败或仍无法找到二进制文件，请告知用户并停止操作。

Step 2: Verify it works

步骤2：验证功能正常

bash

unity --version

If this fails with a permissions error or crash, the CLI installation may be broken. Suggest re-running the install script.

bash

unity --version

如果因权限错误或崩溃导致失败，说明CLI安装可能损坏。建议重新运行安装脚本。

Global flags

全局标志

These work on every command:

Flag	Description
`--format <fmt>`	Output format: `human` (default), `json` , `tsv` , `ndjson` . Also via `UNITY_FORMAT` env var.
`--no-banner`	Suppress the branded header — use in scripts
`--non-interactive`	Disable all interactive prompts — use in CI
`--quiet`	Suppress non-essential output
`--verbose`	Print full error details (stack trace + cause chain) on failure. Also via `UNITY_VERBOSE` .
`--proxy <url>`	HTTP/HTTPS/SOCKS/PAC proxy URL for this invocation. Also via `UNITY_PROXY` . Takes precedence over standard `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` env vars and the persisted `proxy.json` setting.
`--proxy-disable`	Disable proxy for this invocation, ignoring all sources (env vars, persisted config, system settings).
`--log-proxy`	Log one redacted entry per outbound request (host-only URL, resolved proxy, auth source, status, duration) to `proxy-request.json` — for reproducing proxy issues for support. Also via `UNITY_LOG_PROXY=1` or the persisted `proxyRequestLogging` setting.
`--no-log-proxy`	Opt a single invocation out of proxy request logging when it's enabled globally.

Always use
--format json
when you need to parse output programmatically.

A branded Unity header (logo, wordmark, CLI version) renders on the landing surfaces — bare

unity

unity --help

-h

unity help

, and above the first-run consent prompt. It's shown only on a TTY, prints at most once, and degrades to compact, uncolored text on narrow terminals, without Unicode, or under

NO_COLOR

. Piped output is unaffected. Use

--no-banner

to suppress it in scripts. Bare

unity

prints usage and exits 0.

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

标志	描述
`--format <fmt>`	输出格式： `human` （默认）、 `json` 、 `tsv` 、 `ndjson` 。也可通过 `UNITY_FORMAT` 环境变量设置。
`--no-banner`	隐藏品牌化头部——在脚本中使用
`--non-interactive`	禁用所有交互式提示——在CI环境中使用
`--quiet`	抑制非必要输出
`--verbose`	失败时打印完整错误详情（堆栈跟踪+原因链）。也可通过 `UNITY_VERBOSE` 环境变量设置。
`--proxy <url>`	本次调用使用的HTTP/HTTPS/SOCKS/PAC代理URL。也可通过 `UNITY_PROXY` 环境变量设置。优先级高于标准 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` 环境变量和持久化的 `proxy.json` 设置。
`--proxy-disable`	禁用本次调用的代理，忽略所有来源（环境变量、持久化配置、系统设置）。
`--log-proxy`	将每个出站请求的一条脱敏记录（仅主机URL、解析后的代理、认证来源、状态、时长）记录到 `proxy-request.json` ——用于向支持团队复现代理问题。也可通过 `UNITY_LOG_PROXY=1` 或持久化的 `proxyRequestLogging` 设置启用。
`--no-log-proxy`	当全局启用代理请求日志时，让单次调用跳过日志记录。

当需要以编程方式解析输出时，请始终使用
--format json
。

在以下场景会显示Unity品牌化头部（Logo、标识、CLI版本）：直接执行

unity

、

unity --help

-h

、

unity help

，以及首次运行的同意提示上方。仅在TTY环境下显示，最多显示一次，在窄终端、无Unicode或开启

NO_COLOR

时会降级为紧凑的无颜色文本。管道输出不受影响。在脚本中使用

--no-banner

可隐藏它。直接执行

unity

会打印用法并以0状态码退出。

Environment variables

环境变量

All CLI env vars use the

UNITY_

prefix. A CLI flag always overrides the corresponding env var.

Variable	Mirrors flag	Description
`UNITY_FORMAT`	`--format`	Output format ( `human` , `json` , `tsv` , `ndjson` ). `HUB_FORMAT` is a deprecated alias.
`UNITY_EDITOR_VERSION`	`--editor-version`	Editor version (e.g. `2023.3.0f1` , `latest` , `lts` ).
`UNITY_ARCHITECTURE`	`--architecture`	Chip architecture ( `x86_64` , `arm64` ).
`UNITY_PROJECT_PATH`	path argument	Project path for the `open` command.
`UNITY_QUIET`	`--quiet`	Suppress non-essential output.
`UNITY_VERBOSE`	`--verbose`	Show full error details on failure.
`UNITY_NON_INTERACTIVE`	`--non-interactive`	Disable interactive prompts.
`UNITY_NO_BANNER`	`--no-banner`	Suppress the branded banner.
`UNITY_RUN_TIMEOUT`	`--timeout`	Timeout for `unity run` in seconds.
`UNITY_TEST_TIMEOUT`	`--timeout`	Timeout for `unity test` in seconds.
`UNITY_CLOUD_ORG`	`--cloud-org`	Active Unity Cloud organization id or name for a single call.
`UNITY_SERVICE_ACCOUNT_ID`	—	Service account client ID for non-interactive (CI) auth.
`UNITY_SERVICE_ACCOUNT_SECRET`	—	Service account client secret for non-interactive (CI) auth.
`UNITY_PROXY`	`--proxy`	HTTP/HTTPS/SOCKS/PAC proxy URL. Takes precedence over `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` and the persisted `proxy.json` setting.
`UNITY_NO_UPDATE_CHECK`	—	Disable the background "update available" check (see `unity config update-check` ).
`UNITY_LOG_PROXY`	`--log-proxy`	Log one redacted entry per outbound request to `proxy-request.json` . Truthy values: `1` , `true` .
`UNITY_NO_ELEVATE`	`--no-elevate`	Windows: skip the elevated (UAC) install helper for `install` / `install-modules` — for user-writable locations and CI shells that can't answer a UAC prompt.
`UNITY_INSTALL_RETRIES`	`--retries`	Number of times `install-modules` retries a module whose download/validation fails. `0` disables retries.

CI service account auth: Set both

UNITY_SERVICE_ACCOUNT_ID

and

UNITY_SERVICE_ACCOUNT_SECRET

to skip the browser OAuth flow — this keeps the secret out of the process argument list and shell history. These map to the

--client-id

--secret-from-stdin

inputs of

unity auth login

, but reading the credentials from the environment isn't a full login: it doesn't run the interactive flow or persist credentials to the keyring.

所有CLI环境变量均以

UNITY_

为前缀。CLI标志始终覆盖对应的环境变量。

变量	对应标志	描述
`UNITY_FORMAT`	`--format`	输出格式（ `human` 、 `json` 、 `tsv` 、 `ndjson` ）。 `HUB_FORMAT` 是已弃用的别名。
`UNITY_EDITOR_VERSION`	`--editor-version`	编辑器版本（例如 `2023.3.0f1` 、 `latest` 、 `lts` ）。
`UNITY_ARCHITECTURE`	`--architecture`	芯片架构（ `x86_64` 、 `arm64` ）。
`UNITY_PROJECT_PATH`	路径参数	`open` 命令的项目路径。
`UNITY_QUIET`	`--quiet`	抑制非必要输出。
`UNITY_VERBOSE`	`--verbose`	失败时显示完整错误详情。
`UNITY_NON_INTERACTIVE`	`--non-interactive`	禁用交互式提示。
`UNITY_NO_BANNER`	`--no-banner`	隐藏品牌化头部。
`UNITY_RUN_TIMEOUT`	`--timeout`	`unity run` 的超时时间（秒）。
`UNITY_TEST_TIMEOUT`	`--timeout`	`unity test` 的超时时间（秒）。
`UNITY_CLOUD_ORG`	`--cloud-org`	单次调用使用的Unity Cloud组织ID或名称。
`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_LOG_PROXY`	`--log-proxy`	将每个出站请求的一条脱敏记录写入 `proxy-request.json` 。有效值： `1` 、 `true` 。
`UNITY_NO_ELEVATE`	`--no-elevate`	Windows系统：跳过 `install` / `install-modules` 的提升权限（UAC）安装助手——适用于用户可写入的位置和无法响应UAC提示的CI Shell。
`UNITY_INSTALL_RETRIES`	`--retries`	`install-modules` 对下载/验证失败的模块进行重试的次数。 `0` 表示禁用重试。

CI服务账户认证： 同时设置

UNITY_SERVICE_ACCOUNT_ID

和

UNITY_SERVICE_ACCOUNT_SECRET

可跳过浏览器OAuth流程——这样可避免密钥出现在进程参数列表和Shell历史中。这些对应

unity auth login

的

--client-id

--secret-from-stdin

输入，但从环境读取凭证并非完整登录：不会运行交互式流程，也不会将凭证持久化到密钥环。

Getting help

获取帮助

If a command fails or you're unsure of the available options, append

-h

--help

to any command or subcommand:

bash

unity --help
unity install --help
unity projects --help
unity projects create --help

This works at every level of the command hierarchy.

如果命令失败或不确定可用选项，可在任何命令或子命令后添加

-h

或

--help

：

bash

unity --help
unity install --help
unity projects --help
unity projects create --help

这适用于命令层级的每个级别。

Exit codes

退出码

Code	Meaning
0	Success
1	General error
2	Bad arguments
3	Authentication failure
4	Precondition not met (e.g. no license active, floating server not configured)
6	Command-specific failure
130	Interrupted — Ctrl+C / SIGINT (128 + 2)
143	Terminated by SIGTERM (128 + 15) — e.g. `kill` or a CI/runner timeout. Emitted by long-running commands that install a signal handler to clean up first (currently `unity build` , which scrubs the temporary Android keystore).

The

cloud

and

auth

commands map an authentication failure (expired/missing session, rejected sign-in) to

, and any other operational failure (network, server error) to

— so scripts can reliably tell "sign in again" apart from a genuine command failure.

代码	含义
0	成功
1	通用错误
2	参数错误
3	认证失败
4	前置条件未满足（例如无激活许可证、未配置浮动服务器）
6	命令特定错误
130	中断——Ctrl+C / SIGINT（128 + 2）
143	被SIGTERM终止（128 + 15）——例如 `kill` 或CI/运行器超时。由安装了信号处理程序以先清理的长时间运行命令发出（目前为 `unity build` ，会清理临时Android密钥库）。

cloud

和

auth

命令会将认证失败（会话过期/缺失、登录被拒绝）映射为

，将其他操作失败（网络、服务器错误）映射为

——因此脚本可可靠区分“重新登录”和真正的命令失败。

Commands

命令

The full per-command reference — syntax, flags, and examples — lives in grouped files under

references/

. Read the file for the command group you need; all the global flags, environment variables, and exit codes above apply throughout. Every command also supports

-h

--help

(see Getting help).

Commands	Reference file
`auth` (login / logout / status), `license` (activate / return / server), `cloud` (org / project)	auth-license-cloud.md
`editors` (list / add / default / path / install-path / info / upgrade / module), `install` , `uninstall` , `modules` , `install-modules`	editors-install.md
`projects` (list / create / new / clone / open / link / require / upgrade / export / import / pin), `releases` , `templates`	projects-templates.md
`config` (proxy / update-check), `hub install`	config-hub.md
`run` , `test` , `build`	build-run-test.md
`logs` , `doctor` , `env` , `cache` , `analytics` , `changelog` , `language` , `completion` , `bug` , `upgrade` , `self-uninstall` , `diagnose proxy`	diagnostics-maintenance.md
`mcp` (+ `configure` ), connected editors ( `pipeline` / `command` / `status` / `list` ), `shell` , development-only ( `eval` / `cloud-pipeline` / `collab` )	integration-advanced.md

完整的命令参考——语法、标志和示例——位于

references/

下的分组文件中。请阅读你需要的命令组对应的文件；上述所有全局标志、环境变量和退出码均适用于所有命令。每个命令也支持

-h

--help

（参见获取帮助）。

命令	参考文件
`auth` （登录/登出/状态）、 `license` （激活/归还/服务器）、 `cloud` （组织/项目）	auth-license-cloud.md
`editors` （列出/添加/默认/路径/安装路径/信息/升级/模块）、 `install` 、 `uninstall` 、 `modules` 、 `install-modules`	editors-install.md
`projects` （列出/创建/新建/克隆/打开/关联/要求/升级/导出/导入/固定）、 `releases` 、 `templates`	projects-templates.md
`config` （代理/更新检查）、 `hub install`	config-hub.md
`run` 、 `test` 、 `build`	build-run-test.md
`logs` 、 `doctor` 、 `env` 、 `cache` 、 `analytics` 、 `changelog` 、 `language` 、 `completion` 、 `bug` 、 `upgrade` 、 `self-uninstall` 、 `diagnose proxy`	diagnostics-maintenance.md
`mcp` （+ `configure` ）、连接的编辑器（ `pipeline` / `command` / `status` / `list` ）、 `shell` 、仅开发用（ `eval` / `cloud-pipeline` / `collab` ）	integration-advanced.md

Common workflows

常见工作流

Bootstrap a new project from scratch

从零开始引导新项目

For a guided end-to-end experience — concept questions, installing the Editor in the background while you plan, package selection, and monetization handoff — use the new-unity-project
skill. This section is the raw CLI recipe that skill builds on; use it directly when you just want the commands.

Take an idea to a running, version-controlled project using only the CLI. Decide the target platforms first — they determine which Editor modules you install in step 2. You can add modules later (

unity install-modules

), but a project can't build for a platform until that platform's module is installed, so it's simplest to decide up front.

bash

undefined

如果需要引导式端到端体验——包括概念探讨、在你规划时后台安装编辑器、包选择以及变现交接——请使用**
new-unity-project
**技能。本节是该技能基于的原始CLI步骤；当你只需要命令时可直接使用。

仅使用CLI将创意转化为可运行的版本控制项目。首先确定目标平台——它们决定了你在步骤2中需要安装的编辑器模块。你可以稍后添加模块（

unity install-modules

），但项目在安装对应平台的模块前无法为该平台构建，因此最好提前决定。

bash

undefined

1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md).

1. 确认CLI可用，且已登录并获得许可证（参见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

unity --version unity auth status --format json # 如果未登录：unity auth login unity license status --format json # 如果无激活许可证：unity license activate

2. Pick and install an Editor with the modules your target platforms need.

2. 选择并安装包含目标平台所需模块的编辑器。

Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream

默认选择最新LTS版本（最稳定，约2年补丁支持）。仅当LTS版本中没有所需功能时才选择技术流版本（--stream tech）；将--stream beta/alpha版本仅用于评估，绝不要用于打算发布的项目。有发布期限时优先选择LTS版本。

release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as

（在任何需要版本的地方都可以使用lts/latest别名。）

evaluation-only, never for a project you intend to ship. A deadline argues for LTS.

—

(lts / latest aliases work wherever a version is accepted.)

—

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

unity releases --stream lts --limit 5 --format json unity install lts --module android --module ios --yes --accept-eula # 可添加--module webgl等 unity editors --installed --format json # 确认安装完成

3. List the real template ids this Editor offers — don't guess them.

3. 列出该编辑器提供的真实模板ID——不要猜测。

unity templates list --editor lts --format json

Common ids: com.unity.template.3d, com.unity.template.2d, and a URP template (id varies by version).

常见ID：com.unity.template.3d、com.unity.template.2d，以及URP模板（ID因版本而异）。

4. Create the project. The first positional arg is the NAME; --path sets the parent directory.

4. 创建项目。第一个位置参数是项目名称；--path设置父目录。

All options supplied, so it won't prompt; add --non-interactive in CI.

已提供所有选项，因此不会弹出提示；在CI环境中添加--non-interactive。

unity projects create "MyGame" --path ~/UnityProjects
--editor-version lts --template com.unity.template.3d


**Source control — let the user choose.** The CLI publishes the new project to a fresh remote in
one step for any provider. **Always pass tokens on stdin** (`--git-token-stdin`) so secrets never
land in shell history or the process list. Pick based on the project — don't default to one:

- **Git — GitHub / GitLab** (`--vcs github` / `--vcs gitlab`). Ubiquitous. For asset-heavy games
  add **Git LFS** (`--git-lfs`) so large binaries don't bloat history.
- **Unity Version Control — UVCS** (`--vcs uvcs`). Unity's own VCS, built for large binary game
  assets: it handles them natively (**no LFS needed**) and supports file locking — often the
  better fit for art-heavy projects or larger teams. Auth uses your Unity sign-in; `--vcs-region`
  selects the region.

```bash

unity projects create "MyGame" --path ~/UnityProjects
--editor-version lts --template com.unity.template.3d


**版本控制——让用户选择。** CLI可一步将新项目发布到任何提供商的全新远程仓库。**始终通过标准输入传递令牌**（`--git-token-stdin`），这样密钥就不会出现在Shell历史或进程列表中。根据项目选择——不要默认某一种：

- **Git — GitHub / GitLab**（`--vcs github`/`--vcs gitlab`）。应用广泛。对于资产密集型游戏，添加**Git LFS**（`--git-lfs`），避免大型二进制文件膨胀历史记录。
- **Unity版本控制——UVCS**（`--vcs uvcs`）。Unity自研的版本控制系统，专为大型二进制游戏资产设计：原生处理这些资产（**无需LFS**）并支持文件锁定——通常更适合艺术密集型项目或大型团队。认证使用你的Unity登录信息；`--vcs-region`选择区域。

```bash

Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you

Git（GitHub）——如果游戏不是资产密集型，可去掉--git-lfs。如果想在首次提交前添加包/资产，添加--no-initial-commit（参见new-unity-project流程）。

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.3d
--vcs github --git-namespace my-org --git-repo my-game
--git-visibility private --git-default-branch main --git-token-stdin --git-lfs

Unity Version Control (UVCS) — handles binaries natively, so no LFS:

Unity版本控制（UVCS）——原生处理二进制文件，因此无需LFS：

unity projects create "MyGame" --path ~/UnityProjects
--editor-version lts --template com.unity.template.3d
--vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>


Feed the token to `--git-token-stdin` from a secret store, never a literal — e.g.
`… --git-token-stdin <<<"$GIT_TOKEN"` where `$GIT_TOKEN` comes from your CI/secret manager
(UVCS uses your Unity sign-in, so no token is needed). See
[references/projects-templates.md](references/projects-templates.md) for the full
source-control flag set. For a purely local Git repository instead, initialize git with a
Unity-appropriate ignore so the multi-GB `Library/` and other generated folders are never committed:

```bash
cd ~/UnityProjects/MyGame
git init -b main

unity projects create "MyGame" --path ~/UnityProjects
--editor-version lts --template com.unity.template.3d
--vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>


从密钥库向`--git-token-stdin`提供令牌，绝不要直接写字面量——例如`… --git-token-stdin <<<"$GIT_TOKEN"`，其中`$GIT_TOKEN`来自你的CI/密钥管理器（UVCS使用你的Unity登录信息，因此无需令牌）。完整的版本控制标志集请参见[references/projects-templates.md](references/projects-templates.md)。如果只想创建本地Git仓库，请使用适合Unity的忽略规则初始化Git，避免多GB的`Library/`和其他生成文件夹被提交：

```bash
cd ~/UnityProjects/MyGame
git init -b main

Download (do not pipe to a shell) a maintained Unity .gitignore:

下载（不要通过管道传递给Shell）维护中的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将大型二进制文件排除在Git历史之外：

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


**What the CLI does and doesn't cover.** The CLI handles editor, project, and source control.
It does **not** manage UPM (Unity Package Manager) packages — to add packages beyond the
template headlessly, use the **`unity-package-management`** skill (C# PackageManager Client
API). For monetization/backend, hand off to the dedicated skills: `implement-in-app-purchases`
(IAP), `levelplay-unity-integration` (ads), or `build-live-game` (accounts, cloud save,
economy, remote config, leaderboards). Open the project to start working:
`unity open ~/UnityProjects/MyGame`.

git lfs install git lfs track ".psd" ".fbx" ".wav" ".mp3" "*.png" # 根据你的资产类型调整 git add .gitattributes

git add -A git status # 检查：Library/ Temp/ obj/ Build/ 一定不能被暂存 git commit -m "Initial Unity project: MyGame" git ls-files | grep -c '^Library/' # 必须输出0


**CLI能处理和不能处理的内容。** CLI处理编辑器、项目和版本控制。它**不**管理UPM（Unity包管理器）包——如果需要在无界面环境下添加模板之外的包，请使用**`unity-package-management`**技能（C# PackageManager Client API）。对于变现/后端功能，请交给专门的技能：`implement-in-app-purchases`（IAP）、`levelplay-unity-integration`（广告）或`build-live-game`（账户、云存档、经济系统、远程配置、排行榜）。打开项目开始开发：`unity open ~/UnityProjects/MyGame`。

Find and install a missing editor

查找并安装缺失的编辑器

bash

undefined

bash

undefined

1. Check what's installed

1. 检查已安装的编辑器

unity editors --installed --format json

2. Browse available LTS versions

2. 浏览可用的LTS版本

unity releases --lts --limit 5 --format json

3. Install

3. 安装

unity install 6000.0.47f1 --yes --accept-eula

undefined

unity install 6000.0.47f1 --yes --accept-eula

undefined

Open a project with the correct editor

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

bash

undefined

bash

undefined

1. Check the project's required editor version

1. 检查项目所需的编辑器版本

unity projects info /path/to/MyProject --format json

Look at "editorVersion" in the result

查看结果中的"editorVersion"

2. Confirm that editor is installed

2. 确认该编辑器已安装

unity editors --installed --format json

3. Open (warns if the editor version is missing)

3. 打开（如果编辑器版本缺失会发出警告）

unity open /path/to/MyProject

undefined

unity open /path/to/MyProject

undefined

CI: activate a license, then build

CI：激活许可证然后构建

bash

undefined

bash

undefined

1. Sign in non-interactively with a service account

1. 使用服务账户非交互式登录

unity auth login --client-id "$UNITY_SERVICE_ACCOUNT_ID" --secret-from-stdin <<<"$UNITY_SERVICE_ACCOUNT_SECRET"

2. Activate the entitlement license (or use --serial / --floating)

2. 激活授权许可证（或使用--serial / --floating）

unity license activate

3. Build

3. 构建

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

4. Return the seat when done (floating/assigned)

4. 完成后归还许可证（浮动/分配式）

unity license return --yes

undefined

unity license return --yes

undefined

CI: headless build

CI：无界面构建

Prefer the dedicated

unity build

command (handles batch mode, logging, and CI flags):

bash

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

Or use

unity run

(batch mode is automatic — never pass

-batchmode

-quit

bash

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

优先使用专用的

unity build

命令（处理批处理模式、日志和CI标志）：

bash

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

）：

bash

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

CI: run tests and publish results

CI：运行测试并发布结果

bash

unity test /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --mode EditMode \
  --output ./test-results.xml \
  --allow-install \
  --timeout 600
echo "Exit code: $?"   # 0 = pass, 6 = test failures

bash

unity test /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --mode EditMode \
  --output ./test-results.xml \
  --allow-install \
  --timeout 600
echo "Exit code: $?"   # 0 = 通过，6 = 测试失败

Debug the CLI

调试CLI

bash

undefined

bash

undefined

Check auth + installed editors + recent errors in one command

一次命令检查认证+已安装编辑器+最近错误

unity doctor --format json

Follow live logs during an install

在安装过程中实时查看日志

unity logs --follow --level info

---

unity logs --follow --level info

---

Notes

注意事项

```
--non-interactive
```
and
```
--yes
```
together suppress all prompts — use both in CI.
```
--format json
```
always produces machine-readable output; prefer it over parsing human text. Error envelopes are pretty-printed with the same 2-space indent as success envelopes.

unity <version> [path]

is a shorthand for

unity open [path] --editor-version <version>

. Works with

lts

latest

, or a full version string like

6000.0.47f1

The CLI supports kubectl-style plugins: any
```
unity-<name>
```
binary on PATH is callable as
```
unity <name>
```
.
Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, while SGR color/style codes are preserved.
The CLI is currently in beta (latest:
```
1.0.0-beta.2
```
). It moved to 1.0 versioning at
```
1.0.0-beta.1
```
; it's still a beta, so keep
```
UNITY_CLI_CHANNEL=beta
```
in the install command until GA ships, after which that part can be dropped.
As of beta.8 the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with
```
unity config update-check off
```
or the
```
UNITY_NO_UPDATE_CHECK
```
env var.
Outbound HTTP from every CLI command honors the resolved proxy (see
```
unity config proxy
```
). Inspect what the CLI actually resolved with
```
unity env --format json
```
or
```
unity doctor --format json
```
— both surface the active proxy URL, its source, and auth source.

```
--non-interactive
```
和
```
--yes
```
一起使用可抑制所有提示——在CI环境中同时使用这两个标志。
```
--format json
```
始终生成机器可读的输出；优先使用它而非解析人类可读文本。错误信息包与成功信息包一样使用2空格缩进进行格式化。

unity <version> [path]

是

unity open [path] --editor-version <version>

的简写。适用于

lts

、

latest

或完整版本字符串如

6000.0.47f1

。

CLI支持kubectl风格的插件：PATH上的任何
```
unity-<name>
```
二进制文件都可通过
```
unity <name>
```
调用。
终端输出已针对服务器提供的值（项目标题、编辑器版本、模块名称）的控制字符/转义序列注入进行加固——C0控制字符和非SGR转义序列会从表格/列表/树输出中移除，而SGR颜色/样式代码会保留。
CLI目前处于beta阶段（最新版本：
```
1.0.0-beta.2
```
）。在
```
1.0.0-beta.1
```
时开始使用1.0版本号；仍处于beta阶段，因此在正式版发布前，请在安装命令中保留
```
UNITY_CLI_CHANNEL=beta
```
，之后可移除该部分。
从beta.8版本开始，CLI会在后台检查更新，并在交互式会话中打印不显眼的“可用更新”通知（绝不会延迟命令执行）。可通过
```
unity config update-check off
```
或
```
UNITY_NO_UPDATE_CHECK
```
环境变量关闭该功能。
每个CLI命令的出站HTTP请求都会遵循解析后的代理（参见
```
unity config proxy
```
）。可通过
```
unity env --format json
```
或
```
unity doctor --format json
```
查看CLI实际解析的内容——两者都会显示活动代理URL、来源和认证来源。