uloop-cli

library2.0.3jsnpmunverified

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.

llm-agents devops workflow

npm install uloop-cli

github ↗package ↗

INSTALL

IMPORT

SIG · ULOOP-CLI

uloop-cli

llm-agentsjavascriptv2.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

uloop

✓ npm install -g uloop-cli uloop --help

✗ import uloop from 'uloop-cli'

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

✓ uloop compile --project-path ./MyUnityProject

✗ uloop.compile()

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

✓ uloop skills install --claude --global

✗ uloop install skills

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.

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

uloop-cli --version

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

gotchaRunning `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.

affects: >=1.7.0 <1.7.2

gotchaWhen `--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.

affects: >=1.0.0

gotchaEarly 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.

affects: >=1.0.0 <1.7.3

Errors

Common errors & fixes

Error: Unity project not found in current directory. Please specify --project-path.

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?

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, ...]

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.

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

60 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hatayama/unity-cli-loop ↗

packagehttps://www.npmjs.com/package/uloop-cli ↗