iTranslated by AI
I Built a CLI Tool for Controlling the Unity Editor
Overview
I have developed a tool for controlling the Unity Editor via the terminal, and I would like to introduce it here.
Why I created it
When using coding agents for Unity development, it is common to use MCP tools like UnityMCP to control Unity. This eliminates the need for copy-pasting from the console and is extremely convenient; I have been using it in my actual development. However, in my specific workflow, I encountered the following issues:
- MCP's resident design
- While the coding agent has constant access to the tool, it consumes the context window at all times (measured at 18.4k tokens).
- The scrap from when I was experimenting with this can be found here.
- The developer also wants to control the editor from the CLI
- As the development style becomes more agent-centric, one starts to want to complete every task within the terminal.
- When having the agent analyze error logs, rather than starting by saying "read the error logs," it is more reliable to start by passing the logs into the context by executing a direct command like
!unity console get.
Therefore, I decided to build this with a focus on CLI usage while referencing the basic mechanism of UnityMCP.
Installation
Unity
You can install it from the Unity Package Manager using the following URL:
https://github.com/bigdra50/unity-cli.git?path=UnityBridge
Or if you are using OpenUPM:
$ openupm add com.bigdra50.unity-bridge
CLI
Execute directly with uvx:
# Play mode control
$ uvx --from git+https://github.com/bigdra50/unity-cli u play
$ uvx --from git+https://github.com/bigdra50/unity-cli u stop
# Console log retrieval
$ uvx --from git+https://github.com/bigdra50/unity-cli u console get -l E
Global installation:
$ uv tool install git+https://github.com/bigdra50/unity-cli
After installation, you can use the three aliases: unity-cli, u, and unity.
$ unity-cli state
$ unity state
$ u state
Shell completion is also available.
# zsh
$ u completion -s zsh > ~/.zsh/completions/_unity-cli
# bash
$ u completion -s bash >> ~/.bashrc
# fish
$ u completion -s fish > ~/.config/fish/completions/unity-cli.fish

Usage
unity-cli commands are broadly divided into two categories.
Commands that do not require launching the Unity Editor
Retrieving project information
$ u project info
╭──────────────────────────────────────────────────╮
│ MyGame │
╰────── /Users/username/Projects/MyGame ───────────╯
Company: MyCompany
Version: 1.0.0
Unity: 2022.3.20f1
If you only want to retrieve the Unity version:
$ u project version
Unity: 2022.3.20f1
Managing installed Unity editors
$ u editor list
Installed Editors (2)
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Version ┃ Path ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╩
│ 2023.2.10f1 │ /Applications/Unity/Hub/Editor/… │
│ 2022.3.20f1 │ /Applications/Unity/Hub/Editor/… │
└──────────────┴──────────────────────────────────┘
Opening a project
This is often used after a git clone.
# Open project in Unity Editor
$ u open
# Open with a specific version
$ u open --version 2022.3.20f1
Checking settings
$ u config show
=== Unity CLI Configuration ===
Config file: Not found (using defaults)
Relay host: 127.0.0.1
Relay port: 6500
Timeout: 15.0s
Instance: (default)
Commands that require the Unity Editor to be running
These commands interact with the Unity Editor via the Relay Server while it is running. Before using the commands below, you need to start and connect the Relay Server.
Starting the Relay Server
Open Window > Unity Bridge in the Unity Editor and click Start Server, then Connect.

Once the status becomes "Connected," you are ready. You can also check the connection status via the toolbar badge in the top right of the editor. Clicking the badge also allows you to toggle the connection.

