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

> **Note:**
>
> 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](./use-unity-cli.md).

Run `unity --help` to check the authoritative command list for your installed version, including any commands not yet covered on this page.

## Commands

| 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 the CLI installs Editors.                                        |
| [`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`](#help-commands)                                     |        | 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`). |

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

```shell
unity upgrade
```

## Install an Editor

Install a Unity Editor version, optionally with modules.

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

```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 available module IDs, refer to [Add modules to a Unity Editor installation](/hub/add-modules.md) and the [module ID table](/hub/hub-cli-reference.md#available-modules).

## Install modules for an existing Editor

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

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

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

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

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

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

### Identify the default Editor

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

### Editor command 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>
```

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 both the Hub UI and the CLI can find and open them.

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

```shell
unity auth login
unity auth status
unity 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.

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

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 tab-separated values (TSV). If a script expects human-readable text, set `--format human` explicitly, or parse TSV or JSON instead.

### 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": "..."}` 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 or 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 for human readers. Don't parse it in scripts. For machine-readable results, use `--format json`.

## Log locations

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

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