unity-cli

name	unity-cli
description	Use when interacting with Unity CLI from the terminal — install, upgrade or uninstall editors, create, list or open projects, manage modules, manage licenses, check auth status, read logs, browse Unity releases, build/test projects, configure the Unity MCP server for AI agents, or run any other Unity CLI operation. For a guided idea-to-running-project flow for a brand-new game, use the new-unity-project skill instead.
allowed-tools	["Bash"]

Unity CLI

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

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

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)

---

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	diagnostics-maintenance.md
mcp (+ configure), connected editors (pipeline / command / status), 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.

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

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

# 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

# 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

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

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):

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

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

# 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: 0.1.0-beta.8). Once GA ships, the UNITY_CLI_CHANNEL=beta part of the install command 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.