unity-cli

Unity CLI

Drive a running Unity Editor (if one is open)

If a Unity Editor is open on this machine, this CLI can control it live — create and modify GameObjects, edit scenes and assets, inspect the hierarchy, and run arbitrary C# — through the project's Pipeline package (com.unity.pipeline). This runs entirely on your local machine, in your own user account, against your own open Editor: it is not remote access and grants no privilege you don't already have at your own terminal. When an Editor is available, drive it instead of hand-editing scene or asset files.

unity status                    # confirm a connected Editor (look for state "ready")
unity command                   # list the commands the Editor exposes
unity command editor_play       # run one — e.g. enter Play mode
# Run arbitrary C# — e.g. add a GameObject named "Joe" — when the Editor exposes eval:
unity command eval 'new UnityEngine.GameObject("Joe");'

Requires the project's com.unity.pipeline package (Unity 6.0+) — add it once with unity pipeline install. Full details — launching a headless Editor to drive, unity list tool discovery, and authoring custom [CliCommand] tools — are in integration-advanced.md.

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

First check if the CLI is available:

which unity && unity --version

If not found, install it:

macOS / Linux

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

Windows (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:

unity --version

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

Step 2: Verify it works

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.
--json	Global shorthand for --format json, accepted on every command (e.g. unity status --json, unity doctor --json). --format takes precedence when both are supplied.
--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 — used by open, and also honored by status and the cloud commands.
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_NO_CONSENT_PROMPT	—	Suppress the one-time first-run analytics consent prompt without recording a choice — for wrapper scripts on an interactive terminal that must never absorb the prompt. Analytics stay off until you run unity analytics opt-in. Unlike UNITY_NON_INTERACTIVE, it changes nothing else about command behavior.
UNITY_NO_CRASH_REPORT	—	Disable anonymous crash/error reporting (Sentry) entirely.
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 or --help to any command or subcommand:

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 3, and any other operational failure (network, server error) to 6 — 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 / running / 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 / size / close), 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	integration-advanced.md

Common workflows

Edit a scene, GameObject, or asset — unity status first

Before editing any scene, GameObject, prefab, or asset, run unity status to detect a connected Editor. If one is reachable, drive it with live commands instead of touching project files — the Editor applies changes to the actual active scene and keeps its in-memory state in sync.

unity status                       # is an Editor connected? (look for state "ready")
unity command                      # discover the scene/GameObject commands THIS Editor exposes
# then drive it with the commands it lists — for example, if your Editor exposes them:
unity command create_gameobject    # act on the live, active scene
unity command save_scene           # persist the active scene

Command names are defined by the Editor, so run unity command (or unity list) to see the exact set — don't assume a name.

Never hand-edit .unity, .prefab, or .asset YAML while a live Editor is reachable. Raw-file edits are:

• error-prone — fileIDs and GUIDs are assigned by hand and easy to get wrong;
• invisible to the running Editor until a reimport, so the change silently fails to take effect; and
• prone to hitting the wrong file — e.g. writing to SampleScene.unity while the Editor's active scene is actually Demo2.unity, producing valid-looking YAML that changes nothing the user sees.

Only fall back to editing files directly when unity status shows no reachable Editor — and say so explicitly ("no live Editor detected, editing the file directly").

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.

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

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

...