Unity command-line interface (CLI) reference

Explore the Unity CLI commands, options, output formats, and exit codes you can use to install and manage Unity Editors and modules from a terminal.

阅读时间18 分钟

最后更新于 1 天前

注意

The Unity CLI is experimental.

Find the commands and options available in the Unity CLI. For installation and common task instructions, refer to Use the Unity CLI. To use the Unity CLI to control the Unity Editor, install and set up the Unity Pipeline package. For an example of how you can use the Unity CLI with Unity Pipeline, refer to the Unity CLI introduction video.

Run

unity --help

to check the authoritative command list for your installed version, including any commands not yet covered on this page.

Commands

Editors and modules

Command	Alias	Description
`install`	`i`	Installs a Unity Editor version, optionally with modules.
`install-modules`	`im`	Adds modules to an installed Editor version.
`uninstall`	`u`	Removes an installed Editor version.
`editors`	`e`	Lists available releases and installed Editors, add local installs, set the default Editor, upgrade Editors, and list running instances.
`editor`		Manages a single installation of a Editor version. For example use `editor module remove` to remove installed modules on a specific Editor version.
`install-path`	`ip`	Shows or changes the path where the CLI installs Editors.
`modules`		Lists available modules for an Editor version ( `modules list <version>` ).
`releases`		Lists available Unity releases from the release feed.
`hub`		Installs the Unity Hub desktop application ( `hub install` ).

Projects, builds, and templates

Command	Alias	Description
`open`		Opens a Unity project in a compatible Editor version.
`close`		Closes the Unity Editor that has a project open. Neither the default nor `--force` saves your work.
`projects`	`p`	Manages registered Unity projects: list, create, clone, open, link, pin, report disk size, and close.
`templates`	`t`	Lists, inspects, creates, and manages project templates.
`build`		Builds a project in batch mode with CI-friendly flags, including Android signing and export options.
`run`		Runs a project in batch mode, or run a registered Editor command headlessly with `--command` .
`test`		Runs a project's Edit Mode and Play Mode tests through the Editor test runner and write an NUnit report.

Accounts, licenses, and Unity Cloud

Command	Alias	Description
`auth`	`a`	Sign in, check login state, or sign out.
`license`		Lists, activates, and returns Unity licenses on this machine.
`cloud`		Shows cloud sign-in state, organizations, and Unity Cloud projects.

Unity Collaboration

Command	Alias	Description
`collaboration`	`collab`	Manages Unity Collaboration annotations, attachments, thumbnails, and reactions, and link Jira issues to them.

Version control

unity vcs

covers Git, GitHub, GitLab, self-hosted Git, and Unity Version Control (UVCS). It's separate from Unity Collaboration.

Command	Description
`vcs setup`	Sets up a project from no version control to its first commit on a remote. Asks only what it can't detect, and prints the equivalent flag command.
`vcs status`	Shows changes grouped by their meaning to Unity, including `.meta` file pairing problems.
`vcs sync`	Pulls safely: refuse while an Editor holds the project, fetch commits and LFS objects, then report the reimport.
`vcs switch`	Switches branches safely and report the impact before you switch.
`vcs doctor`	Checks the repository settings, ignore rules, and LFS configuration a Unity project needs. `--fix` repairs what it can.
`vcs merge-setup`	Configures Unity scene and prefab merging (UnityYAMLMerge) for the repository.
`vcs conflicts`	Lists unresolved merge conflicts, classified by whether they can merge automatically.
`vcs explain`	Explains in plain language what each side of a conflict changed.
`vcs resolve`	Resolves a conflicted Unity asset using the Editor's own merge tool.
`vcs diff`	Compares a scene or prefab by GameObject and component name rather than by `fileID` .
`vcs summarize`	Summarizes branch changes so you can paste them into a pull request.
`vcs affected`	Reports which assets, assemblies, and tests a change affects. Reports a lower bound when applicable.
`vcs hooks`	Installs or removes Git hooks that run Unity integrity checks on your commits.
`vcs providers`	Reports which Git providers this machine can reach, as whom, and what each host allows.
`vcs git`	Git-only verbs, including `git worktree` and `git migrate-lfs` .
`vcs uvcs`	Unity Version Control reads, including `uvcs locks` , `uvcs changesets` , and `uvcs review` .

Connected Editors and AI agents

Command	Alias	Description
`command`	`cmd`	Forwards a command to a connected Unity Editor, or list the commands a connected Editor exposes.
`list`		Lists every tool a connected Editor registers, with its parameter schema.
`pipeline`	`pipe`	Installs, upgrade, and inspect the Unity pipeline package that connects the CLI to the Editor.
`status`		Shows the live state of connected Editors: port, project path, version, and process ID.
`mcp`		Starts a Model Context Protocol (MCP) server for AI agents, or configure agent clients to use it.
`job`		Manages detached Editor command jobs.
`skill`		Reads the Unity CLI agent skill, or installs it into an AI client.

