Skip to content
Back to search

unicli

MarketplaceWorks with Claude CodeGitHub

A CLI tool to control Unity Editor - enabling both humans and AI agents to run compilations, tests, and editor commands from the terminal.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yucchiy--unicli/badge.svg)](/listings/yucchiy--unicli)

HTML

<a href="/listings/yucchiy--unicli"><img src="/api/listings/yucchiy--unicli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

UniCli requires two components: the **CLI** (`unicli`) installed on your machine, and the **Unity Package** (`com.yucchiy.unicli-server`) installed in your Unity project. Both must be set up for UniCli to work.

Requirements

- Unity 2022.3 or later - macOS (arm64 / x64), Linux (x64), or Windows (x64)

CLI

**Homebrew (macOS):**

brew tap yucchiy/tap
brew install unicli

**Scoop (Windows):**

scoop bucket add unicli https://github.com/yucchiy/scoop-bucket
scoop install unicli

**Linux / Manual:** Download the latest binary from the [Releases](https://github.com/yucchiy/UniCli/releases) page and place it in your PATH.

Unity Package

The UniCli package must be installed in your Unity project. You can install it using the CLI:

unicli install

Or add it manually via Unity Package Manager using the git URL:

https://github.com/yucchiy/UniCli.git?path=src/UniCli.Unity/Packages/com.yucchiy.unicli-server

Quick Usage

Open your Unity project in the Editor, then run `unicli` from the Unity project directory (or any subdirectory). UniCli automatically detects the project by looking for an `Assets` folder in the current directory and its ancestors.

# Verify connection
unicli check

# List all available commands
unicli commands

# Compile scripts
unicli exec Compile

# Run EditMode tests
unicli exec TestRunner.RunEditMode

# Execute arbitrary C# code (--json for JSON output)
unicli eval 'return Application.unityVersion;' --json

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "unicli",
  3. "owner": {
  4. "name": "Yuichiro Mukai"
  5. },
  6. "metadata": {
  7. "description": "Claude Code plugin for controlling Unity Editor via UniCli CLI"
  8. },
  9. "plugins": [
  10. {
  11. "name": "unicli",
  12. "source": "./.claude-plugin/unicli",
  13. "description": "Control Unity Editor from Claude Code using UniCli CLI",
  14. "version": "1.7.0",
  15. "author": {
  16. "name": "Yuichiro Mukai"
  17. },
  18. "homepage": "https://github.com/yucchiy/UniCli",
  19. "repository": "https://github.com/yucchiy/UniCli",
  20. "license": "MIT",
  21. "strict": false
  22. }
  23. ]
  24. }
