Unity CLI

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

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.5",
  "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.9 (beta.7 was withdrawn the same day it shipped). cliVersion in the config is only a bind-time snapshot; the installed binary moves ahead of it. Before using a command whose semantics changed recently, read <cliPath> --version and <cliPath> <command> --help — --help is always the final authority for the binary on disk. beta9+ <cliPath> skill show --list / --path <file> prints Unity's own agent skill read-only (offline, ~44k tokens in total — read one file at a time) — a second reference, never an authorization; this module's gates and DO NOT list still apply. If a command errors unexpectedly, run <cliPath> doctor --format json first (environment snapshot; --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 — read-only, no feature switch needed. open / test / run / build all resolve the editor from the project's ProjectVersion.txt. Before the first CLI launch of a session run these checks; none of them modifies the project:

<cliPath> editors -i --format json                       # all versions: is the bound editorVersion installed?
<cliPath> doctor --ci --format json                      # beta6+: exit 6 = definitive blocker, 7 = retryable
<cliPath> projects verify "<projectPath>" --format json  # beta6+: exit 6 = errors, 0 = clean or warnings only

• doctor --ci (from the project root) checks licence, the project's editor, disk space and Unity services; branch on errors[].code (LICENSE_NONE, EDITOR_NOT_INSTALLED, DISK_SPACE_LOW, NETWORK_UNREACHABLE): 6 → stop and report, 7 → retry a few times, then tell the user. Plain doctor always exits 0. beta6–8 on macOS may hang on a keychain prompt — wrap it in a shell timeout.
• projects verify needs no Editor, licence or network and only detects: META_MISSING / META_ORPHAN / GUID_DUPLICATE / CONFLICT_MARKERS / MANIFEST_INVALID exit 6 — report, never hand-repair; warnings (PATH_UNVERIFIABLE, EDITOR_VERSION_DRIFT via --expect-editor <version>) exit 0 unless --strict.

If the editor is not installed, stop and tell the user — never run install or 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

beta9+: open exits 6 (OPEN_EDITOR_EXITED) when the Editor dies inside the CLI's short watch window — report it at once instead of waiting on wait_for_health. Only that window is covered: an Editor that quits later is never observed, and older binaries exit 0 regardless, so a wait_for_health timeout remains the real failure signal.

Liveness triage — prefer this over blind retry. When REST is unreachable, determine whether an Editor is actually running before deciding to cold-start:

1. Read the project's own cli_config.json first. Only proceed if it exists and enabled: true.
2. Check the UnitySkills registry: 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.
3. Cross-check with the CLI process list: <cliPath> editors running --format json --non-interactive lists the Editor instances the CLI can see. This is useful confirmation, but it only sees instances the CLI's backend recognizes.
4. Check Library/UnityLockfile. A held lockfile means an Editor instance is open on this project even if the registry entry is missing.
5. <cliPath> status is supplementary, not authoritative: it only reflects Unity Pipeline connection state. 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.

If the PID, the CLI process list, or the lockfile indicates an Editor is already running, do not open, run, or build — Unity refuses a second instance on the same project. Only when none of the above show a live Editor for this project should you cold-start with open, then wait_for_health.

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_load 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). In CI, continue to use this file for test results.
• CI-only parameters — test --help may list report/coverage flags (beta4+: --report-format nunit,junit, --junit-output, --coverage*) and, beta6+, --shard N/M, --retries N (re-runs only the failed tests, --timeout per attempt, flaky tests named in test-results.retries.json, never-passing tests still exit 8) and --rerun-failed (reads the failing set from --output, writes test-results.rerun.xml). beta9+ --affected --since <ref> runs only the tests a change can reach (an approximation, writes test-results.affected.xml) — run --affected-compare first to measure its false-negative rate before trusting it. The selectors are mutually exclusive. Use a parameter only if the current binary's test --help lists it; never guess names.
• --timeout <seconds> (env UNITY_TEST_TIMEOUT) — kills the Unity process after N seconds; disabled by default, always set one for unattended runs.
• Extra editor arguments pass through after --, e.g. -- -nographics.
• Exit codes: 0 all passed (also when --retries rescued a flaky test — the flakiness is still reported). beta6+: 8 tests failed (errors[0].code TESTS_FAILED); 6 no verdict — compile error, licence or Editor crash (TEST_RUN_ERROR), --timeout expiry (TEST_TIMED_OUT). beta3–5: 6 covers both — read the XML to tell them apart. 7 Unity services unreachable after CLI retries; 130 SIGINT; 143 SIGTERM; any other non-zero = the command itself failed — check stderr, the JSON envelope and errors[].code, not just the XML. Retry 6/7 if at all; never retry 8.

