Content
# unity-cli
[English](README.md) | [Korean](README.ko.md)
> Control Unity Editor from the command line. Built for AI agents, works with anything.
[](LICENSE)
**No server to run. No config to write. No process to manage. Just type a command.**
## Why this exists
I wanted to control Unity from the terminal. The existing MCP-based integrations required Python runtimes, WebSocket relays, JSON-RPC protocol layers, config files, server processes that need to be started and stopped, tool registration ceremonies, and tens of thousands of lines of over-engineered code. All just to send a simple command to Unity.
On top of that, every AI agent that wanted to use it needed its own MCP config and integration setup. The CLI doesn't care — any agent that can run a shell command can use it immediately.
That felt wrong. If I can `curl` a URL, why do I need all that?
So I built the opposite: a single binary that talks directly to Unity via HTTP. No server to run — the Unity package listens automatically. No config to write — it discovers Unity instances on its own. No tool registration — just call by name. No caching, no protocol layers, no ceremony.
The entire CLI is ~800 lines of Go (plus ~300 lines of help text). The Unity-side connector is ~2,300 lines of C#. It's just a thin layer that lets you control Unity from the shell — nothing more. You install the binary, add the Unity package, and it works.
## Install
### Linux / macOS
```bash
curl -fsSL https://raw.githubusercontent.com/youngwoocho02/unity-cli/master/install.sh | sh
```
### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/youngwoocho02/unity-cli/master/install.ps1 | iex
```
### Other options
```bash
# Go install (any platform with Go)
go install github.com/youngwoocho02/unity-cli@latest
# Manual download (pick your platform)
# Linux amd64 / Linux arm64 / macOS amd64 / macOS arm64 / Windows amd64
curl -fsSL https://github.com/youngwoocho02/unity-cli/releases/latest/download/unity-cli-linux-amd64 -o unity-cli
chmod +x unity-cli && sudo mv unity-cli /usr/local/bin/
```
Supported platforms: Linux (amd64, arm64), macOS (Intel, Apple Silicon), Windows (amd64).
### Update
```bash
# Update to the latest version
unity-cli update
# Check for updates without installing
unity-cli update --check
```
## Unity Setup
Add the Unity Connector package via **Package Manager → Add package from git URL**:
```
https://github.com/youngwoocho02/unity-cli.git?path=unity-connector
```
Or add directly to `Packages/manifest.json`:
```json
"com.youngwoocho02.unity-cli-connector": "https://github.com/youngwoocho02/unity-cli.git?path=unity-connector"
```
To pin a specific version, append a tag to the URL (e.g. `#v0.2.21`).
Once added, the Connector starts automatically when Unity opens. No configuration needed.
### Recommended: Disable Editor Throttling
By default, Unity throttles editor updates when the window is unfocused. This can delay CLI commands because Unity API work is dispatched on the Editor main thread.
To fix this, go to **Edit → Preferences → General → Interaction Mode** and set it to **No Throttling**.
The connector also requests a PlayerLoop update whenever a CLI request arrives. No Throttling is still recommended for the most responsive background behavior.
## Quick Start
```bash
# Check Unity connection
unity-cli status
# Enter play mode and wait
unity-cli editor play --wait
# Run C# code inside Unity
unity-cli exec "return Application.dataPath;"
# Read console logs
unity-cli console --type error,warning,log
```
## How It Works
```
Terminal Unity Editor
──────── ────────────
$ unity-cli editor play --wait
│
├─ scans ~/.unity-cli/instances/*.json
│ → selects the Unity instance for this project
│
├─ waits until Unity can accept a command
│ (not compiling / reloading / busy)
│
├─ sends command to the selected Unity listener
│ { "command": "manage_editor",
│ "params": { "action": "play" }}
│ │
│ HttpServer receives
│ │
│ CommandRouter dispatches
│ │
│ ManageEditor.HandleCommand()
│ → EditorApplication.isPlaying = true
│ │
├─ receives JSON response ←───────────┘
│
├─ polls heartbeat until state is playing
│
└─ prints: Entered play mode (confirmed).
```
The Unity Connector:
1. Opens a local HTTP listener when the Editor starts
2. Writes a per-project instance file to `~/.unity-cli/instances/` so the CLI knows where to connect
3. Updates the instance file every 0.5s with the current state (heartbeat)
4. Discovers all `[UnityCliTool]` classes via reflection on each request
5. Routes incoming commands to the matching handler on the main thread
6. Survives domain reloads (script recompilation)
Before compiling or reloading, the Connector records the state (`compiling`, `reloading`) to the instance file. `/command` is accepted only when state is `ready`, `playing`, or `paused`. Otherwise the CLI waits and tries again until `--timeout`.
## Live tests
With Unity Editor open:
```powershell
powershell -File scripts/live-test.ps1
powershell -File scripts/live-test.ps1 -Project C:/path/to/unity-project
```
Builds the current CLI and sends every built-in command against a running Editor: exec (including async policy), overlapping/serialized requests, console filters, menu (including File/Quit block), scene/game screenshots, profiler, play/pause/stop/refresh, manage_editor tag/layer/tool, one-asset reserialize, and empty EditMode/PlayMode test runs. Does not trigger a full script recompile or reserialize the whole project.
## Built-in Commands
| Command | Description |
|---------|-------------|
| `editor` | Play/stop/pause/refresh the Unity Editor |
| `console` | Read, filter, and clear console logs |
| `exec` | Run arbitrary C# code inside Unity |
| `test` | Run EditMode/PlayMode tests |
| `menu` | Execute any Unity menu item by path |
| `reserialize` | Re-serialize assets through Unity's serializer |
| `screenshot` | Capture scene/game view as PNG |
| `profiler` | Read profiler hierarchy, control recording |
| `list` | Show all available tools with parameter schemas |
| `status` | Show Unity Editor connection state |
| `update` | Self-update the CLI binary |
### Editor Control
```bash
# Enter play mode
unity-cli editor play
# Enter play mode and wait until fully loaded
unity-cli editor play --wait
# Stop play mode
unity-cli editor stop
# Toggle pause (only works during play mode)
unity-cli editor pause
# Refresh assets (blocked in play mode unless --force is set)
unity-cli editor refresh
# Refresh and recompile scripts (also blocked in play mode unless --force is set)
unity-cli editor refresh --compile
# Force refresh while in play mode
unity-cli editor refresh --force
```
### Console Logs
```bash
# Read error and warning logs (default)
unity-cli console
# Read last 20 log entries of all types
unity-cli console --lines 20 --filter error,warning,log
# Read only errors
unity-cli console --type error
# Include stack traces (user: user code only, full: raw)
unity-cli console --stacktrace user
# Clear console
unity-cli console --clear
```
### Execute C# Code
Run arbitrary C# code inside the Unity Editor at runtime. This is the most powerful command — it gives you full access to UnityEngine, UnityEditor, ECS, and every loaded assembly. No need to write a custom tool for one-off queries or mutations.
Use `return` to get output. Common namespaces are included by default. Add `--usings` only for project-specific types (e.g. `Unity.Entities`). `--usings` accepts comma-separated namespaces and can be repeated. The csc compiler and dotnet runtime are auto-detected; if detection fails, specify manually with `--csc <path>` or `--dotnet <path>`.
```bash
unity-cli exec "return Application.dataPath;"
unity-cli exec "return EditorSceneManager.GetActiveScene().name;"
unity-cli exec "return World.All.Count;" --usings Unity.Entities
unity-cli exec "return World.All.Count;" --usings Unity.Entities --usings Unity.Mathematics
# Pipe via stdin to avoid shell escaping issues
echo 'Debug.Log("hello"); return null;' | unity-cli exec
echo 'var go = new GameObject("Marker"); go.tag = "EditorOnly"; return go.name;' | unity-cli exec
```
`exec` blocks async, coroutine, and deferred Unity callback keywords by default because the command returns before those paths complete. Use `--allow-async` only when that delayed behavior is intentional.
Because `exec` compiles and runs real C#, it can do anything a custom tool can — inspect ECS entities, modify assets, call internal APIs, run editor utilities. For AI agents, this means **zero-friction access to Unity's entire runtime** without writing a single line of tool code. Piping via stdin avoids shell escaping headaches with complex code.
### Menu Items
```bash
# Execute any Unity menu item by path
unity-cli menu "File/Save Project"
unity-cli menu "Assets/Refresh"
unity-cli menu "Window/General/Console"
```
Note: `File/Quit` is blocked for safety.
### Asset Reserialize
AI agents (and humans) can edit Unity asset files — `.prefab`, `.unity`, `.asset`, `.mat` — as plain text YAML. But Unity's YAML serializer is strict: a missing field, wrong indent, or stale `fileID` will corrupt the asset silently.
`reserialize` fixes this. After a text edit, it tells Unity to load the asset into memory and write it back out through its own serializer. The result is a clean, valid YAML file — as if you had edited it through the Inspector.
```bash
# Reserialize the entire project (no arguments)
unity-cli reserialize
# After editing a prefab's transform values in a text editor
unity-cli reserialize Assets/Prefabs/Player.prefab
# After batch-editing multiple scenes
unity-cli reserialize Assets/Scenes/Main.unity Assets/Scenes/Lobby.unity
# After modifying material properties
unity-cli reserialize Assets/Materials/Character.mat
```
This is what makes text-based asset editing safe. Without it, a single misplaced YAML field can break a prefab with no visible error until runtime. With it, **AI agents can confidently modify any Unity asset through plain text** — add components to prefabs, adjust scene hierarchies, change material properties — and know the result will load correctly.
### Profiler
```bash
# Read profiler hierarchy (last frame, top-level)
unity-cli profiler hierarchy
# Recursive drill-down
unity-cli profiler hierarchy --depth 3
# Set root by name (substring match) — focus on a specific system
unity-cli profiler hierarchy --root SimulationSystem --depth 3
# Drill into a specific item by ID
unity-cli profiler hierarchy --parent 4 --depth 2
# Average over last 30 frames
unity-cli profiler hierarchy --frames 30 --min 0.5
# Average over a specific frame range
unity-cli profiler hierarchy --from 100 --to 200
# Filter and sort
unity-cli profiler hierarchy --min 0.5 --sort self --max 10
# Enable/disable profiler recording
# disable clears Profiler window Record + profileEditor + ProfilerDriver.enabled
unity-cli profiler enable
unity-cli profiler disable
# Show profiler state (enabled, profileEditor, windowIsSetToRecord, frame range)
unity-cli profiler status
# Clear captured frames
unity-cli profiler clear
```
> **Recording OFF:** `ProfilerDriver.enabled = false` alone is not enough. Edit Mode can keep capturing while the Profiler window Record button (`IsSetToRecord`) or `ProfilerDriver.profileEditor` stays on. `profiler disable` must clear all three.
### Run Tests
Run EditMode and PlayMode tests via the Unity Test Framework.
```bash
# Run EditMode tests (default)
unity-cli test
# Run PlayMode tests
unity-cli test --mode PlayMode
# Filter by test name (substring match)
unity-cli test --filter MyTestClass
```
Requires the Unity Test Framework package. PlayMode tests trigger a domain reload; the CLI polls for results automatically.
### List Tools
```bash
# Show all available tools (built-in + project custom) with parameter schemas
unity-cli list
```
### Custom Tools
```bash
# Call a custom tool directly by name
unity-cli my_custom_tool
# Call with parameters
unity-cli my_custom_tool --params '{"key": "value"}'
```
### Status
```bash
# Show Unity Editor state
unity-cli status
# Output: Unity: ready
# Project: /path/to/project
# Version: 6000.1.0f1
# PID: 12345
```
Send a command once. The CLI waits until Unity can accept it, then delivers one response. It does not leave a request hanging and does not need a second send. `--timeout` bounds that wait.
## Global Options
| Flag | Description | Default |
|------|-------------|---------|
| `--project <path>` | Select Unity instance by project path | auto |
| `--timeout <ms>` | Wait for Unity to accept, then for the response | 120000 |
| `--ignore-version-mismatch` | Skip CLI/connector version check | false |
```bash
# Select by project path when multiple Unity instances are open
unity-cli --project MyGame editor stop
# Run even when the CLI and connector versions differ
unity-cli --ignore-version-mismatch status
```
Use `--help` on any command for detailed usage:
```bash
unity-cli editor --help
unity-cli exec --help
unity-cli profiler --help
```
## Writing Custom Tools
Create a static class with `[UnityCliTool]` attribute in any Editor assembly. The Connector discovers it automatically on domain reload.
```csharp
using UnityCliConnector;
using Newtonsoft.Json.Linq;
using UnityEngine;
[UnityCliTool(Name = "spawn", Description = "Spawn an enemy at a position", Group = "gameplay")]
public static class SpawnEnemy
{
public class Parameters
{
[ToolParameter("X world position", Required = true)]
public float X { get; set; }
[ToolParameter("Y world position", Required = true)]
public float Y { get; set; }
[ToolParameter("Z world position", Required = true)]
public float Z { get; set; }
[ToolParameter("Prefab name in Resources folder", DefaultValue = "Enemy")]
public string Prefab { get; set; }
}
public static object HandleCommand(JObject parameters)
{
var p = new ToolParams(parameters);
float x = p.GetFloat("x", 0);
float y = p.GetFloat("y", 0);
float z = p.GetFloat("z", 0);
string prefabName = p.Get("prefab", "Enemy");
var prefab = Resources.Load<GameObject>(prefabName);
var instance = Object.Instantiate(prefab, new Vector3(x, y, z), Quaternion.identity);
return new SuccessResponse("Enemy spawned", new
{
name = instance.name,
position = new { x, y, z }
});
}
}
```
Call it directly with flags or JSON:
```bash
unity-cli spawn --x 1 --y 0 --z 5 --prefab Goblin
unity-cli spawn --params '{"x":1,"y":0,"z":5,"prefab":"Goblin"}'
```
**Key points:**
- **Name**: without `Name`, auto-derived from class name (`SpawnEnemy` → `spawn_enemy`, `UITree` → `ui_tree`). With `Name = "spawn"`, the command becomes `unity-cli spawn`.
- **Parameters class**: optional but recommended. `unity-cli list` uses it to expose parameter names, types, descriptions, and required flags — so AI assistants can discover your tool without reading the source.
- **ToolParams**: use `p.Get()`, `p.GetInt()`, `p.GetFloat()`, `p.GetBool()`, `p.GetRaw()` for consistent param reading.
- **Discovery**: `unity-cli list` shows built-in tools first (`group: "built-in"`), then custom tools (`group: "custom"`) detected from the connected Unity project.
**Attribute reference:**
| Attribute | Property | Description |
|---|---|---|
| `[UnityCliTool]` | `Name` | Command name override (default: class name → snake_case) |
| | `Description` | Tool description shown in `list` |
| | `Group` | Group name for categorization |
| `[ToolParameter]` | `Description` | Parameter description (constructor arg) |
| | `Required` | Whether the parameter is required (default: `false`) |
| | `Name` | Parameter name override |
| | `DefaultValue` | Default value hint |
### Rules
- Class must be `static`
- Must have `public static object HandleCommand(JObject parameters)` or `async Task<object>` variant
- Return `SuccessResponse(message, data)` or `ErrorResponse(message)`
- Add a `Parameters` nested class with `[ToolParameter]` attributes for discoverability
- Class name is auto-converted to snake_case for the command name
- Override with `[UnityCliTool(Name = "my_name")]` if needed
- Runs on Unity main thread, so all Unity APIs are safe to call
- Discovered automatically on Editor start and after every script recompilation
- Duplicate tool names are detected and logged as errors — only the first discovered handler is used
## Multiple Unity Instances
When multiple Unity Editors are open, each registers its project path:
```bash
# See all running instances
unity-cli status
# Select by project path
unity-cli --project MyGame editor play
# Default: uses the current working directory's Unity project, or the only active instance
unity-cli editor play
```
## Compared to MCP
| | MCP | unity-cli |
|---|-----|-----------|
| **Install** | Python + uv + FastMCP + config JSON | Single binary |
| **Dependencies** | Python runtime, WebSocket relay | None |
| **Protocol** | JSON-RPC 2.0 over stdio + WebSocket | Direct HTTP POST |
| **Setup** | Generate MCP config, restart AI tool | Add Unity package, done |
| **Reconnection** | Complex reconnect logic for domain reloads | Stateless per request |
| **Client support** | MCP client setup only | Anything with a shell |
| **Custom tools** | Same `[Attribute]` + `HandleCommand` pattern | Same |
## Author
Created by **DevBookOfArray**
[](https://www.youtube.com/@DevBookOfArray)
[](https://github.com/youngwoocho02)
## License
MIT
