uloop-cli: Unity Editor CLI Companion

2.0.3 · active · verified Wed Apr 22

uloop-cli is a command-line interface (CLI) tool designed to communicate with the Unity Editor via the Unity CLI Loop (uLoopMCP) server. It enables external applications, particularly AI agents and Large Language Models (LLMs), to automate Unity operations such as compiling code, running tests, getting console logs, and controlling Play Mode. The current stable version is 2.0.3, released on April 22, 2026. The package maintains a rapid release cadence, with multiple bugfix releases often occurring on the same day following a major or minor update. Its key differentiator is facilitating direct, programmatic control of the Unity Editor through a standardized CLI, abstracting away the complexities of Unity's internal scripting for external tools and AI, enabling seamless integration for automated development workflows.

Common errors

```
Error: Unity project not found in current directory. Please specify --project-path.
```
cause The `uloop-cli` command was executed without `--project-path` and could not automatically detect a Unity project in the current working directory.

fix Run the command again with `uloop <command> --project-path /path/to/your/unity/project`.
```
Failed to connect to uLoopMCP server. Is Unity Editor running with uLoopMCP?
```
cause The Unity Editor is either not running, or the `uLoopMCP` package is not installed/running within the Unity project, preventing the CLI from establishing a connection.

fix Ensure your Unity Editor is open, the correct Unity project is loaded, and the `uLoopMCP` server is active within the uLoopMCP Window in Unity.
```
Unknown command: 'my-custom-skill'. Available commands: [compile, run-tests, ...]
```
cause The custom skill you are trying to invoke has not been properly defined or synced from the Unity project, or the CLI cannot detect it.

fix Verify that your custom skill is correctly set up in your Unity project, that `uLoopMCP` is running, and try running `uloop sync --project-path /path/to/your/unity/project` to refresh the CLI's cached skill definitions.

Warnings

breaking Version 2.0.0 introduced significant performance improvements for `execute-dynamic-code` (over 6x faster) and a revamped Setup Wizard. While this is a feature, it implies internal changes that might affect highly customized scripts or integrations that relied on previous wizard behavior or execution timing. Review the release notes for detailed behavioral changes.
Fix: Review the new Setup Wizard flow and the improved `execute-dynamic-code` performance. If automating setup, adjust scripts to accommodate the clearer and more reliable new setup behavior. No direct code fix is generally needed for standard CLI usage.
gotcha Running `uloop update` previously showed a deprecation warning, which was removed in v1.7.2. While not a breaking change, users might have encountered this warning and should be aware it's no longer present.
Fix: Update to v1.7.2 or newer to remove the deprecation warning if it was a concern. No functional change is required.
gotcha When `--project-path` is omitted, `uloop-cli` attempts to detect the Unity project in the current directory. This can lead to unexpected behavior or incorrect project targeting if not executed from the desired Unity project root or if multiple projects are present.
Fix: Always explicitly specify `--project-path <path/to/your/unity/project>` when executing commands, especially in environments where the current working directory is not guaranteed to be the Unity project root, or when managing multiple Unity instances.
gotcha Early versions could produce 'Unity not running' errors or misleading editor availability errors even when Unity was open. These issues were addressed in versions like 1.7.1 and 1.7.3.
Fix: Ensure you are running version 1.7.3 or newer to benefit from improved Unity Editor detection and error reporting. If on an older version, manually verify Unity Editor status and ensure `uLoopMCP` server is running.

Install

npm install uloop-cli npm
yarn add uloop-cli yarn
pnpm add uloop-cli pnpm

Imports

uloop
wrong:
```
import uloop from 'uloop-cli'
```
correct:
```
npm install -g uloop-cli
uloop --help
```
This package is a CLI tool and is primarily used by invoking the `uloop` command globally after installation, not by importing symbols directly into a JavaScript/TypeScript project.
uloop compile
wrong:
```
uloop.compile()
```
correct:
```
uloop compile --project-path ./MyUnityProject
```
CLI commands are executed directly in the terminal. The `--project-path` flag is crucial when operating on specific Unity projects, especially if multiple are present or the command is not run from the project root.
uloop skills install
wrong:
```
uloop install skills
```
correct:
```
uloop skills install --claude --global
```
Skills are integrations that allow LLM tools (e.g., Claude, OpenAI Codex) to automatically invoke `uloop` commands. `--claude` and `--codex` specify the target LLM environment, while `--global` changes the installation scope.

Quickstart

Installs necessary 'skills' for LLMs to interact with Unity, compiles a Unity project, and then chains commands to compile and enter Play Mode, demonstrating basic automation.

npm install -g uloop-cli

# Assuming Unity CLI Loop (uLoopMCP) is installed and running in your Unity project.
# This example installs skills for Claude Code globally and then executes a compilation.
# Replace './path/to/your/unity/project' with the actual path.

# Step 1: Install skills for LLM tools (e.g., Claude Code)
# This allows LLMs to automatically use uloop commands.
uloop skills install --claude --global

# Step 2: Compile your Unity project
# This command will trigger a compilation within the specified Unity Editor instance.
# The '--wait-for-domain-reload true' flag ensures the CLI waits until Unity has finished its domain reload.
# The output will indicate compilation success or failure and any errors/warnings.
uloop compile --project-path ./path/to/your/unity/project --wait-for-domain-reload true

# Step 3: Example of chaining commands: Compile, wait, then enter Play Mode
# This demonstrates automating a sequence of operations.
uloop compile --project-path ./path/to/your/unity/project --wait-for-domain-reload true && \
uloop control-play-mode --project-path ./path/to/your/unity/project --action Play

view raw JSON →