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

> **Note:**
>
> 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](./hub-cli). A side-by-side summary of the differences is in [Migrate from the Hub CLI](#migrate-from-the-hub-cli) at the bottom of this page.

## Install the CLI

The Unity CLI ships as a separate binary. Download and installation procedures depend on your platform and release channel; see the [Unity Hub download page](https://unity.com/download) and your platform's package documentation.

After installation, confirm the CLI is on your `PATH`:

```shell
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.

> **Note:**
>
> 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:

```shell
unity upgrade
```

## Quick start

You can get started quickly with the following key commands:

```shell
unity --help                               # Top-level help
unity install lts                          # Install the latest LTS Editor
unity install-modules -e 6000.3.7f1 -m ios # Add the iOS module
unity editors -i                           # List installed Editors
unity 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`). |

> **Tip:**
>
> `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`](#install-an-editor)                              | `i`    | Install a Unity Editor version, optionally with modules.                                       |
| [`install-modules`](#install-modules-for-an-existing-editor) | `im`   | Add modules to an already-installed Editor.                                                    |
| [`uninstall`](#uninstall-an-editor)                          | `u`    | Remove an installed Editor.                                                                    |
| [`editors`](#list-and-manage-editors)                        | `e`    | List available releases and installed Editors, add local installs, and set the default Editor. |
| [`install-path`](#set-or-get-the-editor-install-path)        | `ip`   | Show or change the path where Editors are installed.                                           |
| [`open`](#open-a-project)                                    |        | Open a Unity project, resolving the correct Editor version.                                    |
| [`projects`](#manage-projects-in-the-hub-registry)           | `p`    | Manage the list of Unity projects the Hub knows about.                                         |
| [`auth`](#sign-in-and-out)                                   | `a`    | Sign in, check login state, or sign out.                                                       |
| [`language`](#change-the-cli-display-language)               | `lang` | Show or change the CLI display language.                                                       |
| [`upgrade`](#update-the-cli)                                 |        | Self-update the `unity` CLI binary.                                                            |
| [`help`](#get-help)                                          |        | Display help for any command. Equivalent to `--help`.                                          |

> **Note:**
>
> 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.

```shell
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

```shell
unity install 6000.3.7f1
unity install lts
unity install 6000.3.7f1 -c 9b001d489a54
unity install 6000.3.7f1 -m android --cm
unity install lts -m ios android webgl
```

> **Note:**
>
> For the list of available module IDs, refer to [Add modules to a Unity Editor installation](./add-modules) and the [module ID table](./hub-cli#install-modules).

## Install modules for an existing Editor

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

```shell
unity install-modules [options]
```

> **Important:**
>
> 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>` | 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

```shell
unity install-modules -e 6000.3.7f1 -m ios android
unity install-modules -e 6000.3.7f1 -l
unity install-modules -e 6000.3.7f1 --all
unity install-modules -e 6000.3.7f1 -m android --no-cm
```

## Uninstall an Editor

Remove an installed Editor version.

```shell
unity uninstall <version>
```

### `uninstall` examples

```shell
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.

```shell
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/A   | Include 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.

```shell
unity editors add /Applications/Unity/Hub/Editor/6000.3.7f1/Unity.app
unity 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:

```shell
unity editors default               # show the default
unity editors default 6000.3.7f1    # set the default
```

### `editors` examples

```shell
unity editors -r       # list available releases
unity editors -i       # list installed Editors
unity editors -a       # combined list
```

## Set or get the Editor install path

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

```shell
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.

```shell
unity open <path>
```

### Path shorthand

You can omit the `open` keyword when the first argument is a path:

```shell
unity open ./MyProject
unity ./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.

```shell
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.

```shell
unity auth login
unity auth status
unity auth logout
```

### `auth` examples

```shell
unity auth login      # interactive OAuth flow
unity auth status     # print current user, if any
unity auth logout
```

## Change the CLI display language

Show the CLI's current display language, or change it to another supported language.

```shell
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:

```shell
unity editors -i --format json
unity editors -i --format tsv
```

> **Tip:**
>
> 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:

```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](./hub-cli).

### Invocation

|                | Hub CLI                                   | Unity CLI                                        |
| :------------- | :---------------------------------------- | :----------------------------------------------- |
| **How to run** | `"Unity Hub.exe" -- --headless <command>` | `unity <command>`                                |
| **Dependency** | Requires 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 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          | Plaintext 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`](#sign-in-and-out), [`open`](#open-a-project), [`projects`](#manage-projects-in-the-hub-registry), [`uninstall`](#uninstall-an-editor), and [`upgrade`](#update-the-cli). The path shorthand `unity ./MyProject` is equivalent to `unity open ./MyProject`.

### Impact summary

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