Unity CLI Install
Gets unity working against a live Unity Editor, and keeps re-running safe.
This skill installs. Unity's own unity-cli skill teaches the ~142 commands — step 6
installs it, and you should defer to it for day-to-day usage.
The chain (four layers, each can fail alone)
unity binary ──► Unity account ──► com.unity.pipeline ──► agent MCP entry
(winget/brew) (unity auth) (in the PROJECT) (unity mcp configure)
│
Editor must import it
before any command exists
The trap that wastes the most time: the CLI connects, reports ready, and lists
0 commands. That is layer 3 — com.unity.pipeline is in manifest.json but the
running Editor has not re-resolved packages yet. Focus or restart the Editor. Nothing
about the CLI is broken.
Workflow
Run everything through the scripts; they check state before touching anything.
node scripts/install.mjs --project "<unity-project>" --client claude-code
node scripts/verify.mjs --project "<unity-project>"
install.mjs prints one line per step: = already correct, + changed, - skipped,
! warning, x failed. A second run on a healthy machine must print 0 changed —
if it does not, that is a bug in the skill, not in the user's machine.
Useful flags: --dry-run (report only), --no-skill, --disable-competing,
--min-version <semver>, --client <name>.
- Install the binary — winget on Windows, Homebrew on macOS, the CDN script on
Linux. Skipped when the installed version already meets
--min-version.
unity doctor — windows-long-paths warns on most Windows boxes; harmless
until a package path exceeds 260 chars.unity auth login — the script never opens a browser on its own. If it reports
not signed in, tell the user to run it.unity pipeline install — writes com.unity.pipeline into the project's
Packages/manifest.json. Then have the user focus the Unity Editor so it
resolves; verify.mjs checks packages-lock.json for this specifically.unity mcp configure <client> — unity mcp configure --list shows ~16 clients.
Some write a JSON file; claude-code instead shells out to claude mcp add, so its
row always reads delegation/manual and re-running is how you check it.unity skill install <client> — Unity's own usage skill, embedded in the binary
and installed offline. Supported: claude-code, claude-desktop, grok, cursor,
windsurf, vscode, cline, codex. Re-render after a CLI upgrade with unity skill refresh.- One Unity server only — if a third-party Unity MCP server is also enabled, the
agent sees 150+ overlapping Unity tools and picks worse.
--disable-competing sets
"disabled": true (never deletes, always backs up) so the user can swap back.
- Verify —
verify.mjs fails loudly. The check that proves the whole chain is
command surface: a count above 0 means all four layers are live.
Rules
- Never delete a competing server — disable it. The user may have paid extensions on it.
- Never run
unity auth login unattended. It opens a browser.
- Close nothing. Ask the user to focus/restart their Editor; don't kill
Unity.exe.
- Re-run
install.mjs after any Unity CLI upgrade — an upgrade can leave the
installed agent skill stale.
Gotchas that bite in practice
| Symptom |
Cause |
ready but 0 commands |
Editor has not imported com.unity.pipeline — focus it |
No GameObject at hierarchy path 'C:/Program Files/Git/Player' |
Git Bash rewrote /Player. Set MSYS_NO_PATHCONV=1, or use PowerShell |
Could not resolve 'target' |
Args are --target /Player, never target=/Player |
eval throws TypeLoadException … CSharpCompilationOptions |
Two packages ship conflicting Roslyn builds. Every other command still works |
| Input code compiles but throws at Play |
Check activeInputHandler first — 1 means Input System only, so Input.GetAxis is dead |
Full detail, command reference, and the config paths: REFERENCE.md.
1---2name: unity-cli-install3description: Install, repair, and verify Unity's official Unity CLI (`unity`) end to end — the binary, the `com.unity.pipeline` Editor package that exposes its ~142 commands, the agent MCP registration, and Unity's own usage skill — then prove the whole chain works. Every step is idempotent, so running it again on a working machine changes nothing and running it on a broken one repairs only what drifted. Use when the user wants to install or set up the Unity CLI, says "ติดตั้ง Unity CLI", "unity command not found", "unity cmd ไม่ทำงาน", is moving off a third-party Unity MCP server, or is debugging a Unity CLI that connects but lists 0 tools.4---56# Unity CLI Install78Gets `unity` working against a live Unity Editor, and **keeps re-running safe**.910This skill installs. Unity's own `unity-cli` skill teaches the ~142 commands — step 611installs it, and you should defer to it for day-to-day usage.1213## The chain (four layers, each can fail alone)1415```16unity binary ──► Unity account ──► com.unity.pipeline ──► agent MCP entry17(winget/brew) (unity auth) (in the PROJECT) (unity mcp configure)18 │19 Editor must import it20 before any command exists21```2223**The trap that wastes the most time:** the CLI connects, reports `ready`, and lists24**0 commands**. That is layer 3 — `com.unity.pipeline` is in `manifest.json` but the25running Editor has not re-resolved packages yet. Focus or restart the Editor. Nothing26about the CLI is broken.2728## Workflow2930Run everything through the scripts; they check state before touching anything.3132```bash33node scripts/install.mjs --project "<unity-project>" --client claude-code34node scripts/verify.mjs --project "<unity-project>"35```3637`install.mjs` prints one line per step: `=` already correct, `+` changed, `-` skipped,38`!` warning, `x` failed. **A second run on a healthy machine must print `0 changed`** —39if it does not, that is a bug in the skill, not in the user's machine.4041Useful flags: `--dry-run` (report only), `--no-skill`, `--disable-competing`,42`--min-version <semver>`, `--client <name>`.43441. **Install the binary** — winget on Windows, Homebrew on macOS, the CDN script on45 Linux. Skipped when the installed version already meets `--min-version`.462. **`unity doctor`** — `windows-long-paths` warns on most Windows boxes; harmless47 until a package path exceeds 260 chars.483. **`unity auth login`** — the script never opens a browser on its own. If it reports49 not signed in, tell the user to run it.504. **`unity pipeline install`** — writes `com.unity.pipeline` into the project's51 `Packages/manifest.json`. Then **have the user focus the Unity Editor** so it52 resolves; `verify.mjs` checks `packages-lock.json` for this specifically.535. **`unity mcp configure <client>`** — `unity mcp configure --list` shows ~16 clients.54 Some write a JSON file; `claude-code` instead shells out to `claude mcp add`, so its55 row always reads *delegation/manual* and re-running is how you check it.566. **`unity skill install <client>`** — Unity's own usage skill, embedded in the binary57 and installed offline. Supported: claude-code, claude-desktop, grok, cursor,58 windsurf, vscode, cline, codex. Re-render after a CLI upgrade with `unity skill refresh`.597. **One Unity server only** — if a third-party Unity MCP server is also enabled, the60 agent sees 150+ overlapping Unity tools and picks worse. `--disable-competing` sets61 `"disabled": true` (never deletes, always backs up) so the user can swap back.628. **Verify** — `verify.mjs` fails loudly. The check that proves the whole chain is63 *command surface*: a count above 0 means all four layers are live.6465## Rules6667- **Never delete a competing server** — disable it. The user may have paid extensions on it.68- **Never run `unity auth login` unattended.** It opens a browser.69- **Close nothing.** Ask the user to focus/restart their Editor; don't kill `Unity.exe`.70- **Re-run `install.mjs` after any Unity CLI upgrade** — an upgrade can leave the71 installed agent skill stale.7273## Gotchas that bite in practice7475| Symptom | Cause |76| --- | --- |77| `ready` but 0 commands | Editor has not imported `com.unity.pipeline` — focus it |78| `No GameObject at hierarchy path 'C:/Program Files/Git/Player'` | Git Bash rewrote `/Player`. Set `MSYS_NO_PATHCONV=1`, or use PowerShell |79| `Could not resolve 'target'` | Args are `--target /Player`, never `target=/Player` |80| `eval` throws `TypeLoadException … CSharpCompilationOptions` | Two packages ship conflicting Roslyn builds. Every other command still works |81| Input code compiles but throws at Play | Check `activeInputHandler` first — `1` means Input System only, so `Input.GetAxis` is dead |8283Full detail, command reference, and the config paths: [REFERENCE.md](REFERENCE.md).
duckxy166