Diagnostics and configuration

Command	Alias	Description
`doctor`		Prints a diagnostic snapshot and environment health checks.
`diagnose`		Prints focused diagnostic reports, such as a redacted proxy report.
`logs`		Reads and tail the CLI's log file.
`env`		Prints environment paths and versions used by the CLI and the Hub.
`config`		Views or changes CLI settings by key ( `get` , `set` , `list` , `unset` ) or through dedicated subcommands, such as, the proxy server and update checks.
`analytics`		Manages usage-data consent ( `opt-in` , `opt-out` , `status` ).
`cache`		Shows or cleans the download cache, or print a deterministic cache key for a project's `Library` folder ( `cache key` ).
`bug`		Reports a bug to Unity, interactively or through flags.
`language`	`lang`	Shows or changes the CLI display language.
`completion`		Prints a shell completion script for bash, zsh, fish, or PowerShell.
`shell`		Starts an interactive session that runs many commands in one warm process.
`changelog`		Shows release notes for the installed CLI.
`plugin`		Views and manages the external components Unity installs for you, such as, the Unity Version Control client.

CLI lifecycle

Command	Alias	Description
`self-update`		Updates the `unity` CLI binary to the latest release. `upgrade` remains a working alias.
`self-uninstall`		Removes the CLI binary, environment files, and stored credentials.
`version`		Prints the CLI's version, release channel, commit, platform, architecture, and runtime.
`help`		Displays help for any command. Equivalent to `--help` .

Help commands

Command	Description
`unity --help`	Top-level help, including the list of commands.
`unity <command> --help`	Help for a specific command and its options.
`unity <command> <subcommand> --help`	Help for a subcommand (for example, `unity editors add --help` ).

提示

unity --help

is the authoritative source for flags in your installed version. This page covers the main commands. Your release might add flags or commands that appear only in

--help

Update the CLI

Use the built-in self-update command to install the latest CLI release:


unity self-update

unity upgrade

remains a working alias, so existing scripts keep running.

Print the CLI version

Print the CLI's version, release channel, commit, platform, architecture, and runtime as one object in any output format:


unity version --format json

A bare

unity --version

still prints only the version string. Set a machine format before the flag (

unity --format json --version

, or

UNITY_FORMAT=json unity --version

) to switch it to the same structured object, as the flag ends option parsing.

Install an Editor

Install a Unity Editor version, optionally with modules.


unity install [version] [options]

The

version

argument is positional and optional:

On an interactive terminal, omitting the version opens an interactive prompt.
On a non-interactive terminal (for example, a CI pipeline), omitting the version is an error.

Version aliases

Alias	Resolves to
`latest`	The newest available Editor release.
`lts`	The newest long-term support release.
`default`	The version configured as your default in the Unity CLI.
`6` , `6.5` , `2022` , and similar	The newest release within that major or minor stream.

Install options

Refer to

unity install --help

for the complete list.

Option	Usage	Description
`-c, --changeset <hash>`	`-c 9b001d489a54`	Changeset for the chosen Editor, required when the version isn't in the release list.
`-m, --module <id>`	`-m android` or `-m ios webgl`	Module IDs to install alongside the Editor. Accepts multiple values.
`--cm` , `--child-modules`	`--cm`	Also installs child modules of each selected module (for example, Android SDK & NDK under `android` ). `--childModules` also still works.
`-a, --architecture <arch>`	`-a arm64` or `-a x86_64`	macOS only. Selects between Apple silicon and Intel builds.

Install examples


unity install 6000.3.7f1unity install ltsunity install 6000.3.7f1 -c 9b001d489a54unity install 6000.3.7f1 -m android --cmunity install lts -m ios android webgl

注意

For available module IDs, refer to Add modules to a Unity Editor installation and the module ID table.

Install modules for an existing Editor

Add one or more modules to an Editor you already installed with the Hub or the CLI.


unity install-modules [options]

重要

You can only add modules to Editors that the Hub or CLI installed. Reinstall manually installed Editors through the Hub or CLI to add modules.

Install-modules options

Option	Required?	Description
`-e, --editor-version <version>`	No	Editor version to add the module to. If omitted on an interactive terminal, you receive a prompt.
`-m, --module <id>`	No	Module ID(s) to install. Accepts multiple values.
`-l, --list`	No	Lists installable modules for the target Editor instead of installing anything.
`--all`	No	Installs every available module for the target Editor.
`--cm` , `--child-modules`	No	Also installs child modules. Use `--no-cm` (or `--no-child-modules` ) to explicitly skip them. The previous `--childModules` / `--no-childModules` options also still work.

