文档

Unity CLI reference

The Unity CLI is a standalone binary that lets you install Editors, manage modules, and automate Hub workflows from the terminal, independently of the Unity Hub desktop application.
阅读时间9 分钟最后更新于 2 天前
注意
The Unity CLI is experimental. Full feature parity with the Unity Hub UI is not guaranteed.
The Unity CLI (invoked as 
unity
) is a standalone command-line tool for installing and managing Unity Editors and modules from a terminal. It is distributed as its own binary and can be installed, updated, and used independently of the Unity Hub desktop application. The Unity CLI is well suited for:
  • Continuous integration (CI) and build agents where installing the full Hub is undesirable.
  • Scripting and automation that needs structured output (JSON/TSV) and predictable exit codes.
  • Power users who prefer a terminal-first workflow for everyday Hub tasks.
This page is the primary reference for the Unity CLI. If you use the Hub CLI that runs inside the Unity Hub desktop app (invoked with 
-- --headless
), refer to Hub CLI reference. A side-by-side summary of the differences is in Migrate from the Hub CLI at the bottom of this page.

Install the CLI

The Unity CLI ships as a separate binary. Run the install script for your platform to download and install the latest experimental build from the 
beta
release channel: macOS or Linux: 
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
Windows: 
$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
After installation, confirm the CLI is on your 
PATH
: 
unity --version
If 
unity --version
prints a version string, the CLI is ready to use. If the command is not found, add the install directory to your shell's 
PATH
or reopen your terminal.
注意
Because the CLI is self-contained, you can keep it installed on machines that do not run the Unity Hub desktop app, such as headless CI workers.

Update the CLI

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

Quick start

You can get started quickly with the following key commands: 
unity --help                               # Top-level helpunity install lts                          # Install the latest LTS Editorunity install-modules -e 6000.3.7f1 -m ios # Add the iOS moduleunity editors -i                           # List installed Editorsunity open ./MyProject                     # Open a project in Unity

Get help

The CLI uses a standard 
--help
flag on every command and subcommand:

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 may add flags or subcommands that appear only in 
--help
.

Command overview

Command

Alias

Description

install
i
Install a Unity Editor version, optionally with modules.
install-modules
im
Add modules to an already-installed Editor.
uninstall
u
Remove an installed Editor.
editors
e
List available releases and installed Editors, add local installs, and set the default Editor.
install-path
ip
Show or change the path where Editors are installed.
open
Open a Unity project, resolving the correct Editor version.
projects
p
Manage the list of Unity projects the Hub knows about.
auth
a
Sign in, check login state, or sign out.
language
lang
Show or change the CLI display language.
upgrade
Self-update the 
unity
CLI binary.
help
Display help for any command. Equivalent to 
--help
.
注意
Run 
unity --help
to see the authoritative command list for your installed CLI version, including any commands added after this page was written.

Install an Editor

Install a Unity Editor version, optionally with modules. 
unity install [version] [options]
The 
version
argument is a positional value and is 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

In addition to explicit versions like 
6000.3.7f1
, the CLI accepts 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
, ...		The newest release within that major/minor stream.

Common 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 is not 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 the list of 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 Hub or with the CLI: 
unity install-modules [options]
重要
You can only add modules to an Editor that was installed through the Hub or the CLI. Editors installed manually must be reinstalled through the Hub or the CLI to receive modules.

install-modules
options

Option

Required?

Description

-e, --editor-version <version>
NoEditor version to add the module to. If omitted on an interactive terminal, you receive a prompt.
-m, --module <id>
NoModule ID(s) to install. Accepts multiple values.
-l, --list
NoList installable modules for the target Editor instead of installing anything.
--all
NoInstall every available module for the target Editor.
--cm
, 
--childModules
NoAlso 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]

editors
options

Option

Alias

Description

--all
-a
Show both available releases and installed Editors.
--releases
-r
Show available releases.
--installed
-i
Show Editors installed on this machine.
--verbose
N/AInclude additional detail in the output.

editors add

Register an Editor that was installed outside of the Hub so that the Hub and CLI can manage it. Accepts one or more paths. 
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"

editors default

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

editors
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>

Path shorthand

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 that both the Hub UI and the CLI can find and open them. 
unity projects [subcommand] [options]
Alias: 
p
. Run 
unity projects --help
to see the available subcommands and options in your installed CLI version.

Sign in and out

The 
auth
command manages your Unity account session. 
unity auth loginunity auth statusunity auth logout

auth
examples

unity auth login      # interactive OAuth flowunity auth status     # print current user, if anyunity auth logout

Change the CLI display language

Show the CLI's current display language, or change it to another 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 is designed for both humans and scripts. It 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 is piped or redirected.Tab-separated, one record per line. Machine-parseable.
json
--format json
(or 
--json
) is set.		Structured output suitable for 
jq
and other tools.
Select a format explicitly with the global flag: 
unity editors -i --format jsonunity editors -i --format tsv
提示
When you pipe CLI output, the default format changes to TSV. If a script expects human-readable text, set 
--format human
explicitly, or parse TSV/JSON instead.

Errors on stderr

Errors and diagnostic messages are written to 
stderr
, leaving 
stdout
free for data output. In JSON mode, errors are emitted as 
{"error": "..."}
on 
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.
130
User cancelled the command (for example with Ctrl+C / SIGINT).

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 intended for human readers; do not parse it in scripts. For machine-readable progress or results, use 
--format json
.

Log locations

Logs are located at the following paths:
  • 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 previously wrote scripts targeting the CLI embedded in the Unity Hub desktop app (invoked with 
-- --headless
), the tables below 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>
DependencyRequires the full Unity Hub desktop app.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...>
(subcommand; accepts multiple paths)
-v
on 
install
Editor versionReserved. 
-V
prints the CLI version.
help
command		Platform-specific help text filesReplaced by 
--help
on every command.

Output and errors

Area

Hub CLI

Unity CLI

Default outputPlain text, always
human
on an interactive terminal; 
tsv
when piped
Structured output
--json
per command (where supported)		Global 
--format json
(
--json
kept for compatibility)
ErrorsWritten to 
stdout
Written to 
stderr
(JSON errors: 
{"error": "..."}
on stderr)
ProgressPlaintext lines, for example 
downloading 23.50%
Animated progress bar; static summary on completion
Exit codes
0
success, 
1
error
0
success, 
1
error, 
130
user cancellation

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 commands that are not in the Hub CLI: 
auth
, 
open
, 
projects
, 
uninstall
, and 
upgrade
. The path shorthand 
unity ./MyProject
is equivalent to 
unity open ./MyProject
.

Impact summary

重要
Review existing scripts and CI pipelines before switching. The items below describe the areas most likely to require changes.

High — scripts will 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 silently

  • Piped 
    stdout
    defaults to TSV, not plain text.
  • Errors go to 
    stderr
    , not 
    stdout
    .
  • Progress output format changed; do not parse it.

Low — additive, should not 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.