unity-development

UniCli — Unity Editor CLI

UniCli lets you interact with Unity Editor directly from the terminal. The CLI (unicli) communicates with the Unity Editor over named pipes, so the Editor must be open with the com.yucchiy.unicli-server package installed.

RULES — Always Follow These

1. After creating/modifying ANY file under Assets/ or Packages/: Run unicli exec AssetDatabase.Import --path "<path>" --json to generate .meta files. Never create .meta files manually — always let Unity generate them via this command. Unity requires .meta files for every asset — skipping this causes missing references, broken imports, and compilation errors. This applies to all file types: .cs, .asmdef, .asset, .prefab, directories, etc.
2. After modifying C# code in the Unity project: Run unicli exec Compile --json to verify compilation.
3. Always use --json when parsing output programmatically.
4. If connection to Unity Editor fails: Retry 2–3 times, then ask the user to confirm Unity Editor is running with the project open.
5. For platform-specific verification: Use unicli exec BuildPlayer.Compile --target <platform> --json to catch platform-specific errors (missing #if guards, unsupported APIs, etc.).
6. When running tests: Always use the default --resultFilter failures (or --resultFilter none for summary-only) to keep output minimal. Only use --resultFilter all when you specifically need to inspect individual passed test details. This prevents large test suites from flooding context. Stack traces are omitted by default (--stackTraceLines 0); use --stackTraceLines 3 when you need to diagnose a failure location.
7. When checking console logs: Use Console.GetLog with {"logType":"Warning,Error"} to filter out informational noise and focus on actionable issues. Stack traces are omitted by default; use {"logType":"Error","stackTraceLines":3} when debugging errors.
8. Discover commands dynamically: Use unicli commands --json to list all available commands and unicli exec <command> --help to see parameters for any command. --help includes nested type details when applicable, and commands --json provides nested schemas via each command's requestTypeDetails and responseTypeDetails. Match nested type details by typeId; type and typeName are display labels and may not be unique. Do not rely on memorized command lists — the project may have custom commands.
9. Before scene-affecting operations: Run unicli exec Editor.Status (without --json — the compact text summary is enough to check for dirty state and keeps output small) before TestRunner.RunPlayMode, BuildPlayer.Build, Scene.Open, Scene.New, Scene.Close, Menu.Execute, or entering Play Mode. TestRunner.RunPlayMode is the most common offender: the test runner creates a temporary test scene and swaps out the currently open scenes, so any unsaved scene changes at that moment can trigger a save prompt, abort the run, or leave the CLI waiting forever. If dirty scenes came from your own edits, save only the changes that should persist; revert or discard temporary probe changes when that is safer. If the dirty state may be from the user, do not save or discard it; ask the user how to proceed.
10. When commands hang or time out: Suspect a Unity Editor modal dialog such as a scene save prompt. Do not keep retrying blindly; ask the user to close or resolve the dialog, then retry.