/unity-cli

name: unity-cli
description: Guide for using the experimental Unity CLI with bound UnitySkills projects. 与已绑定的 UnitySkills 项目协同使用实验性 Unity CLI。

Unity CLI (advisory)

**Advisory module — no REST skills.** All commands here run in YOUR shell on the user's machine, not through the REST server. That is the point: they work while the Unity Editor is **closed**.

Gate — read this first

Before using anything below, check the binding config:

<projectRoot>/Library/UnitySkills/cli_config.json

• File missing, unreadable, or `enabled: false` → **Unity CLI is OFF for this project. Ignore this module entirely.** Do not suggest installing the CLI unprompted; the user opts in via `Window > UnitySkills → AI Config → Unity CLI Setup…`.
• `enabled: true` → use `cliPath` as the executable (it may not be on your PATH). Respect the per-feature switches in `features`:

{
  "schemaVersion": 1,
  "enabled": true,
  "cliPath": "/Users/me/.local/bin/unity",
  "cliVersion": "1.0.0-beta.3",
  "projectPath": "/path/to/Project",
  "editorVersion": "6000.0.32f1",
  "boundAt": "2026-07-26T09:00:00Z",
  "features": { "coldStart": true, "openArgs": true, "cliTest": true, "cliRun": false, "cliBuild": false }
}

Configs written by older plugin versions may lack the `cliRun` / `cliBuild` keys — for these two, **a missing key means OFF** (the first three keys keep their original semantics). Both also default to off on fresh binds; the user enables them per project in the panel.

The global registry (`~/.unity_skills/registry.json`) also carries `cliBound` / `cliPath` per running instance — use it for **liveness checks only, never as authorization**: the ONLY thing that authorizes CLI use for a project is that project's own `cli_config.json`. Do not cold-start any project whose own config you have not read, even if it appears in the registry. Also note `projectPath` inside the config is a bind-time snapshot — the directory you actually found the config under is authoritative (helper `get_cli_config()` already rewrites it); never `open` the stored path if it differs from the real project root.

> Unity CLI is **experimental (beta)** and its command surface changes between releases — this document was verified against `1.0.0-beta.3`; the official docs may lag behind the binary, so `<cliPath> --help` is always authoritative. If a command errors unexpectedly, run `<cliPath> doctor --format json` first (environment snapshot: CLI version, paths, auth state, installed editors, recent log lines; `--tail <n>` for more log) and re-check `--help` before retrying. Never modify the server or config to work around a CLI quirk.

1. Cold start / lifecycle (`features.coldStart`)

The one capability REST can never provide: starting the editor when it is not running.

<cliPath> status --format json          # any editor instances running?
<cliPath> open "<projectPath>" --args -unityskills-coldstart

**Always pass `--args -unityskills-coldstart`** when cold-starting: the UnitySkills plugin detects this marker at editor startup and force-starts the REST server for this session, even if the user's Auto-start preference is off. Without the marker you depend on the user's saved preference. The marker is consumed once per editor session — it never overrides a mid-session manual stop.

**Preflight — is the right editor even installed?** `open` / `test` / `run` / `build` all resolve the editor from the project's `ProjectVersion.txt`. Before the first CLI launch of a session, confirm the bound `editorVersion` is actually installed:

<cliPath> editors -i --format json

If it is not installed, **stop and tell the user** — installing an editor is a large, system-changing operation that only the user decides on. Never run `install`, and never pass `--allow-install` (see DO NOT).

After launching, poll the UnitySkills REST server until ready (first import/compile can take minutes):

from unity_skills import wait_for_health
health = wait_for_health(timeout=600)   # polls /health on ports 8090-8100

**Liveness triage — prefer this over blind retry.** When REST is unreachable:

1. **Check the UnitySkills registry first**: read `~/.unity_skills/registry.json`, find the entry whose `path` equals the project root, then test its `pid` (`ps -p <pid>` / Windows `tasklist`). Live pid → the editor is running but busy (Domain Reload / import) → keep the normal REST wait-and-retry; **do not** cold-start. 2. `<cliPath> status` is **supplementary, not authoritative**: it only lists editor instances visible to the CLI (requires the Unity Pipeline package in the project). An empty table / non-zero exit does **NOT** mean the editor is closed — verified in practice: a running editor without the Pipeline package shows nothing. 3. Only when the registry has no live-pid entry for this project → cold-start with `open`, then `wait_for_health`. 4. Never `open` a project whose editor is already running (live registry pid, or `Library/UnityLockfile` held) — Unity refuses a second instance on the same project.

2. Launch with arguments (`features.openArgs`)

<cliPath> open "<projectPath>" --args -openscene "Assets/Scenes/Main.unity"

Anything after `--args` is passed to the Unity Editor as standard command-line arguments. Useful to land in a known state (specific scene, custom `-executeMethod`). Only at launch time — for an already-running editor use REST `scene_open` instead.

3. Headless tests (`features.cliTest`)

<cliPath> test "<projectPath>" --mode EditMode --filter <pattern> --output test-results.xml --timeout 1800

• `--mode <EditMode|PlayMode>` — omit to run the editor's default test platform; cover both modes with two separate invocations.
• `--filter <pattern>` — only run tests whose names match.
• `--output <path>` — NUnit XML report (default `test-results.xml`).
• `--timeout <seconds>` (env `UNITY_TEST_TIMEOUT`) — kills the Unity process after N seconds; disabled by d