Documentation

Unity command-line interface (CLI)

Unity Pipeline

Unity Hub

Download Unity Hub

Unity command-line interface (CLI)

Migrate from the Hub CLI to the Unity CLI

Migrate scripts and CI pipelines from the Unity Hub CLI to the Unity CLI by comparing syntax, flags, output formats, exit codes, and identify breaking changes.
Read time 3 minutesLast updated 2 days ago
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 commands for the full list. The path shorthand 
unity ./MyProject
is equivalent to 
unity open ./MyProject
.

Impact summary

Important
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.