Install-modules examples


unity install-modules -e 6000.3.7f1 -m ios androidunity install-modules -e 6000.3.7f1 -lunity install-modules -e 6000.3.7f1 --allunity install-modules -e 6000.3.7f1 -m android --no-cm

Uninstall an Editor

Remove an installed Editor version.


unity uninstall <version>

uninstall examples


unity uninstall 6000.3.7f1

List and manage Editors

Inspect available releases and installed Editors, register locally installed Editors with the Hub, and set a default version.


unity editors [options]unity editors add <path...>unity editors default [version]

Editor options

Option	Alias	Description
`--releases`	`-r`	Shows available releases.
`--installed`	`-i`	Shows Editors installed on this machine.
`--verbose`		Includes additional detail in the output.
`--architecture <architecture>`	`-a`	Sets Editor architecture (x86_64 or arm64) the default setting is "unknown".
`--json`	N/A	Outputs the list in JSON format.
`--watch`	`-w`	Watches for editor changes and refresh output (press Ctrl-C to stop).
`--help`	`-h`	Displays help for this command.

Add an Editor


unity editors add /Applications/Unity/Hub/Editor/6000.3.7f1/Unity.appunity editors add "C:\Program Files\Unity\6000.3.7f1" "C:\Program Files\Unity\2022.3.40f1"

Identify the default Editor

Print the current default Editor, or set a new default by passing a version:


unity editors default               # show the defaultunity editors default 6000.3.7f1    # set the default

Editor command examples


unity editors -r       # list available releasesunity editors -i       # list installed Editorsunity editors -a       # combined list

Set or get the Editor install path

Show or change the directory where the CLI installs Unity Editors.


unity install-path [options]

Alias:

ip

. Run

unity install-path --help

for the current option list, including flags to display or update the path.

Open a project

Open a Unity project, resolving the Editor version declared by the project.


unity open <path>

You can omit the

open

keyword when the first argument is a path:


unity open ./MyProjectunity ./MyProject       # equivalent

Manage projects in the Hub registry

Manage the list of Unity projects the Hub knows about, so both the Hub UI and the CLI can find and open them.


unity projects [subcommand] [options]

Alias:

. Run

unity projects --help

to check the available commands and options in your installed CLI version.

The

auth

command manages your Unity account session.


unity auth loginunity auth statusunity auth logout

Command	Description
`unity auth login`	Opens a browser-based sign-in flow.
`unity auth status`	Prints the current signed-in user, if any.
`unity auth logout`	Signs out of the current session.
`unity auth consumers`	Lists the applications that have used your Unity sign-in on this machine.
`unity auth revoke <application>`	Stops an application from using your sign-in. Pass `--restore` to undo a revoke.

Change the CLI display language

Show the current CLI display language, or change it to a supported language.


unity language [options]

Alias:

lang

. Run

unity language --help

for the list of supported languages and the exact option names.

Output formats and automation

The CLI chooses a default output format based on the context and supports explicit formats for automation.

Format selection

Format	Selected when	Notes
`human`	Output goes to an interactive terminal.	Colorized, animated progress, aligned columns.
`tsv`	Output goes to a pipe or file.	Tab-separated, one record per line. Machine-parseable.
`json`	You set `--format json` (or `--json` ).	Structured output for use with `jq` and other tools. Uses a standard envelope with `success` , `command` , `data` , `errors` , and `warnings` .
`ndjson`	You set `--format ndjson` .	One JSON object per line. Long-running commands, such as `install` , stream typed progress frames and end with a result frame.
`github`	You set `--format github` .	Failures print as GitHub Actions annotations ( `::error::...` , `::warning::...` ) instead of plain text, so a red workflow step indicates what went wrong in its summary. Inert outside GitHub Actions.

Select a format explicitly with the global flag:


unity editors -i --format jsonunity editors -i --format tsvunity install lts --format ndjson

注意

--json

is accepted on every command as a global shorthand for

--format json

. When you supply both,

--format

takes precedence.

提示

When you pipe CLI output, the default format changes to tab-separated values (TSV). If a script expects human-readable text, set

--format human

explicitly, or parse TSV, JSON, or NDJSON instead. Use

json

for a single buffered result and

ndjson

when you also want streamed progress frames from long-running commands.

Color output

Use the global

--color <auto|always|never>

flag to control colored output directly instead of relying only on the