You can also launch the Relay Server directly from the CLI:
$ uvx --from git+https://github.com/bigdra50/unity-cli unity-relay --port 6500
The Relay Server accepts connections from multiple Unity instances in a single process. Even if you have multiple Unity projects open at the same time, you just need to connect to the same server from each instance; there is no need to launch the server twice.
You can check the instances to operate with u instances and specify them using the -i option.
# List of connected instances
$ u instances
Connected Instances (1)
┏━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
┃ # ┃ Project ┃ Unity Version ┃ Status ┃ Default ┃
┡━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩
│ 1 │ TestProject │ 6000.2.6f2 │ ready │ * │
└───┴─────────────┴───────────────┴────────┴─────────┘
# Execute a command specifying an instance
$ u -i TestProject state
Verifying C# script compilation
Workflow to check for compilation errors after editing a script:
# Refresh AssetDatabase and execute compilation
$ u refresh
[OK] Asset database refreshed
# Displays if there are any errors
$ u console get -l E
06:53:37 error Assets/Scripts/Player/PlayerHealth.cs(44,13): error CS0201: Only
assignment, call, increment, decrement, await, and new object expressions can be
used as a statement
06:53:37 error Assets/Scripts/Player/PlayerHealth.cs(44,13): error CS0103: The
name 'hoge' does not exist in the current context
# After fixing errors, clear the console and recompile
$ u console clear
[OK] Console cleared
$ u refresh
[OK] Asset database refreshed
# No errors = no output
$ u console get -l E
You can also display with stack traces using the -v option, which is useful for investigating runtime errors:
$ u console get -l E -v
Running tests
EditMode tests:
# Check the list of tests
$ u tests list edit
{
"mode": "edit",
"count": 38,
"tests": [
{ "fullName": "Game.Tests.Editor.DamageCalculatorTests.Calculate_AppliesCriticalMultiplier_WhenCritical", ... },
{ "fullName": "Game.Tests.Editor.InventoryTests.AddItem_IncreasesSlotCount_WhenNewItem", ... },
...
]
}
# Run tests
$ u tests run edit
Running tests (46/46) Pass:38 Fail:0 Skip:0
PlayMode tests:
$ u tests list play
$ u tests run play
Running tests (17/17) Pass:19 Fail:0 Skip:0
Running disposable scripts with menu exec
menu exec is a command to execute MenuItem from the CLI. While it can be used to run existing MenuItems, it is also convenient for writing and executing disposable scripts.
When you want to request Editor API operations that aren't covered by the unity-cli commands, you can have the agent write a script with [MenuItem] and execute it with menu exec. For example, this includes tasks such as placing objects in a scene or manipulating the Inspector.
# 1. Agent generates a script with [MenuItem("Tools/TempSetup")]
# 2. Compile -> Execute -> Cleanup
$ u refresh
$ u menu exec "Tools/TempSetup"
$ rm Assets/Editor/TempSetup.cs && u refresh
Since anything possible with the Editor API can be executed this way, it serves as a receptacle for operations that don't have dedicated CLI commands.
Integration with Coding Agents
Error messages for agents
To help coding agents recover easily when errors occur while executing commands autonomously, I include next actions in the error messages.
# Attempting to pause when not in Play mode
$ u pause
Error: Cannot pause: not in play mode. Enter play mode first with action 'enter'.
# Passing an invalid action
$ u play --action foo
Error: Unknown action: foo. Valid actions: enter, exit, pause, unpause, step, state
# Instance not found
$ u state
Error: Instance not found. Check available instances with 'u instances'.
Agents can read the error messages to determine the next command to execute, allowing them to proceed with recovery without human intervention.
Integration example: From UI creation to screenshots
Below is an execution log when I instructed Claude Code to "Create a game title screen with a neumorphism style using UI Toolkit, place it in the scene, and take a screenshot." Claude Code performs everything autonomously, from creating UXML/USS/C# to verifying the behavior in Unity.

