Unity CLI

Step 1: Install the CLI (if not already installed)

First check if the CLI is available:

bash

which unity && unity --version

If not found, install it:

macOS / Linux

bash

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

Windows (PowerShell)

powershell

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

After installing, open a new shell so

unity

is on PATH, then verify:

bash

unity --version

If the install script fails or the binary is still not found, tell the user and stop.

Step 2: Verify it works

bash

unity --version

If this fails with a permissions error or crash, the CLI installation may be broken. Suggest re-running the install script.

Global flags

These work on every command:

Flag	Description
`--format <fmt>`	Output format: `human` (default), `json` , `tsv` , `ndjson` . Also via `UNITY_FORMAT` env var.
`--no-banner`	Suppress the branded header — use in scripts
`--non-interactive`	Disable all interactive prompts — use in CI
`--quiet`	Suppress non-essential output
`--verbose`	Print full error details (stack trace + cause chain) on failure. Also via `UNITY_VERBOSE` .
`--proxy <url>`	HTTP/HTTPS/SOCKS/PAC proxy URL for this invocation. Also via `UNITY_PROXY` . Takes precedence over standard `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` env vars and the persisted `proxy.json` setting.
`--proxy-disable`	Disable proxy for this invocation, ignoring all sources (env vars, persisted config, system settings).
`--log-proxy`	Log one redacted entry per outbound request (host-only URL, resolved proxy, auth source, status, duration) to `proxy-request.json` — for reproducing proxy issues for support. Also via `UNITY_LOG_PROXY=1` or the persisted `proxyRequestLogging` setting.
`--no-log-proxy`	Opt a single invocation out of proxy request logging when it's enabled globally.

Always use
--format json
when you need to parse output programmatically.

A branded Unity header (logo, wordmark, CLI version) renders on the landing surfaces — bare

unity

unity --help

-h

unity help

, and above the first-run consent prompt. It's shown only on a TTY, prints at most once, and degrades to compact, uncolored text on narrow terminals, without Unicode, or under

NO_COLOR

. Piped output is unaffected. Use

--no-banner

to suppress it in scripts. Bare

unity

prints usage and exits 0.

Environment variables

All CLI env vars use the

UNITY_

prefix. A CLI flag always overrides the corresponding env var.

Variable	Mirrors flag	Description
`UNITY_FORMAT`	`--format`	Output format ( `human` , `json` , `tsv` , `ndjson` ). `HUB_FORMAT` is a deprecated alias.
`UNITY_EDITOR_VERSION`	`--editor-version`	Editor version (e.g. `2023.3.0f1` , `latest` , `lts` ).
`UNITY_ARCHITECTURE`	`--architecture`	Chip architecture ( `x86_64` , `arm64` ).
`UNITY_PROJECT_PATH`	path argument	Project path for the `open` command.
`UNITY_QUIET`	`--quiet`	Suppress non-essential output.
`UNITY_VERBOSE`	`--verbose`	Show full error details on failure.
`UNITY_NON_INTERACTIVE`	`--non-interactive`	Disable interactive prompts.
`UNITY_NO_BANNER`	`--no-banner`	Suppress the branded banner.
`UNITY_RUN_TIMEOUT`	`--timeout`	Timeout for `unity run` in seconds.
`UNITY_TEST_TIMEOUT`	`--timeout`	Timeout for `unity test` in seconds.
`UNITY_CLOUD_ORG`	`--cloud-org`	Active Unity Cloud organization id or name for a single call.
`UNITY_SERVICE_ACCOUNT_ID`	—	Service account client ID for non-interactive (CI) auth.
`UNITY_SERVICE_ACCOUNT_SECRET`	—	Service account client secret for non-interactive (CI) auth.
`UNITY_PROXY`	`--proxy`	HTTP/HTTPS/SOCKS/PAC proxy URL. Takes precedence over `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` and the persisted `proxy.json` setting.
`UNITY_NO_UPDATE_CHECK`	—	Disable the background "update available" check (see `unity config update-check` ).
`UNITY_LOG_PROXY`	`--log-proxy`	Log one redacted entry per outbound request to `proxy-request.json` . Truthy values: `1` , `true` .
`UNITY_NO_ELEVATE`	`--no-elevate`	Windows: skip the elevated (UAC) install helper for `install` / `install-modules` — for user-writable locations and CI shells that can't answer a UAC prompt.
`UNITY_INSTALL_RETRIES`	`--retries`	Number of times `install-modules` retries a module whose download/validation fails. `0` disables retries.

CI service account auth: Set both

UNITY_SERVICE_ACCOUNT_ID

and

UNITY_SERVICE_ACCOUNT_SECRET

to skip the browser OAuth flow — this keeps the secret out of the process argument list and shell history. These map to the

--client-id

