ドキュメント

Unity command-line interface (CLI)

Unity Pipeline

Unity Hub

Download Unity Hub

Unity command-line interface (CLI)

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.
読み終わるまでの所要時間 21 分最終更新 4日前

重要
The Unity command-line interface (CLI) is experimental. The features and documentation might change in an upcoming release.
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, adds local installs, sets the default Editor, upgrades Editors, lists running instances, and prunes unused or missing Editors.
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.
assets
Inspects, exports, and imports Unity asset packages.
assets inspect <file>
lists the contents of a
.unitypackage
without importing it,
assets export
writes project assets to a
.unitypackage
, and
assets import <file>
imports one into a project.
build
Builds a project in batch mode with CI-friendly flags, including Android signing and export options. Use
--list-targets
,
--list-profiles
, and
--create-profile <target>
to discover targets and create Unity 6 build profiles, and
build run
to launch the project's most recent recorded build.
run
Runs a project in batch mode or runs a registered Editor command in headless mode with
--command
. Use
--log-file <path>
to write the Editor log to a file.
recompile
Recompiles a running Editor's scripts and reports compile errors, without a full build.
--strict
also fails on warnings.
test
Runs a project's Edit Mode and Play Mode tests through the Editor test runner and write an NUnit report.
watch
Watches a project and re-runs a command each time its files change.
watch test
re-runs
unity test --affected
.

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, and creates organizations (
cloud org create
).

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 blame
Shows who last changed each GameObject and component in a scene or prefab.
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.
commands
Lists every command and subcommand as a machine-readable manifest (
--format json
) for agents and tooling.
list
Lists every tool a connected Editor registers, with its parameter schema.
pipeline
pipe
Installs, upgrades, and inspects the Unity pipeline package that connects the CLI to the Editor.
pipeline cloud-build
and
pipeline automation
read Unity Build Automation and Unity Pipeline Automation.
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 configures agent clients to use it.
mcp configure --server issue-tracker
configures the Unity Issue Tracker MCP server.
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 or the resolved Unity Accelerator endpoint (
diagnose accelerator
).
logs
Reads and tail the CLI's log file.
env
Prints environment paths and versions used by the CLI and the Hub.
context
Saves and switches between named sets of account, organization, project, Editor, and install path (
context save
,
use
,
list
,
current
,
delete
).
config
Views or changes CLI settings by key (
get
,
set
,
list
,
unset
,
resolve
) or through dedicated subcommands, such as, the proxy server and update checks.
config accelerator
stores the Unity Accelerator endpoint that
run
,
test
, and
build
pass to the Editor.
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.
docs
Opens the Unity documentation page for a class or topic, that matches your project's Unity version.
--url
prints the address instead.
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.
If a download is interrupted, the next
unity self-update
resumes the download instead of starting over.
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>
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
NoLists installable modules for the target Editor instead of installing anything.
--all
NoInstalls every available module for the target Editor.
--cm
,
--child-modules
NoAlso 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/AOutputs 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

Register an Editor you installed outside the Hub so 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"

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
On macOS and Linux, add
--wait
to keep the command running until the Editor exits. The command then exits with code 0 when the Editor exits cleanly, or 6 when it fails or crashes.
--wait
isn't supported on Windows yet and exits with code 2.

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:
p
. Run
unity projects --help
to check the available commands 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

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
available for data output. In
json
and
ndjson
modes, a failed command still writes a complete result to
stdout
. In
json
mode, the result is an envelope with
success: false
and an
errors
array. In
ndjson
mode, the result contains the terminal
result
frame with
success: false
. Branch on the stable error code, such as
errors[0].code
in
json
mode, instead of parsing
stderr
. Usage errors, such as a mistyped option, report
INVALID_COMMAND_ARGS
.
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, even after the CLI retried, or
unity recompile
couldn't reach a running Editor. Either 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
6
or
7
. A
6
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
8
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_CLOUD_PROJECT
Default Unity Cloud project id for
unity collaboration
commands that accept
--project-id
. An explicit
--project-id
wins.
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_SKIP_HOOKS
Turn the Git hooks installed by
unity vcs hooks install
into no-ops when Git provides no way to skip them.
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_ACCELERATOR
Unity Accelerator endpoint (
host:port
) for
unity run
,
unity test
, and
unity build
, like
--accelerator
. A bare host defaults to port 10080. A flag wins over this variable, which wins over the value saved with
unity config accelerator
.
UNITY_NO_EDITOR_IDENTITY_SERVER
Disables the background identity-server process that answers an Editor's sign-in requests when no Hub is running.
UNITY_NO_AUTH_BROKER
Disables the resident auth broker that serves your sign-in to CLI commands and read credentials directly from the keyring instead. The broker starts on demand and exits after two minutes of inactivity.
UNITY_CLI_HOME
Installation directory for the install script. When set, the script installs the CLI to
<UNITY_CLI_HOME>/bin
(
<UNITY_CLI_HOME>\bin
on Windows) instead of the default location.
UNITY_PEER_AUTH_MODE
Specifies how the CLI's background sign-in helpers verify the code signature of a connecting Editor or client. On macOS and Windows the default is
enforce
. Set
identify-only
to log without refusing, for example for an Editor you built from source. On Linux the default is logging only. Set
enforce
together with
UNITY_PEER_AUTH_LINUX_ALLOWED_HASHES
, a comma-separated list of trusted executable SHA-256 hashes to opt in.
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>
DependencyRequires 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 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
Diagnostic text on
stderr
. In
json
and
ndjson
modes, the failed result is still on
stdout
.
ProgressPlain 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.
  • Diagnostic error text goes to
    stderr
    , not
    stdout
    . In
    json
    and
    ndjson
    modes, a failed result stays on
    stdout
    , so branch on its error code rather than on the stream where the text arrived. Refer to Error output.
  • 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.