---
title: Migrate from the Hub CLI to the Unity CLI
product: Unity command-line interface (CLI)
canonical: https://docs.unity.com/en-us/unity-cli/reference/migrate-hub-cli
last_updated: 2026-11-02
generated_at: 2026-11-04T20:24:40.035Z
locale: en-us
---

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

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`                                | Diagnostic text on `stderr`. In `json` and `ndjson` modes, the failed result is still on `stdout`.                                    |
| Progress          | Plain 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](/unity-cli/reference/output-formats.md#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`](/unity-cli/reference/accounts-licenses-cloud-commands.md#sign-in-and-out), [`open`](/unity-cli/reference/editor-project-commands.md#open-a-project), [`projects`](/unity-cli/reference/editor-project-commands.md#manage-projects-in-the-hub-registry), [`uninstall`](/unity-cli/reference/editor-project-commands.md#uninstall-an-editor), [`self-update`](/unity-cli/reference/cli-config-diagnostics-commands.md#update-the-unity-cli), `build`, `test`, `license`, `shell`, and `mcp`. Refer to [commands](/unity-cli/reference.md) 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](/unity-cli/reference/output-formats.md#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.