--secret-from-stdin

inputs of

unity auth login

, but reading the credentials from the environment isn't a full login: it doesn't run the interactive flow or persist credentials to the keyring.

Getting help

If a command fails or you're unsure of the available options, append

-h

--help

to any command or subcommand:

bash

unity --help
unity install --help
unity projects --help
unity projects create --help

This works at every level of the command hierarchy.

Exit codes

Code	Meaning
0	Success
1	General error
2	Bad arguments
3	Authentication failure
4	Precondition not met (e.g. no license active, floating server not configured)
6	Command-specific failure
130	Interrupted — Ctrl+C / SIGINT (128 + 2)
143	Terminated by SIGTERM (128 + 15) — e.g. `kill` or a CI/runner timeout. Emitted by long-running commands that install a signal handler to clean up first (currently `unity build` , which scrubs the temporary Android keystore).

The

cloud

and

auth

commands map an authentication failure (expired/missing session, rejected sign-in) to

, and any other operational failure (network, server error) to

— so scripts can reliably tell "sign in again" apart from a genuine command failure.

Commands

The full per-command reference — syntax, flags, and examples — lives in grouped files under

references/

. Read the file for the command group you need; all the global flags, environment variables, and exit codes above apply throughout. Every command also supports

-h

--help

(see Getting help).

Commands	Reference file
`auth` (login / logout / status), `license` (activate / return / server), `cloud` (org / project)	auth-license-cloud.md
`editors` (list / add / default / path / install-path / info / upgrade / module), `install` , `uninstall` , `modules` , `install-modules`	editors-install.md
`projects` (list / create / new / clone / open / link / require / upgrade / export / import / pin), `releases` , `templates`	projects-templates.md
`config` (proxy / update-check), `hub install`	config-hub.md
`run` , `test` , `build`	build-run-test.md
`logs` , `doctor` , `env` , `cache` , `analytics` , `changelog` , `language` , `completion` , `bug` , `upgrade` , `self-uninstall` , `diagnose proxy`	diagnostics-maintenance.md
`mcp` (+ `configure` ), connected editors ( `pipeline` / `command` / `status` / `list` ), `shell` , development-only ( `eval` / `cloud-pipeline` / `collab` )	integration-advanced.md

Common workflows

Bootstrap a new project from scratch

For a guided end-to-end experience — concept questions, installing the Editor in the background while you plan, package selection, and monetization handoff — use the new-unity-project
skill. This section is the raw CLI recipe that skill builds on; use it directly when you just want the commands.

Take an idea to a running, version-controlled project using only the CLI. Decide the target platforms first — they determine which Editor modules you install in step 2. You can add modules later (

unity install-modules

), but a project can't build for a platform until that platform's module is installed, so it's simplest to decide up front.

bash

# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md).
unity --version
unity auth status --format json      # if signed out:      unity auth login
unity license status --format json   # if none active:      unity license activate

# 2. Pick and install an Editor with the modules your target platforms need.
#    Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream
#    release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as
#    evaluation-only, never for a project you intend to ship. A deadline argues for LTS.
#    (lts / latest aliases work wherever a version is accepted.)
unity releases --stream lts --limit 5 --format json
unity install lts --module android --module ios --yes --accept-eula   # add --module webgl, etc.
unity editors --installed --format json                               # confirm it landed

# 3. List the real template ids this Editor offers — don't guess them.
unity templates list --editor lts --format json
#    Common ids: com.unity.template.3d, com.unity.template.2d, and a URP template (id varies by version).

# 4. Create the project. The first positional arg is the NAME; --path sets the parent directory.
#    All options supplied, so it won't prompt; add --non-interactive in CI.
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.3d

Source control — let the user choose. The CLI publishes the new project to a fresh remote in one step for any provider. Always pass tokens on stdin (

--git-token-stdin

) so secrets never land in shell history or the process list. Pick based on the project — don't default to one:

Git — GitHub / GitLab (
```
--vcs github
```
/
```
--vcs gitlab
```
). Ubiquitous. For asset-heavy games add Git LFS (
```
--git-lfs
```
) so large binaries don't bloat history.
Unity Version Control — UVCS (
```
--vcs uvcs
```
). Unity's own VCS, built for large binary game assets: it handles them natively (no LFS needed) and supports file locking — often the better fit for art-heavy projects or larger teams. Auth uses your Unity sign-in;
```
--vcs-region
```
selects the region.

bash

# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you
# want to add packages/assets BEFORE the first commit (see the new-unity-project flow).
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.3d \
  --vcs github --git-namespace my-org --git-repo my-game \
  --git-visibility private --git-default-branch main --git-token-stdin --git-lfs

# Unity Version Control (UVCS) — handles binaries natively, so no LFS:
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.3d \
  --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>