Demo UI created with UIToolkit
# 1. After the agent creates UXML, USS, and C# scripts...
# Refresh AssetDatabase and compile
$ u refresh
[OK] Asset database refreshed
# Check for compilation errors
$ u console get -l E
(No output = No errors)
# Create a GameObject in the scene and add components
$ u gameobject create -n SampleHUD
$ u component add -t SampleHUD -T UnityEngine.UIElements.UIDocument
$ u component add -t SampleHUD -T SampleHUDController
$ u scene save
# Enter PlayMode and verify UI display
$ u play
[OK] Entered play mode
# Dump UI tree to check structure
$ u uitree dump -p "PanelSettings" -d 3
Panel: PanelSettings (36 elements)
VisualElement "Root" .root ref_3
VisualElement "StatusBar" .status-bar ref_4
Label "StatusTime" ref_5
VisualElement "TitleCard" .neu-card .profile-card ref_6
VisualElement .title-area ref_7
VisualElement .xp-section ref_10
VisualElement "Chapters" .section ref_22
Label .section-title ref_23
VisualElement .card-row ref_24
VisualElement "Menu" .section ref_46
VisualElement .action-row ref_47
VisualElement "Toast" .toast .hidden ref_54
Label "ToastMessage" ref_55
VisualElement "TabBar" .neu-card .tab-bar ref_57
VisualElement "TabHome" .tab .tab-active ref_58
VisualElement "TabQuest" .tab ref_60
VisualElement "TabCodex" .tab ref_62
VisualElement "TabConfig" .tab ref_64
# Take a GameView screenshot
$ u screenshot -s game -p ./screenshot.png
[OK] Screenshot captured: ./screenshot.png
$ u stop
[OK] Exited play mode
Integration example: Exploring and interacting with the UI tree
The uitree command uses a ref ID-based operation system similar to Playwright MCP, allowing you to search, inspect, and manipulate UI Toolkit elements.
Below is an example session when passing the following prompt to Claude Code. Claude Code autonomously cycles through dump -> query -> text -> click -> inspect.
Enter Play mode and explore the UI Toolkit elements using the unity-cli uitree command.
Try grasping the UI tree structure, searching/inspecting elements, retrieving text, and verifying state changes via click operations.
# Enter Play mode and get a list of panels
$ u uitree dump
Panels:
[Editor] DockArea (21 elements)
[Editor] Toolbar (76 elements)
[Player] PanelSettings (65 elements)
[Player] UIDocument SamplePanelSettings (SampleHUD) (64 elements)
...
# Dump the UI tree structure (ref IDs are assigned to each element)
$ u uitree dump -p "SampleHUD" -d 3
Panel: UIDocument SamplePanelSettings (SampleHUD) (20 elements)
UIDocumentRootElement "SampleHUD-container" ref_1
VisualElement "Root" .root ref_2
VisualElement "StatusBar" .status-bar ref_3
VisualElement "TitleCard" .neu-card .profile-card ref_4
VisualElement .title-area ref_5
VisualElement .xp-section ref_8
VisualElement "Chapters" .section ref_15
Label .section-title ref_16
VisualElement .card-row ref_17
VisualElement "Menu" .section ref_18
VisualElement .action-row ref_19
VisualElement "Toast" .toast .hidden ref_20
VisualElement "TabBar" .neu-card .tab-bar ref_21
# Read text via ref ID
$ u uitree text ref_167
ref_167 Label: Story Progress
$ u uitree text ref_197
ref_197 Label: SETTINGS
# Search for elements by type
$ u uitree query -p "SampleHUD" -t Label
Found 29 elements in "SampleHUD":
ref_147 Label "StatusTime" ...
ref_148 Label .game-title ...
...
# Inspect with children -> Verify Chapter1 has the card-selected class
$ u uitree inspect ref_171 --children
ref_171 VisualElement "Chapter1"
classes: .neu-card .featured-card .card-selected
visible: True
...
# Click Chapter2 to verify state change
$ u uitree click ref_178
ref_178 VisualElement: Clicked element
$ u uitree inspect ref_178
ref_178 VisualElement "Chapter2"
classes: .neu-card .featured-card .card-selected # <- Selection moved
...
# Click tab -> Verify movement of tab-active
$ u uitree click ref_155
ref_155 VisualElement: Clicked element
$ u uitree inspect ref_155
ref_155 VisualElement "TabQuest"
classes: .tab .tab-active # <- tab-active was applied
...
# Click CONTINUE button -> Verify Toast message
$ u uitree click ref_192
ref_192 VisualElement: Clicked element
$ u uitree text ref_153
ref_153 Label: Loading save data...
With the dump -> click -> inspect/text cycle, Claude Code can autonomously perform UI operations and verify the results.
Teaching commands to Claude Code
Instead of consuming context constantly like MCP, you need a way to inform Claude Code about the command system. Basically, just writing commonly used commands concisely in the project's CLAUDE.md is sufficient.
## Commands
| Command | Purpose |
| -------------------------------- | ------------------------- |
| `u state` | Get editor state |
| `u play` / `u stop` | Play/Stop mode control |
| `u refresh` | Refresh AssetDatabase |
| `u console get -l E` | Get error logs |
| `u tests run edit` | Run EditMode tests |
| `u uitree dump -p <panel>` | Dump UI tree |
| `u screenshot -s game -p <path>` | Capture screenshot |
However, if you write down entire workflows like "refresh -> compilation error check -> test -> runtime verification" in CLAUDE.md, the context consumption increases and becomes counterproductive. Therefore, I extract workflow-based procedures as Skills. Since Skills are only loaded into the context when called, they allow you to pass complex procedures to the agent while avoiding constant context consumption.
These Skills are being converted into Claude Code plugins on an experimental basis.
# Add from marketplace
/plugin marketplace add bigdra50/unity-cli
# Install
/plugin install unity-cli@unity-tools
Conclusion
The toolchain surrounding coding agents is evolving rapidly, and the current design is not necessarily the optimal one for half a year from now. I intend to continue adding and improving necessary features while using it in practice.
Since Skills often depend on project-specific workflows, the policy for now is to prioritize expanding the functionality of the CLI itself.
Issues and PRs are welcome. I look forward to your feedback if you find anything while using it.
Update (2026-02-11): Added Relay Server startup instructions, connection verification via toolbar badge, and supplementary notes for multiple instance connections.
Discussion