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.

阅读时间11 分钟

最后更新于 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`	Install a Unity Editor version, optionally with modules.
`install-modules`	`im`	Add modules to an installed Editor version.
`uninstall`	`u`	Remove an installed Editor version.
`editors`	`e`	List available releases and installed Editors, add local installs, set the default Editor, upgrade Editors, and list running instances.
`editor`		Manage 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`	Show or change the path where the CLI installs Editors.
`modules`		List available modules for an Editor version ( `modules list <version>` ).
`releases`		List available Unity releases from the release feed.
`hub`		Install the Unity Hub desktop application ( `hub install` ).

Projects, builds, and templates

Command	Alias	Description
`open`		Open a Unity project in a compatible Editor version.
`projects`	`p`	Manage registered Unity projects: list, create, clone, open, link, pin, report disk size, and close.
`templates`	`t`	List, inspect, create, and manage project templates.
`build`		Build a project in batch mode with CI-friendly flags, including Android signing and export options.
`run`		Run a project in batch mode, or run a registered Editor command headlessly with `--command` .
`test`		Run 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`		List, activate, and return Unity licenses on this machine.
`cloud`		Show cloud sign-in state, organizations, and Unity Cloud projects.

Connected Editors and AI agents

Command	Alias	Description
`command`	`cmd`	Forward a command to a connected Unity Editor, or list the commands a connected Editor exposes.
`list`		List every tool a connected Editor registers, with its parameter schema.
`pipeline`	`pipe`	Install, upgrade, and inspect the Unity pipeline package that connects the CLI to the Editor.
`status`		Show the live state of connected Editors: port, project path, version, and process ID.
`mcp`		Start a Model Context Protocol (MCP) server for AI agents, or configure agent clients to use it.

Diagnostics and configuration

Command	Alias	Description
`doctor`		Print a diagnostic snapshot and environment health checks.
`diagnose`		Print focused diagnostic reports, such as a redacted proxy report.
`logs`		Read and tail the CLI's log file.
`env`		Print environment paths and versions used by the CLI and the Hub.
`config`		View or change CLI settings, such as the proxy server and update checks.
`analytics`		Manage usage-data consent ( `opt-in` , `opt-out` , `status` ).
`cache`		Show or clean the download cache.
`bug`		Report a bug to Unity, interactively or through flags.
`language`	`lang`	Show or change the CLI display language.
`completion`		Print a shell completion script for bash, zsh, fish, or PowerShell.
`shell`		Start an interactive session that runs many commands in one warm process.
`changelog`		Show release notes for the installed CLI.

CLI lifecycle

Command	Alias	Description
`upgrade`		Self-update the `unity` CLI binary.
`self-uninstall`		Remove the CLI binary, environment files, and stored credentials.
`help`		Display 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 upgrade

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` , `--childModules`	`--cm`	Also install child modules of each selected module (for example, Android SDK & NDK under `android` ).
`-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	List installable modules for the target Editor instead of installing anything.
`--all`	No	Install every available module for the target Editor.
`--cm` , `--childModules`	No	Also install child modules. Use `--no-cm` (or `--no-childModules` ) to explicitly skip them.

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`	Show available releases.
`--installed`	`-i`	Show Editors installed on this machine.
`--verbose`		Include additional detail in the output.
`--architecture <architecture>`	`-a`	Set Editor architecture (x86_64 or arm64) the default setting is "unknown".
`--json`	N/A	Output the list in JSON format.
`--watch`	`-w`	Watch for editor changes and refresh output (press Ctrl-C to stop).
`--help`	`-h`	Display 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.

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.

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.

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, tests failed, or the Editor exited with an error.
`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.

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` , or `ndjson` ). `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_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_NO_UPDATE_CHECK`	Disable the background check for CLI updates.
`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 adds many commands not in the Hub CLI, including

auth

open

projects

uninstall

upgrade

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
```
,
```
upgrade
```
.
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

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

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

Error output

Exit codes

Code

Meaning

Environment variables

Variable

Effect

Progress output

Log locations

Platform

Path

Migrate from the Hub CLI

Invocation