Unity CLI (advisory)

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.