# Unity CLI Install

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

- Skill: `duckxy166/unity-cli-install` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add duckxy166/unity-cli-install`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duckxy166/unity-cli-install/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: duckxy166 (https://skillmd.com/u/duckxy166)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/duckxy166/unity-cli-install

---


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

```bash
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>`.

1. **Install the binary** — winget on Windows, Homebrew on macOS, the CDN script on
   Linux. Skipped when the installed version already meets `--min-version`.
2. **`unity doctor`** — `windows-long-paths` warns on most Windows boxes; harmless
   until a package path exceeds 260 chars.
3. **`unity auth login`** — the script never opens a browser on its own. If it reports
   not signed in, tell the user to run it.
4. **`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.
5. **`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.
6. **`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`.
7. **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.
8. **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](REFERENCE.md).