README.md · README · 972 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # UniCli
  2. [![GitHub Release](https://img.shields.io/github/v/release/yucchiy/UniCli)](https://github.com/yucchiy/UniCli/releases)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. A command-line interface for controlling Unity Editor from the terminal.
  5. UniCli lets you compile scripts, run tests, manage packages, inspect GameObjects, and more — all without leaving your terminal.
  6. Designed to work with AI coding agents such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code), UniCli gives AI the ability to interact with Unity Editor directly through structured CLI commands with JSON output.
  7. - **80+ built-in commands**: compile, test, build, inspect GameObjects, manage scenes/prefabs/packages, and more
  8. - **Dynamic C# execution**: run arbitrary C# code in Unity via `unicli eval`
  9. - **Extensible**: add custom commands with a single C# class
  10. - **AI-agent ready**: structured JSON output, Claude Code plugin, and Agent Skills support
  11. - **Cross-platform**: NativeAOT binaries for macOS (arm64/x64), Linux (x64), and Windows (x64)
  12. ## Table of Contents
  13. - [Getting Started](#getting-started)
  14. - [Requirements](#requirements)
  15. - [CLI](#cli)
  16. - [Unity Package](#unity-package)
  17. - [Quick Usage](#quick-usage)
  18. - [CLI Usage](#cli-usage)
  19. - [Project Discovery](#project-discovery)
  20. - [Executing Commands](#executing-commands)
  21. - [Parameter syntax](#parameter-syntax)
  22. - [Common options](#common-options)
  23. - [Examples](#examples)
  24. - [Dynamic Code Execution (Eval)](#dynamic-code-execution-eval)
  25. - [Custom Commands](#custom-commands)
  26. - [Text formatting](#text-formatting)
  27. - [Async handlers and cancellation](#async-handlers-and-cancellation)
  28. - [Error handling](#error-handling)
  29. - [Built-in Commands](#built-in-commands)
  30. - [Module Management](#module-management)
  31. - [Architecture](#architecture)
  32. - [Remote Commands](#remote-commands)
  33. - [Prerequisites](#prerequisites)
  34. - [Editor-side commands](#editor-side-commands)
  35. - [Built-in debug commands](#built-in-debug-commands)
  36. - [Creating custom debug commands](#creating-custom-debug-commands)
  37. - [AI Agent Integration](#ai-agent-integration)
  38. - [Claude Code Plugin](#claude-code-plugin)
  39. - [Agent Skills / Codex](#agent-skills--codex)
  40. - [License](#license)
  41. ## Getting Started
  42. UniCli requires two components: the **CLI** (`unicli`) installed on your machine, and the **Unity Package** (`com.yucchiy.unicli-server`) installed in your Unity project. Both must be set up for UniCli to work.
  43. ### Requirements
  44. - Unity 2022.3 or later
  45. - macOS (arm64 / x64), Linux (x64), or Windows (x64)
  46. ### CLI
  47. **Homebrew (macOS):**
  48. ```bash
  49. brew tap yucchiy/tap
  50. brew install unicli
  51. ```
  52. **Scoop (Windows):**
  53. ```powershell
  54. scoop bucket add unicli https://github.com/yucchiy/scoop-bucket
  55. scoop install unicli
  56. ```
  57. **Linux / Manual:** Download the latest binary from the [Releases](https://github.com/yucchiy/UniCli/releases) page and place it in your PATH.
  58. ### Unity Package
  59. The UniCli package must be installed in your Unity project. You can install it using the CLI:
  60. ```bash
  61. unicli install
  62. ```
  63. Or add it manually via Unity Package Manager using the git URL:
  64. ```
  65. https://github.com/yucchiy/UniCli.git?path=src/UniCli.Unity/Packages/com.yucchiy.unicli-server
  66. ```
  67. ### Quick Usage
  68. Open your Unity project in the Editor, then run `unicli` from the Unity project directory (or any subdirectory). UniCli automatically detects the project by looking for an `Assets` folder in the current directory and its ancestors.
  69. ```bash
  70. # Verify connection
  71. unicli check
  72. # List all available commands
  73. unicli commands
  74. # Compile scripts
  75. unicli exec Compile
  76. # Run EditMode tests
  77. unicli exec TestRunner.RunEditMode
  78. # Execute arbitrary C# code (--json for JSON output)
  79. unicli eval 'return Application.unityVersion;' --json
  80. ```
  81. ## CLI Usage
  82. The `unicli` binary provides the following subcommands:
  83. | Subcommand | Description |
  84. |---------------|-------------------------------------------------------------|
  85. | `check` | Check package installation and Unity Editor connection |
  86. | `install` | Install the UniCli package into a Unity project |
  87. | `exec` | Execute a command on the Unity Editor |
  88. | `eval` | Compile and execute C# code dynamically in the Unity Editor |
  89. | `commands` | List all available commands |
  90. | `status` | Show connection status and project info |
  91. | `completions` | Generate shell completion scripts (bash / zsh / fish) |
  92. ```
  93. unicli check # verify installation and editor connection
  94. unicli install # install the Unity package
  95. unicli commands # list all available commands
  96. unicli eval '<code>' # compile and execute C# code dynamically
  97. unicli status # show connection details
  98. unicli completions bash # generate shell completions
  99. ```
  100. Add `--json` to `check`, `commands`, or `status` for machine-readable JSON output.
  101. ### Project Discovery
  102. By default, `unicli` searches the current directory and its ancestors for a Unity project (a directory containing an `Assets` folder). If you run `unicli` from outside a Unity project, or want to target a specific project, set the `UNICLI_PROJECT` environment variable:
  103. ```bash
  104. # Run from anywhere by specifying the project path
  105. UNICLI_PROJECT=/path/to/my/unity-project unicli exec Compile --json
  106. # Useful when the current directory is not inside the Unity project
  107. UNICLI_PROJECT=src/UniCli.Unity unicli commands --json
  108. ```
  109. ## Executing Commands
  110. Use `unicli exec <command>` to run commands on the Unity Editor.
  111. ### Parameter syntax
  112. Parameters can be passed as `--key value` flags or as a raw JSON string. For arrays and nested values, JSON is often the clearest option:
  113. ```bash
  114. # --key value syntax
  115. unicli exec BuildPlayer.Build --locationPathName "Builds/Test.app" --options Development
  116. # Raw JSON syntax
  117. unicli exec GameObject.Find '{"name":"Main Camera"}'
  118. unicli exec GameObject.Find '{"namePattern":"Camera"}'
  119. unicli exec TestRunner.RunEditMode '{"testNames":["UniCli.Server.Editor.Tests.ResultTests.Success_IsSuccess_ReturnsTrue"]}'
  120. ```
  121. Boolean flags can be passed without a value:
  122. ```bash
  123. unicli exec GameObject.Find --includeInactive
  124. ```
  125. Array parameters can be passed by repeating the same flag:
  126. ```bash
  127. unicli exec BuildPlayer.Build --locationPathName "Builds/Test.app" --options Development --options ConnectWithProfiler
  128. unicli exec BuildPlayer.Compile --target iOS --extraScriptingDefines MY_DEFINE --extraScriptingDefines ANOTHER_DEFINE
  129. ```
  130. ### Common options
  131. These options can be combined with any `exec` command:
  132. | Option | Description |
  133. |-------------|--------------------------------------|
  134. | `--json` | Output in JSON format |
  135. | `--timeout` | Set command timeout in milliseconds |
  136. | `--no-focus`| Don't bring Unity Editor to front |
  137. | `--help` | Show command parameters and nested type details |
  138. By default, when the server is not responding (e.g., after an assembly reload), the CLI automatically brings Unity Editor to the foreground using a PID file (`Library/UniCli/server.pid`) and restores focus to the original application once the command completes on macOS and Windows. Linux currently skips foreground activation. Use `--no-focus` to disable this behavior, or set the `UNICLI_FOCUS` environment variable to `0` or `false` to disable it globally.
  139. ### Examples
  140. ```bash
  141. # Compile scripts (--json for JSON output, --timeout to set deadline)
  142. unicli exec Compile --json
  143. unicli exec Compile --timeout 30000
  144. # Build the player
  145. unicli exec BuildPlayer.Build --locationPathName "Builds/Test.app"
  146. unicli exec BuildPlayer.Build --locationPathName "Builds/Test-Android.apk" --options Development --target Android
  147. # Discover and run tests
  148. unicli exec TestRunner.List '{"mode":"EditMode"}' --json
  149. unicli exec TestRunner.RunEditMode
  150. unicli exec TestRunner.RunEditMode '{"testNames":["UniCli.Server.Editor.Tests.ResultTests.Success_IsSuccess_ReturnsTrue"],"stackTraceLines":3}'
  151. unicli exec TestRunner.RunEditMode --resultFilter all
  152. # Find and inspect GameObjects
  153. unicli exec GameObject.Find '{"name":"Main Camera"}'
  154. unicli exec GameObject.Find '{"namePattern":"Camera"}'
  155. unicli exec GameObject.GetHierarchy
  156. unicli exec GameObject.GetComponents --instanceId 1234
  157. # Create and modify GameObjects
  158. unicli exec GameObject.Create --name "Enemy"
  159. unicli exec GameObject.SetTransform '{"path":"Enemy","position":[1,2,3],"rotation":[0,90,0]}'
  160. unicli exec GameObject.AddComponent --path "Enemy" --typeName BoxCollider
  161. # Scene operations
  162. unicli exec Scene.Open --path "Assets/Scenes/Level1.unity"
  163. unicli exec Scene.Save --all
  164. # Dirty-scene policy: commands that would drop unsaved changes fail by default.
  165. # Choose explicitly: save the changes first, or discard them (scene commands only).
  166. unicli exec Scene.Open '{"path":"Assets/Scenes/Level1.unity","dirtyAction":"save"}'
  167. unicli exec Scene.New '{"empty":true,"dirtyAction":"discard"}'
  168. unicli exec TestRunner.RunPlayMode '{"dirtyAction":"save"}' --json
  169. # SceneView screenshots (lookAt: GameObject path; offset: added to the lookAt position)
  170. unicli exec Scene.Screenshot2D '{"lookAt":"Player","offset":[1,0],"size":5,"path":"Screenshots/map.png"}'
  171. unicli exec Scene.Screenshot3D '{"lookAt":"Player","yaw":45,"pitch":30,"distance":10,"path":"Screenshots/shot.png"}'
  172. # Set component properties
  173. unicli exec Component.SetProperty --componentInstanceId 1234 --propertyPath "m_IsKinematic" --value "true"
  174. # Console logs
  175. unicli exec Console.GetLog '{"logType":"Warning,Error"}'
  176. # Memory snapshot leak check (requires com.unity.memoryprofiler)
  177. unicli exec MemorySnapshot.Capture '{"path":"MemoryCaptures/before.snap"}' --json
  178. unicli exec MemorySnapshot.Load '{"path":"MemoryCaptures/before.snap","name":"before"}' --json
  179. unicli exec MemorySnapshot.Capture '{"path":"MemoryCaptures/after.snap"}' --json
  180. unicli exec MemorySnapshot.Load '{"path":"MemoryCaptures/after.snap","name":"after"}' --json
  181. unicli exec MemorySnapshot.AllOfMemory '{"snapshot":"after","baseSnapshot":"before","limit":20,"minSize":1048576,"minSizeDelta":1048576}' --json
  182. unicli exec MemorySnapshot.AllOfMemory '{"snapshot":"after","includeBreakdownTree":true,"pathFilter":"Native/Unity Subsystems","pathDepth":1,"memoryMetric":"both"}' --json
  183. unicli exec MemorySnapshot.Diff '{"baseSnapshot":"before","targetSnapshot":"after","scope":"native","minSizeDelta":1048576}' --json
  184. unicli exec MemorySnapshot.TopObjects '{"snapshot":"after","scope":"managed","groupByType":true,"limit":10}' --json
  185. unicli exec MemorySnapshot.Analyze '{"snapshot":"after","baseSnapshot":"before","limit":10}' --json
  186. # Show command parameters and usage
  187. unicli exec GameObject.Find --help
  188. ```
  189. ### Object instance ids
  190. `instanceId` / `componentInstanceId` fields are 64-bit integers (int64). On Unity 6.5+ they carry the full `EntityId` value, which exceeds the 32-bit range; on older Unity versions they are the legacy instance id widened to 64 bits. Treat them as opaque, session-scoped handles:
  191. - Pass ids back exactly as returned by a previous command. Do not truncate them to 32 bits.
  192. - Do not persist ids across Unity Editor restarts; they are only valid within the running session.
  193. - When post-processing `--json` output, use a tool that preserves 64-bit integers (`jq` 1.7+, Python). JavaScript-based tools lose precision above 2^53.
  194. ### Inspect nested request/response types
  195. `unicli exec <command> --help` shows top-level fields and, when available, nested type details.
  196. For machine-readable schemas, use `unicli commands --json`: nested types are exposed via each command's `requestTypeDetails` and `responseTypeDetails` arrays.
  197. Match nested type details by `typeId`; `type` and `typeName` stay human-friendly and may not be unique.
  198. ```bash
  199. # Human-friendly schema (includes nested type details)
  200. unicli exec AssetDatabase.Find --help
  201. # Machine-readable schema (commands include "requestTypeDetails" / "responseTypeDetails")
  202. unicli commands --json
  203. ```
  204. See [Built-in Commands](#built-in-commands) for the full list of available commands.
  205. ## Dynamic Code Execution (Eval)
  206. `unicli eval` compiles and executes arbitrary C# code in the Unity Editor context using `AssemblyBuilder`.
  207. Code has full access to Unity APIs (`UnityEngine`, `UnityEditor`) as well as any packages and libraries referenced by the project.
  208. Avoid APIs that show modal dialogs or file panels (`EditorUtility.DisplayDialog`, `EditorUtility.OpenFilePanel`, `EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo`, ...): they block the editor main loop, so the CLI keeps waiting until someone closes the dialog in the Editor.
  209. ```bash
  210. unicli eval '<code>' [--json] [--declarations '<decl>'] [--timeout <ms>] [--no-focus]
  211. ```
  212. | Option | Description |
  213. |---|---|
  214. | `--json` | Output in JSON format |
  215. | `--declarations` | Additional type declarations (classes, structs, enums) |
  216. | `--timeout` | Timeout in milliseconds |
  217. | `--no-focus` | Don't bring Unity Editor to front |
  218. For multi-line code, use shell heredocs:
  219. ```bash
  220. unicli eval "$(cat <<'EOF'
  221. var scene = UnityEngine.SceneManagement.SceneManager.GetActiveScene();
  222. var objects = GameObject.FindObjectsOfType<GameObject>(true);
  223. return $"{scene.name}: {objects.Length} objects";
  224. EOF
  225. )" --json
  226. ```
  227. The result is returned as raw JSON. If the return type is `[Serializable]`, it is serialized with `JsonUtility`.
  228. `UnityEngine.Object` types use `EditorJsonUtility`. Primitives and strings are returned directly. Code that doesn't return a value (`void` operations) returns `null`.
  229. Use `--declarations` to define custom types for structured return values:
  230. ```bash
  231. unicli eval "$(cat <<'EOF'
  232. var stats = new SceneStats();
  233. stats.sceneName = UnityEngine.SceneManagement.SceneManager.GetActiveScene().name;
  234. stats.objectCount = GameObject.FindObjectsOfType<GameObject>().Length;
  235. return stats;
  236. EOF
  237. )" --declarations "$(cat <<'EOF'
  238. [System.Serializable]
  239. public class SceneStats
  240. {
  241. public string sceneName;
  242. public int objectCount;
  243. }
  244. EOF
  245. )" --json
  246. ```
  247. Eval code supports `async`/`await` and receives a `cancellationToken` variable (`System.Threading.CancellationToken`) that is cancelled when the client disconnects.
  248. Use it for cooperative cancellation of long-running operations:
  249. ```bash
  250. # Wait asynchronously with cancellation support
  251. unicli eval 'await Task.Delay(5000, cancellationToken); return "done";' --json
  252. ```
  253. ## Custom Commands
  254. You can extend UniCli by adding custom commands in your Unity project. Commands are auto-discovered — no manual registration required.
  255. Inherit from `CommandHandler<TRequest, TResponse>` and define `[Serializable]` request/response types:
  256. ```csharp
  257. using System;
  258. using System.Threading;
  259. using System.Threading.Tasks;
  260. using UniCli.Protocol;
  261. using UniCli.Server.Editor.Handlers;
  262. public sealed class GreetHandler : CommandHandler<GreetRequest, GreetResponse>
  263. {
  264. public override string CommandName => "MyApp.Greet";
  265. public override string Description => "Returns a greeting message";
  266. protected override ValueTask<GreetResponse> ExecuteAsync(GreetRequest request, CancellationToken cancellationToken)
  267. {
  268. return new ValueTask<GreetResponse>(new GreetResponse
  269. {
  270. message = $"Hello, {request.name}!"
  271. });
  272. }
  273. }
  274. [Serializable]
  275. public class GreetRequest
  276. {
  277. public string name;
  278. }
  279. [Serializable]
  280. public class GreetResponse
  281. {
  282. public string message;
  283. }
  284. ```
  285. Once the handler is placed anywhere in your Unity project, it becomes immediately available:
  286. ```bash
  287. unicli exec MyApp.Greet --name "World"
  288. ```
  289. For naming conventions (when to use concept-based names like `Scene.*` vs API-direct names like `AssetDatabase.*`), see [`doc/command-naming-guidelines.md`](doc/command-naming-guidelines.md).
  290. For commands that require no input or produce no output, use `Unit` as the type parameter:
  291. ```csharp
  292. public sealed class PingHandler : CommandHandler<Unit, PingResponse>
  293. {
  294. public override string CommandName => "MyApp.Ping";
  295. public override string Description => "Health check";
  296. protected override ValueTask<PingResponse> ExecuteAsync(Unit request, CancellationToken cancellationToken)
  297. {
  298. return new ValueTask<PingResponse>(new PingResponse { ok = true });
  299. }
  300. }
  301. ```
  302. ### Text formatting
  303. Override `TryWriteFormatted` to provide human-readable output (used when `--json` is not specified):
  304. ```csharp
  305. protected override bool TryWriteFormatted(GreetResponse response, bool success, IFormatWriter writer)
  306. {
  307. writer.WriteLine(response.message);
  308. return true;
  309. }
  310. ```
  311. With this override, the output changes depending on whether `--json` is used:
  312. ```bash
  313. $ unicli exec MyApp.Greet --name "World"
  314. Hello, World!
  315. $ unicli exec MyApp.Greet --name "World" --json
  316. {"message":"Hello, World!"}
  317. ```
  318. ### Async handlers and cancellation
  319. All command handlers receive a `CancellationToken` that is cancelled when the client disconnects (e.g., Ctrl+C). For long-running async operations, pass the token through to ensure prompt cancellation:
  320. ```csharp
  321. using System.Threading;
  322. using System.Threading.Tasks;
  323. using UniCli.Server.Editor;
  324. using UniCli.Server.Editor.Handlers;
  325. public sealed class LongRunningHandler : CommandHandler<MyRequest, MyResponse>
  326. {
  327. public override string CommandName => "MyApp.LongTask";
  328. public override string Description => "A long-running async operation";
  329. protected override async ValueTask<MyResponse> ExecuteAsync(MyRequest request, CancellationToken cancellationToken)
  330. {
  331. var tcs = new TaskCompletionSource<string>();
  332. // Start an async Unity operation
  333. SomeAsyncUnityApi.Start(result => tcs.SetResult(result));
  334. // Use WithCancellation to abort the wait if the client disconnects
  335. var result = await tcs.Task.WithCancellation(cancellationToken);
  336. return new MyResponse { value = result };
  337. }
  338. }
  339. ```
  340. The `WithCancellation` extension method (on `Task` / `Task<T>`) races the task against the cancellation token. If the client disconnects, the await throws `OperationCanceledException` and the server immediately becomes available for the next command.
  341. For synchronous handlers that complete instantly, the `cancellationToken` parameter can be ignored.
  342. ### Error handling
  343. Throw `CommandFailedException` to report failures while still returning structured data:
  344. ```csharp
  345. if (hasErrors)
  346. throw new CommandFailedException("Validation failed", response);
  347. ```
  348. ## Built-in Commands
  349. The following commands are built in. Run `unicli commands` to see this list from the terminal, or `unicli exec <command> --help` to see parameters for any command. For a full reference with parameter and response details, see [`doc/commands.md`](doc/commands.md).
  350. ### Core
  351. | Command | Description |
  352. |---|---|
  353. | `Compile` | Compile scripts and return results |
  354. | `Editor.Status` | Get EditorApplication, EditorSceneManager, SceneManager, and PrefabStageUtility status |
  355. | `Eval` | Compile and execute C# code dynamically |
  356. ### Console
  357. | Command | Description |
  358. |---|---|
  359. | `Console.GetLog` | Get console log entries (supports comma-separated `logType` filter, e.g. `"Warning,Error"`) |
  360. | `Console.Clear` | Clear console |
  361. ### PlayMode
  362. | Command | Description |
  363. |---|---|
  364. | `PlayMode.Enter` | Enter play mode |
  365. | `PlayMode.Exit` | Exit play mode |
  366. | `PlayMode.Pause` | Toggle pause |
  367. | `PlayMode.Step` | Advance one frame in play mode |
  368. | `PlayMode.Status` | Get the current play mode state |
  369. ### TestRunner
  370. | Command | Description |
  371. |---|---|
  372. | `TestRunner.List` | List available tests for EditMode or PlayMode |
  373. | `TestRunner.RunEditMode` | Run EditMode tests (`resultFilter`: `"failures"` (default), `"all"`, `"none"`; `dirtyAction`: `"error"` (default), `"save"`) |
  374. | `TestRunner.RunPlayMode` | Run PlayMode tests (`resultFilter`: `"failures"` (default), `"all"`, `"none"`; `dirtyAction`: `"error"` (default), `"save"`) |
  375. ### Build
  376. | Command | Description |
  377. |---|---|
  378. | `BuildPlayer.Build` | Build the player |
  379. | `BuildPlayer.Compile` | Compile player scripts for a build target |
  380. | `BuildTarget.GetActive` | Get the active build target and target group |
  381. | `BuildTarget.Switch` | Switch the active build target |
  382. | `BuildProfile.List` | List all build profiles (Unity 6+) |
  383. | `BuildProfile.GetActive` | Get the active build profile (Unity 6+) |
  384. | `BuildProfile.SetActive` | Set the active build profile (Unity 6+) |
  385. | `BuildProfile.Inspect` | Inspect a build profile's details (Unity 6+) |
  386. ### GameObject / Component
  387. | Command | Description |
  388. |---|---|
  389. | `GameObject.Find` | Find GameObjects |
  390. | `GameObject.Create` | Create a new GameObject |
  391. | `GameObject.CreatePrimitive` | Create a primitive GameObject |
  392. | `GameObject.GetComponents` | Get components |
  393. | `GameObject.SetActive` | Set active state |
  394. | `GameObject.GetHierarchy` | Get scene hierarchy |
  395. | `GameObject.AddComponent` | Add a component |
  396. | `GameObject.RemoveComponent` | Remove a component |
  397. | `GameObject.Destroy` | Destroy a GameObject |
  398. | `GameObject.SetTransform` | Set local transform |
  399. | `GameObject.Duplicate` | Duplicate a GameObject |
  400. | `GameObject.Rename` | Rename a GameObject |
  401. | `GameObject.SetParent` | Change parent or move to root |
  402. | `Component.SetProperty` | Set a component property (supports ObjectReference via `guid:`, `instanceId:`, asset path) |
  403. ### Scene
  404. | Command | Description |
  405. |---|---|
  406. | `Scene.List` | List all loaded scenes |
  407. | `Scene.GetActive` | Get the active scene |
  408. | `Scene.SetActive` | Set the active scene |
  409. | `Scene.Open` | Open a scene by asset path (`dirtyAction`: `"error"` (default), `"save"`, `"discard"`) |
  410. | `Scene.Close` | Close a loaded scene (`dirtyAction`: `"error"` (default), `"save"`, `"discard"`) |
  411. | `Scene.Save` | Save a scene or all open scenes (untitled scenes require `saveAsPath`; saving them without a path is rejected instead of opening a file panel) |
  412. | `Scene.New` | Create a new scene (`dirtyAction`: `"error"` (default), `"save"`, `"discard"`) |
  413. | `Scene.Screenshot2D` | Capture a SceneView screenshot in 2D mode (orthographic) as PNG |
  414. | `Scene.Screenshot3D` | Capture a SceneView screenshot in 3D mode (orbit by yaw/pitch/distance) as PNG |
  415. Commands that would drop unsaved scene changes (`Scene.Open`/`Scene.New` in single mode, `Scene.Close`, and `TestRunner.RunEditMode`/`RunPlayMode`) refuse to run by default when a dirty scene is affected, instead of letting Unity discard the changes silently or show a blocking save dialog. Pass `dirtyAction: "save"` to save the scenes first, or `dirtyAction: "discard"` (scene commands only) to proceed without saving.
  416. ### Asset
  417. | Command | Description |
  418. |---|---|
  419. | `AssetDatabase.Find` | Search assets |
  420. | `AssetDatabase.Import` | Import an asset |
  421. | `AssetDatabase.GetPath` | Get asset path by GUID |
  422. | `AssetDatabase.Delete` | Delete an asset |
  423. | `Prefab.GetStatus` | Get prefab instance status |
  424. | `Prefab.Instantiate` | Instantiate a prefab into scene |
  425. | `Prefab.Save` | Save GameObject as prefab |
  426. | `Prefab.Apply` | Apply prefab overrides |
  427. | `Prefab.Unpack` | Unpack a prefab instance |
  428. | `Material.Create` | Create a new material asset |
  429. | `Material.Inspect` | Read all properties of a material (auto-generated) |
  430. | `Material.SetColor` | Set a color property on a material |
  431. | `Material.GetColor` | Get a color property from a material |
  432. | `Material.SetFloat` | Set a float property on a material |
  433. | `Material.GetFloat` | Get a float property from a material |
  434. ### Animation
  435. | Command | Description |
  436. |---|---|
  437. | `AnimatorController.Create` | Create a new .controller asset |
  438. | `AnimatorController.Inspect` | Inspect layers, parameters, states |
  439. | `AnimatorController.AddParameter` | Add a parameter |
  440. | `AnimatorController.RemoveParameter` | Remove a parameter |
  441. | `AnimatorController.AddState` | Add a state to a layer |
  442. | `AnimatorController.AddTransition` | Add a transition between states |
  443. | `AnimatorController.AddTransitionCondition` | Add a condition to a transition |
  444. | `Animator.Inspect` | Inspect Animator component |
  445. | `Animator.SetController` | Assign an AnimatorController |
  446. | `Animator.SetParameter` | Set a parameter value (PlayMode) |
  447. | `Animator.Play` | Play a state immediately (PlayMode) |
  448. | `Animator.CrossFade` | Cross-fade to a state (PlayMode) |
  449. ### PackageManager
  450. | Command | Description |
  451. |---|---|
  452. | `PackageManager.List` | List packages |
  453. | `PackageManager.Add` | Add a package |
  454. | `PackageManager.Remove` | Remove a package |
  455. | `PackageManager.Search` | Search registry |
  456. | `PackageManager.GetInfo` | Get package details |
  457. | `PackageManager.Update` | Update a package |
  458. ### Project / Settings
  459. | Command | Description |
  460. |---|---|
  461. | `Project.Inspect` | Get project info |
  462. | `PlayerSettings.Inspect` | Get all PlayerSettings values (auto-generated) |
  463. | `EditorSettings.Inspect` | Get all EditorSettings values (auto-generated) |
  464. | `EditorUserBuildSettings.Inspect` | Get all EditorUserBuildSettings values (auto-generated) |
  465. ### AssemblyDefinition
  466. | Command | Description |
  467. |---|---|
  468. | `AssemblyDefinition.List` | List assembly definitions |
  469. | `AssemblyDefinition.Get` | Get assembly definition |
  470. | `AssemblyDefinition.Create` | Create assembly definition |
  471. | `AssemblyDefinition.AddReference` | Add asmdef reference |
  472. | `AssemblyDefinition.RemoveReference` | Remove asmdef reference |
  473. ### Selection / Window / Menu
  474. | Command | Description |
  475. |---|---|
  476. | `Selection.Get` | Get the current editor selection |
  477. | `Selection.SetAsset` | Select an asset by path |
  478. | `Selection.SetAssets` | Select multiple assets by paths |
  479. | `Selection.SetGameObject` | Select a GameObject by path |
  480. | `Selection.SetGameObjects` | Select multiple GameObjects by paths |
  481. | `Window.List` | List all available EditorWindow types |
  482. | `Window.Open` | Open an EditorWindow by type name |
  483. | `Window.Focus` | Focus an already-open EditorWindow |
  484. | `Window.Create` | Create a new EditorWindow instance |
  485. | `Menu.List` | List menu items |
  486. | `Menu.Execute` | Execute a menu item (menu items that show dialogs or file panels block the editor and leave the CLI waiting — prefer dedicated commands where available) |
  487. ### Utility
  488. | Command | Description |
  489. |---|---|
  490. | `Type.List` | List types derived from a base type |
  491. | `Type.Inspect` | Inspect nested types of a given type |
  492. ### Connection / Remote
  493. | Command | Description |
  494. |---|---|
  495. | `Connection.List` | List available connection targets |
  496. | `Connection.Connect` | Connect to a target by ID, IP, or device ID |
  497. | `Connection.Status` | Get current connection status |
  498. | `Remote.List` | List debug commands on connected player |
  499. | `Remote.Invoke` | Invoke a debug command on connected player |
  500. ### Profiler
  501. | Command | Description |
  502. |---|---|
  503. | `Profiler.Inspect` | Get profiler status and memory statistics |
  504. | `Profiler.StartRecording` | Start profiler recording |
  505. | `Profiler.StopRecording` | Stop profiler recording |
  506. | `Profiler.SaveProfile` | Save profiler data to a .raw file |
  507. | `Profiler.LoadProfile` | Load profiler data from a .raw file |
  508. | `Profiler.GetFrameData` | Get CPU profiler sample data for a specific frame |
  509. | `Profiler.TakeSnapshot` | Take a memory snapshot (.snap file) |
  510. | `Profiler.AnalyzeFrames` | Analyze recorded frames and return aggregate statistics |
  511. | `Profiler.FindSpikes` | Find frames exceeding frame time or GC allocation thresholds |
  512. ### Optional: Memory Profiler
  513. Requires Unity Memory Profiler (`com.unity.memoryprofiler`). Use `MemorySnapshot.Capture`, `Profiler.TakeSnapshot`, or the Memory Profiler window to capture `.snap` files.
  514. | Command | Description |
  515. |---|---|
  516. | `MemorySnapshot.Capture` | Capture a `.snap` file with configurable `Unity.Profiling.Memory.CaptureFlags` |
  517. | `MemorySnapshot.List` | List memory snapshot (.snap) files |
  518. | `MemorySnapshot.Load` | Analyze and pin a snapshot under a `name`/`id` for later commands |
  519. | `MemorySnapshot.Summary` | Summarize category totals and metadata; use `snapshot` or `path`, omitted `path` uses the latest `MemoryCaptures/*.snap` |
  520. | `MemorySnapshot.AllOfMemory` | Show a Memory Profiler All Of Memory style report with `limit`, `scope`, `typeFilter`, `nameFilter`, `pathFilter`, `pathDepth`, `memoryMetric`, `minSize`, `minSizeDelta`, and `include*` filters |
  521. | `MemorySnapshot.TopObjects` | List largest retained native objects or native/managed type totals; use `snapshot` or `path` |
  522. | `MemorySnapshot.Diff` | Compare native or managed type deltas; use `baseSnapshot`/`targetSnapshot` or paths, omitted paths use latest and second latest captures |
  523. | `MemorySnapshot.Analyze` | Produce a compact summary/top/diff report for leak investigation |
  524. | `MemorySnapshot.Status` | Show loaded/cached snapshot analyses with id/name/pinned state |
  525. | `MemorySnapshot.Unload` | Release one loaded snapshot by `snapshot` id/name, or clear cached analysis results |
  526. `MemorySnapshot.AllOfMemory` can return a bounded flat `breakdownTree` with `includeBreakdownTree:true`; `pathFilter` matches root-origin `/` segments exactly and enables the tree implicitly. `memoryMetric` (`allocated`, `resident`, `both`) only affects `breakdownTree` sorting and `minSize`; type/object sections remain allocated-based, and resident falls back to allocated when unavailable.
  527. ### Screenshot / Recorder
  528. | Command | Description |
  529. |---|---|
  530. | `Screenshot.Capture` | Capture Game View screenshot as PNG (Edit Mode or Play Mode; pin with `mode`) |
  531. | `Recorder.StartRecording` | Start recording Game View as video (requires Play Mode) |
  532. | `Recorder.StopRecording` | Stop the current video recording |
  533. | `Recorder.Status` | Get the current recording status |
  534. ### Module
  535. | Command | Description |
  536. |---|---|
  537. | `Module.List` | List all available modules and their enabled status |
  538. | `Module.Enable` | Enable a module and reload the command dispatcher |
  539. | `Module.Disable` | Disable a module and reload the command dispatcher |
  540. ### Optional: Search
  541. | Command | Description |
  542. |---|---|
  543. | `Search` | Search Unity project using Unity Search API |
  544. ### Optional: NuGet
  545. Requires [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity).
  546. | Command | Description |
  547. |---|---|
  548. | `NuGet.List` | List all installed NuGet packages |
  549. | `NuGet.Install` | Install a NuGet package |
  550. | `NuGet.Uninstall` | Uninstall a NuGet package |
  551. | `NuGet.Restore` | Restore all NuGet packages |
  552. | `NuGet.ListSources` | List all configured package sources |
  553. | `NuGet.AddSource` | Add a NuGet package source |
  554. | `NuGet.RemoveSource` | Remove a NuGet package source |
  555. ### Optional: BuildMagic
  556. Requires [BuildMagic](https://github.com/AnnulusGames/BuildMagic) (`jp.co.cyberagent.buildmagic`).
  557. | Command | Description |
  558. |---|---|
  559. | `BuildMagic.List` | List all BuildMagic build schemes |
  560. | `BuildMagic.Inspect` | Inspect a build scheme's configurations |
  561. | `BuildMagic.Apply` | Apply a build scheme |
  562. Settings Inspect commands (`PlayerSettings.Inspect`, `EditorSettings.Inspect`, etc.) are auto-generated via a Roslyn Source Generator, so the available properties always match your exact Unity version. To **modify** settings, use `unicli eval`:
  563. ```bash
  564. unicli eval 'PlayerSettings.companyName = "MyCompany";' --json
  565. ```
  566. ## Module Management
  567. UniCli groups optional commands into **modules** that can be toggled on or off per project. Core commands (Compile, Eval, Console, PlayMode, Menu, Build, TestRunner, Settings, etc.) are always available and cannot be disabled.
  568. The following modules are available:
  569. | Module | Description |
  570. |---|---|
  571. | Scene | Scene operations |
  572. | GameObject | GameObject and Component operations |
  573. | Assets | AssetDatabase, Prefab, Material operations |
  574. | Profiler | Profiler operations |
  575. | Animation | Animator and AnimatorController operations |
  576. | Remote | Remote debug and Connection operations |
  577. | Recorder | Video recording operations (requires `com.unity.recorder`) |
  578. | MemoryProfiler | Memory snapshot analysis operations (requires `com.unity.memoryprofiler`) |
  579. | Search | Unity Search API operations |
  580. | NuGet | NuGet package management (requires NuGetForUnity) |
  581. | BuildMagic | BuildMagic build scheme operations (requires `jp.co.cyberagent.buildmagic`) |
  582. All modules are enabled by default. To disable a module, use the CLI or the Unity settings UI (**Edit > Project Settings > UniCli**):
  583. ```bash
  584. # List all modules and their enabled status
  585. unicli exec Module.List --json
  586. # Enable a module
  587. unicli exec Module.Enable '{"name":"Search"}' --json
  588. # Disable a module
  589. unicli exec Module.Disable '{"name":"Profiler"}' --json
  590. ```
  591. Module settings are saved in `ProjectSettings/UniCliSettings.asset`.
  592. `unicli commands --json` includes `builtIn` and `module` fields for each command, so you can programmatically identify whether a command is built-in or user-defined and which module it belongs to.
  593. ## Architecture
  594. UniCli consists of two components:
  595. - **CLI** (`unicli`) — A NativeAOT-compiled binary that you run from the terminal
  596. - **Unity Package** (`com.yucchiy.unicli-server`) — An Editor plugin that receives and executes commands inside Unity
  597. ### Architecture
  598. ```
  599. ┌──────────┐ Named Pipe ┌────────────────┐ PlayerConnection ┌────────────────┐
  600. │ unicli │◄───────────────►│ Unity Editor │◄──────────────────►│ Device │
  601. │ (CLI) │ Length-prefixed │ (Server) │ Chunked messages │ (Dev Build) │
  602. │ │ JSON messages │ │ │ │
  603. └──────────┘ └────────────────┘ └────────────────┘
  604. ```
  605. **CLI ↔ Editor (Named Pipe):**
  606. The CLI and Unity Editor communicate over a named pipe. The pipe name is derived from a SHA256 hash of the project's `Assets` path, so each project gets its own connection. Messages use a length-prefixed JSON framing protocol with a handshake (magic bytes `UCLI` + protocol version). The server plugin initializes via `[InitializeOnLoad]`, creates a background listener on the named pipe, and enqueues incoming commands to a `ConcurrentQueue`. Commands are dequeued and executed on Unity's main thread every frame via `EditorApplication.update`.
  607. **Editor ↔ Device (PlayerConnection):**
  608. For remote debugging, the Editor relays commands to a running Development Build via Unity's `PlayerConnection`. The runtime module (`UniCli.Remote`) auto-initializes a `RuntimeDebugReceiver` on the device, which discovers debug commands via reflection and registers message handlers. Responses are split into 16 KB chunks to work around PlayerConnection's undocumented message size limits. The Editor's `RemoteBridge` reassembles chunks and returns the complete response to the CLI.
  609. ## Remote Commands
  610. UniCli can invoke debug commands on a running Development Build via Unity's `PlayerConnection`. This lets you inspect runtime state, query performance stats, and execute custom debug operations on a connected device — all from the terminal.
  611. **Communication path:** CLI → Unity Editor (Named Pipe) → Device (PlayerConnection)
  612. ### Prerequisites
  613. 1. **Define symbol** — Add `UNICLI_REMOTE` to your project's Scripting Define Symbols (Player Settings → Other Settings).
  614. - The remote module's asmdef has two define constraints: `UNICLI_REMOTE || UNITY_EDITOR` and `DEVELOPMENT_BUILD || UNITY_EDITOR`.
  615. - In the Editor, both constraints are satisfied automatically — no additional setup needed for development.
  616. - In player builds, `UNICLI_REMOTE` must be defined **and** the build must be a Development Build for the module to be included.
  617. - This means release builds and builds without `UNICLI_REMOTE` will never contain the remote module code.
  618. 2. **Development Build** — Build with the "Development Build" and "Autoconnect Profiler" options enabled to allow PlayerConnection communication.
  619. 3. **Connect** — Use `Connection.Connect` to connect the Editor to the running player before sending remote commands.
  620. ### Editor-side commands
  621. | Command | Description |
  622. |---|---|
  623. | `Remote.List` | List all debug commands registered on the connected player |
  624. | `Remote.Invoke` | Invoke a debug command on the connected player |
  625. ```bash
  626. # List debug commands on connected runtime player
  627. unicli exec Remote.List
  628. # Invoke a debug command
  629. unicli exec Remote.Invoke '{"command":"Debug.Stats"}'
  630. # Invoke with parameters
  631. unicli exec Remote.Invoke '{"command":"Debug.GetPlayerPref","data":"{\"key\":\"HighScore\",\"type\":\"int\"}"}'
  632. # Specify a particular player (when multiple are connected)
  633. unicli exec Remote.Invoke '{"command":"Debug.SystemInfo","playerId":1}'
  634. ```
  635. ### Built-in debug commands
  636. The following debug commands are included in the package and available on any Development Build with `UNICLI_REMOTE` defined:
  637. | Command | Description |
  638. |---|---|
  639. | `Debug.SystemInfo` | Device model, OS, CPU, GPU, memory, battery, screen, quality settings |
  640. | `Debug.Stats` | FPS, frame time, memory usage, GC collection counts, scene/object counts |
  641. | `Debug.GetLogs` | Recent log entries from a ring buffer (supports limit and type filter) |
  642. | `Debug.GetHierarchy` | Active scene hierarchy tree with depth, active state, component names |
  643. | `Debug.FindGameObjects` | Substring search across all GameObjects (including inactive) |
  644. | `Debug.GetScenes` | All loaded scenes with name, path, build index, root count |
  645. | `Debug.GetPlayerPref` | Read a PlayerPrefs value by key (string, int, or float) |
  646. ### Creating custom debug commands
  647. Inherit from `DebugCommand<TRequest, TResponse>` and override `CommandName` / `Description`. Commands are auto-discovered at runtime via reflection.
  648. ```csharp
  649. using System;
  650. using UniCli.Remote;
  651. using UnityEngine;
  652. public sealed class ToggleHitboxesCommand : DebugCommand<ToggleHitboxesCommand.Request, ToggleHitboxesCommand.Response>
  653. {
  654. public override string CommandName => "Debug.ToggleHitboxes";
  655. public override string Description => "Toggle hitbox visualization";
  656. protected override Response ExecuteCommand(Request request)
  657. {
  658. HitboxVisualizer.Enabled = request.enabled;
  659. return new Response { enabled = HitboxVisualizer.Enabled };
  660. }
  661. [Serializable]
  662. public class Request
  663. {
  664. public bool enabled;
  665. }
  666. [Serializable]
  667. public class Response
  668. {
  669. public bool enabled;
  670. }
  671. }
  672. ```
  673. Use `Unit` as the type parameter when no input or output is needed:
  674. ```csharp
  675. public sealed class ResetStateCommand : DebugCommand<Unit, Unit>
  676. {
  677. public override string CommandName => "Debug.ResetState";
  678. public override string Description => "Reset game state";
  679. protected override Unit ExecuteCommand(Unit request)
  680. {
  681. GameManager.ResetAll();
  682. return Unit.Value;
  683. }
  684. }
  685. ```
  686. Key points:
  687. - Request/Response types must be `[Serializable]` with **public fields** (required by `JsonUtility`)
  688. - The base class uses `[RequireDerived]` to protect all subclasses from Managed Stripping automatically
  689. - Commands run synchronously on the main thread
  690. - Override `CommandName` (by convention `Debug.*`) and optionally `Description`
  691. - Place custom commands anywhere in your project — they are discovered automatically via reflection at startup
  692. ## AI Agent Integration
  693. ### Claude Code Plugin
  694. UniCli provides a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin via the marketplace. This plugin gives Claude Code the ability to interact with Unity Editor — compiling scripts, running tests, inspecting GameObjects, managing packages, and more — as part of its coding workflow.
  695. With the plugin installed, Claude Code can:
  696. - **Compile & verify** — catch compilation errors immediately after code changes
  697. - **Run tests** — execute EditMode / PlayMode tests and read results
  698. - **Inspect the scene** — find GameObjects, check components, and navigate the hierarchy
  699. - **Manage packages** — add, remove, and search Unity packages
  700. - **Discover commands** — automatically find all available commands, including project-specific custom commands
  701. The plugin also handles server package setup: if the `com.yucchiy.unicli-server` package is not yet installed in the Unity project, Claude Code will run `unicli install` to set it up automatically.
  702. #### Install the plugin
  703. The UniCli CLI must be installed beforehand. See [Getting Started — CLI](#cli) above.
  704. ```bash
  705. # 1. Add the UniCli marketplace
  706. /plugin marketplace add yucchiy/UniCli
  707. # 2. Install the plugin
  708. /plugin install unicli@unicli
  709. ```
  710. ### Agent Skills / Codex
  711. UniCli's skill definition follows the [Agent Skills](https://github.com/anthropics/agent-skills) specification, making it compatible with multiple AI coding agents:
  712. - **Codex (OpenAI)**: Automatically detected via `.agents/skills/unity-development/`
  713. - **Claude Code**: Installed as a plugin via `.claude-plugin/`
  714. - **Other agents**: Any tool that supports the Agent Skills spec can load the skill from `.agents/skills/`
  715. #### Install via Codex `$skill-installer`
  716. If you're using [Codex](https://openai.com/index/introducing-codex/), install the UniCli skill directly from this repository:
  717. ```
  718. $skill-installer install https://github.com/yucchiy/UniCli/tree/main/.agents/skills/unity-development
  719. ```
  720. Once installed, Codex automatically detects the skill and gains the ability to interact with Unity Editor.
  721. #### Manual setup for other projects
  722. To use UniCli's skill in another project, copy the skill directory:
  723. ```bash
  724. mkdir -p .agents/skills
  725. cp -R /path/to/UniCli/.agents/skills/unity-development .agents/skills/unity-development
  726. ```
  727. ## License
  728. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.