NO_COLOR

and

FORCE_COLOR

environment variables.

--no-color

is shorthand for

--color never

. Color affects only

human

output. The

json

tsv

, and

ndjson

formats never emit color.

Error output

The CLI writes errors and diagnostic messages to

stderr

, leaving

stdout

free for data output. In JSON mode, the CLI emits errors as

{"error": "..."}

stderr

To capture both streams in a shell:


unity install 6000.3.7f1 > install.log 2>&1

Exit codes

Code	Meaning
`0`	Success.
`1`	A general error occurred. Inspect `stderr` for details.
`2`	Usage error: invalid flags, invalid option values, or missing required arguments.
`3`	Authentication or authorization failure, such as a rejected sign-in or an expired session.
`4`	Configuration required: the arguments are valid, but a required preference or context isn't set.
`6`	The command's primary operation failed. For example, an Editor install failed, or the Editor exited with an error. For `unity test` , the run didn't finish, so it produced no test results. Refer to `8` for more information.
`7`	A Unity service couldn't be reached. The CLI retried before giving up, so this is safe for a script to retry; a `6` is terminal.
`8`	`unity test` only: The tests ran, and one or more failed. Scripts can't ever retry after exit code `8` .
`130`	The command was interrupted with Ctrl+C ( `SIGINT` ).
`143`	The command was terminated with `SIGTERM` , for example by `kill` or a CI runner timeout.

注意

When a CI job retries a failed

unity test

run, retry only exit code

. A

means the run didn't finish, for example because of a compile error, an unavailable license, an Editor crash, or

--timeout

, so a retry can still produce results. An

means the tests themselves failed, so a retry produces the same result.

Environment variables

Global CLI options have environment variable equivalents, and some behaviors are controlled only through the environment. A command-line flag takes precedence over its environment variable.

Variable	Effect
`UNITY_FORMAT`	Default output format ( `human` , `json` , `tsv` , `ndjson` , or `github` ). `HUB_FORMAT` remains supported as an alias.
`UNITY_QUIET`	Suppress non-essential output, like `--quiet` .
`UNITY_NO_BANNER`	Suppress the Unity banner, like `--no-banner` .
`UNITY_NON_INTERACTIVE`	Disable interactive prompts, like `--non-interactive` .
`UNITY_PAGER`	Pager for long human-readable output. Falls back to `PAGER` , then `less -RFX` . On Windows there is no built-in fallback: if neither variable is set and `less` is not on `PATH` , output is not paged.
`UNITY_NO_PAGER`	Never page output, like `--no-pager` .
`UNITY_PROJECT_PATH`	Default Unity project path for commands that accept `--project-path` .
`UNITY_CLOUD_ORG`	Default Unity Cloud organization for commands that accept `--cloud-org` .
`UNITY_PROXY`	Proxy server URL, like `--proxy` .
`UNITY_LOG_PROXY`	Log one redacted entry per outbound request for proxy troubleshooting, like `--log-proxy` .
`UNITY_INSTALL_RETRIES`	Number of retries for module downloads that fail intermittently, like `--retries` . `0` disables retries.
`UNITY_NO_ELEVATE`	Windows only. Skip the elevated (UAC) install helper, like `--no-elevate` .
`UNITY_BUILD_TIMEOUT`	End `unity build` after this many seconds, similar to `--timeout` . Disabled by default.
`UNITY_NO_UPDATE_CHECK`	Disable the background check for CLI updates.
`UNITY_NO_CLOUD`	Create projects without the Unity Cloud step, like `--no-cloud` .
`UNITY_INSTALL_MISSING_TOOLS`	Allow an unattended run to install missing tools, such as Git LFS, without asking.
`UNITY_NO_CRASH_REPORT`	Disable anonymous crash and error reporting.
`UNITY_NO_CONSENT_PROMPT`	Suppress the one-time first-run analytics consent prompt without recording a choice.
`UNITY_SERVICE_ACCOUNT_ID` , `UNITY_SERVICE_ACCOUNT_SECRET`	Authenticate as a Unity service account for unattended workflows. Set both.

Progress output

Long-running commands (such as

install

) render animated progress bars on an interactive terminal and a static summary when complete. Progress output is for human readers. Don't parse it in scripts. For a machine-readable result, use

--format json

; to also stream machine-readable progress updates while the command runs, use

--format ndjson

, which emits typed progress frames followed by a final result frame.

Log locations

The CLI writes its own log file,

cli-log.json

, in the shared Unity Hub logs directory. Read and follow it with

unity logs

, or include it in a diagnostic snapshot with

unity doctor