Routing rule:

• Interactive iteration (editor already running, quick feedback on a few tests) → REST test_* skills.
• Full regression / CI-style run, or editor closed → unity test (headless, NUnit XML output). Do not run unity test against a project whose editor is open.

4. Batch runs (features.cliRun)

One-shot batch automation on the bound project only, while the editor is closed — the third lifecycle option between REST (editor open, interactive) and cold start (launch and keep serving):

<cliPath> run "<projectPath>" --timeout 1800 -- -executeMethod Your.Static.Method -quit

• Everything after -- is forwarded to the Unity Editor as standard command-line arguments; -executeMethod <static method> plus -quit is the typical shape (asset re-import, batch fixes, custom pipelines).
• Streams the editor log to stdout and returns the editor's exit code — non-zero means the batch run failed. beta5+ reports an Editor crash as stopped with signal SIG… (see §6) — an Editor crash, not a business-logic failure.
• --timeout <seconds> (env UNITY_RUN_TIMEOUT) — disabled by default; always set one, a hung batch editor otherwise blocks your shell forever.
• Routing: editor already running → use REST skills, never run (Unity refuses a second instance on the same project — same Library/UnityLockfile rule as cold start). Editor closed + persistent session needed → cold start. Editor closed + one-shot task → run.
• run --command <name> drives Unity Pipeline package commands — not part of this workflow (see DO NOT).

5. Headless builds (features.cliBuild)

cliBuild is off by default. When the user enables it, choose the build path based on the installed CLI version, Unity Editor version, target platform, and whether a Build Profile exists:

Path 1 — Unity 6 Build Profile (beta4+)

<cliPath> build "<projectPath>" --profile "Windows" --output-path ./Builds/win64

• --profile accepts a Build Profile asset path or the profile name shown in the Build Profile window.
• Requires Unity 6 (6000.x) and a configured Build Profile.

Path 2 — Built-in desktop build (beta4+)

<cliPath> build "<projectPath>" --target StandaloneWindows64 --output-path ./Builds/win64

• --target is still required.
• For desktop targets, --execute-method is optional starting with beta4; the CLI can drive the built-in desktop build when --output-path is provided.

Path 3 — Custom C# build method (all versions, required for mobile/WebGL)

<cliPath> build "<projectPath>" --target Android --execute-method Builder.PerformBuild --output-path ./Builds/android

• --execute-method remains compatible and takes priority when provided; use it for Android, iOS, WebGL, or projects that already have a custom build pipeline.
• --output-path is forwarded to Unity as -buildOutput; the execute-method itself is responsible for reading it.
• If the project does not already contain a static build method, tell the user instead of writing one into their project unasked.

Common build flags

• The build log tails to stdout by default (--no-tail to disable); the full log lands at <project>/Logs/build-<target>-<timestamp>.log unless --log-file overrides it. beta6+ also writes <output>.provenance.json beside the artifact — what was built, failed builds too (--no-provenance to skip).
• --timeout <seconds> (env UNITY_BUILD_TIMEOUT, beta6+) — aborts the build and exits 6; disabled by default, always set one for unattended builds. beta6+ json/ndjson also carry heartbeat frames (elapsed, and seconds since the log last grew — even with --quiet): a stalled Editor is a growing gap, not silence.
• Dirty-worktree guard: build refuses to run with uncommitted changes. That protection is deliberate — pass --allow-dirty-build only when the user explicitly says so.
• --versioning-strategy <semantic|tag|custom|none> (default none) stamps the build version from git tags/history; --build-version applies only with custom.
• Android: --android-export-type <apk|aab|android-studio-project> and keystore/signing flags exist, but secrets on the command line leak into shell history and CI logs — let the user handle signing; never ask them to paste keystore passwords into your shell commands.
• Same lifecycle rules as run: bound project only, editor must be closed, and once the editor is up again all normal operations go back through REST.
• Exit codes / signals: 0 success; 6 build failed, --timeout expired (beta6+), or the Editor exited abnormally; 7 Unity services unreachable after retries; 130 SIGINT; 143 SIGTERM. beta5+ reports an Editor crash as stopped with signal SIG… (see §6) — treat that separately from BUILD_FAILED.