Feed the token to

--git-token-stdin

from a secret store, never a literal — e.g.

… --git-token-stdin <<<"$GIT_TOKEN"

where

$GIT_TOKEN

comes from your CI/secret manager (UVCS uses your Unity sign-in, so no token is needed). See references/projects-templates.md for the full source-control flag set. For a purely local Git repository instead, initialize git with a Unity-appropriate ignore so the multi-GB

Library/

and other generated folders are never committed:

bash

cd ~/UnityProjects/MyGame
git init -b main
# Download (do not pipe to a shell) a maintained Unity .gitignore:
curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore

# Asset-heavy game? Keep large binaries out of git history with Git LFS:
git lfs install
git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png"   # adjust to your asset types
git add .gitattributes

git add -A
git status                             # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged
git commit -m "Initial Unity project: MyGame"
git ls-files | grep -c '^Library/'     # must print 0

What the CLI does and doesn't cover. The CLI handles editor, project, and source control. It does not manage UPM (Unity Package Manager) packages — to add packages beyond the template headlessly, use the unity-package-management
skill (C# PackageManager Client API). For monetization/backend, hand off to the dedicated skills:

implement-in-app-purchases

(IAP),

levelplay-unity-integration

(ads), or

build-live-game

(accounts, cloud save, economy, remote config, leaderboards). Open the project to start working:

unity open ~/UnityProjects/MyGame

Find and install a missing editor

bash

# 1. Check what's installed
unity editors --installed --format json

# 2. Browse available LTS versions
unity releases --lts --limit 5 --format json

# 3. Install
unity install 6000.0.47f1 --yes --accept-eula

Open a project with the correct editor

bash

# 1. Check the project's required editor version
unity projects info /path/to/MyProject --format json
# Look at "editorVersion" in the result

# 2. Confirm that editor is installed
unity editors --installed --format json

# 3. Open (warns if the editor version is missing)
unity open /path/to/MyProject

CI: activate a license, then build

bash

# 1. Sign in non-interactively with a service account
unity auth login --client-id "$UNITY_SERVICE_ACCOUNT_ID" --secret-from-stdin <<<"$UNITY_SERVICE_ACCOUNT_SECRET"

# 2. Activate the entitlement license (or use --serial / --floating)
unity license activate

# 3. Build
unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

# 4. Return the seat when done (floating/assigned)
unity license return --yes

CI: headless build

Prefer the dedicated

unity build

command (handles batch mode, logging, and CI flags):

bash

unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

Or use

unity run

(batch mode is automatic — never pass

-batchmode

-quit

bash

unity run /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --allow-install \
  -- -executeMethod Builder.PerformBuild -logFile build.log
echo "Exit code: $?"

CI: run tests and publish results

bash

unity test /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --mode EditMode \
  --output ./test-results.xml \
  --allow-install \
  --timeout 600
echo "Exit code: $?"   # 0 = pass, 6 = test failures

Debug the CLI

bash

# Check auth + installed editors + recent errors in one command
unity doctor --format json

# Follow live logs during an install
unity logs --follow --level info

Notes

```
--non-interactive
```
and
```
--yes
```
together suppress all prompts — use both in CI.
```
--format json
```
always produces machine-readable output; prefer it over parsing human text. Error envelopes are pretty-printed with the same 2-space indent as success envelopes.

unity <version> [path]

is a shorthand for

unity open [path] --editor-version <version>

. Works with

lts

latest

, or a full version string like

6000.0.47f1

The CLI supports kubectl-style plugins: any
```
unity-<name>
```
binary on PATH is callable as
```
unity <name>
```
.
Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, while SGR color/style codes are preserved.
The CLI is currently in beta (latest:
```
1.0.0-beta.2
```
). It moved to 1.0 versioning at
```
1.0.0-beta.1
```
; it's still a beta, so keep
```
UNITY_CLI_CHANNEL=beta
```
in the install command until GA ships, after which that part can be dropped.
As of beta.8 the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with
```
unity config update-check off
```
or the
```
UNITY_NO_UPDATE_CHECK
```
env var.
Outbound HTTP from every CLI command honors the resolved proxy (see
```
unity config proxy
```
). Inspect what the CLI actually resolved with
```
unity env --format json
```
or
```
unity doctor --format json
```
— both surface the active proxy URL, its source, and auth source.

unity-cli

NPX Install

Tags

SKILL.md Content

Unity CLI

Step 1: Install the CLI (if not already installed)

Step 2: Verify it works

Global flags

Environment variables

Getting help

Exit codes

Commands

Common workflows

Bootstrap a new project from scratch

Find and install a missing editor

Open a project with the correct editor

CI: activate a license, then build

CI: headless build

CI: run tests and publish results

Debug the CLI

Notes