Platform	Path
Windows	`%UserProfile%\AppData\Roaming\UnityHub\logs`
macOS	`~/Library/Application Support/UnityHub/logs`
Linux	`~/.config/UnityHub/logs`

You can also open the log folder from the Hub: Account > Help and Support > Logs.

Migrate from the Hub CLI

If you have scripts targeting the CLI embedded in the Unity Hub desktop application (invoked with

-- --headless

), the following tables summarize the behavioral and syntactic differences. For full Hub CLI syntax, refer to Hub CLI reference.

Invocation

	Hub CLI	Unity CLI
How to run	`"Unity Hub.exe" -- --headless <command>`	`unity <command>`
Dependency	Requires the full Unity Hub desktop application.	Standalone binary; no Hub installation required.

Command and flag changes

Area	Hub CLI	Unity CLI
`install` version	`--version` / `-v <version>` (required flag)	`[version]` (optional positional argument)
`install-modules` editor version	`--version` / `-v <version>` (required)	`-e, --editor-version <version>` (optional)
`install-modules` module	`--module` / `-m <id>` (required)	`-m, --module <id>` (optional)
`editors` add local Editor	`editors --add <path>` (flag)	`editors add <path...>` (command; accepts multiple paths)
`-v` on `install`	Editor version	Reserved. `-V` prints the CLI version.
`help` command	Platform-specific help text files	Replaced by `--help` on every command.

Output and errors

Area	Hub CLI	Unity CLI
Default output	Plain text, always	`human` on an interactive terminal; `tsv` when piped
Structured output	`--json` per command (where supported)	Global `--format json` ( `--json` kept for compatibility)
Errors	Written to `stdout`	Written to `stderr` (JSON errors: `{"error": "..."}` on `stderr` )
Progress	Plain text lines, for example `downloading 23.50%`	Animated progress bar; static summary on completion
Exit codes	`0` success, `1` error	Differentiated codes for usage, auth, and command failures. Refer to Exit codes.

Removed global flags

These Hub CLI flags have no equivalent in the Unity CLI:

--headless

--errors

--silent

--logLevel

-l

--bugReporter

--debugMode

--inspect

--userEmail

--theme

--editorLicense

--servicesUrlInterval

--cloudEnvironment

New commands

The Unity CLI includes many commands that are not available in the Hub CLI, including

auth

open

projects

uninstall

self-update

build

test

license

shell

, and

mcp

. Refer to the Commands tables for the full list. The path shorthand

unity ./MyProject

is equivalent to

unity open ./MyProject

Impact summary

重要

Review existing scripts and continuous integration (CI) pipelines before switching. The following items describe the areas most likely to require changes.

High: scripts that fail without updates

Replace
```
-- --headless
```
invocations with
```
unity
```
.
Replace
```
install -v <version>
```
with
```
install <version>
```
(positional).

Replace

install-modules --version

-v

with

--editor-version

-e

Replace
```
editors --add
```
with
```
editors add
```
.

Medium: behavior changes that can produce wrong results

Piped
```
stdout
```
defaults to TSV, not plain text.
Errors go to
```
stderr
```
, not
```
stdout
```
.
Progress output format changed. Don't parse it.

Low: additive changes that don't break existing usage

New commands:
```
auth
```
,
```
open
```
,
```
projects
```
,
```
uninstall
```
,
```
self-update
```
.
New flags such as
```
--verbose
```
,
```
--list
```
, and
```
--all
```
.
Version aliases:
```
latest
```
,
```
lts
```
,
```
default
```
, and short majors.
New exit code
```
130
```
for user cancellation.

Unity command-line interface (CLI) reference

Commands

Editors and modules

Command

Alias

Description

Projects, builds, and templates

Command

Alias

Description

Accounts, licenses, and Unity Cloud

Command

Alias

Description

Unity Collaboration

Command

Alias

Description

Version control

Command

Description

Connected Editors and AI agents

Command

Alias

Description

Diagnostics and configuration

Command

Alias

Description

CLI lifecycle

Command

Alias

Description

Help commands

Command

Description

Update the CLI

Print the CLI version

Install an Editor

Version aliases

Alias

Resolves to

Install options

Option

Usage

Description

Install examples

Install modules for an existing Editor

Install-modules options

Option

Required?

Description

Install-modules examples

Uninstall an Editor

uninstall examples

List and manage Editors

Editor options

Option

Alias

Description

Add an Editor

Identify the default Editor

Editor command examples

Set or get the Editor install path

Open a project

Manage projects in the Hub registry

Sign in and out

Command

Description

Change the CLI display language

Output formats and automation

Format selection

Format

Selected when

Notes

Color output

Error output

Exit codes

Code

Meaning