{"id":17479,"library":"uloop-cli","title":"uloop-cli: Unity Editor CLI Companion","description":"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.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/hatayama/unity-cli-loop","tags":["javascript","cli","unity","mcp","uloop"],"install":[{"cmd":"npm install uloop-cli","lang":"bash","label":"npm"},{"cmd":"yarn add uloop-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add uloop-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import uloop from 'uloop-cli'","symbol":"uloop","correct":"npm install -g uloop-cli\nuloop --help"},{"note":"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.","wrong":"uloop.compile()","symbol":"uloop compile","correct":"uloop compile --project-path ./MyUnityProject"},{"note":"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.","wrong":"uloop install skills","symbol":"uloop skills install","correct":"uloop skills install --claude --global"}],"quickstart":{"code":"npm install -g uloop-cli\n\n# Assuming Unity CLI Loop (uLoopMCP) is installed and running in your Unity project.\n# This example installs skills for Claude Code globally and then executes a compilation.\n# Replace './path/to/your/unity/project' with the actual path.\n\n# Step 1: Install skills for LLM tools (e.g., Claude Code)\n# This allows LLMs to automatically use uloop commands.\nuloop skills install --claude --global\n\n# Step 2: Compile your Unity project\n# This command will trigger a compilation within the specified Unity Editor instance.\n# The '--wait-for-domain-reload true' flag ensures the CLI waits until Unity has finished its domain reload.\n# The output will indicate compilation success or failure and any errors/warnings.\nuloop compile --project-path ./path/to/your/unity/project --wait-for-domain-reload true\n\n# Step 3: Example of chaining commands: Compile, wait, then enter Play Mode\n# This demonstrates automating a sequence of operations.\nuloop compile --project-path ./path/to/your/unity/project --wait-for-domain-reload true && \\\nuloop control-play-mode --project-path ./path/to/your/unity/project --action Play","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update to v1.7.2 or newer to remove the deprecation warning if it was a concern. No functional change is required.","message":"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.","severity":"gotcha","affected_versions":">=1.7.0 <1.7.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0 <1.7.3"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run the command again with `uloop <command> --project-path /path/to/your/unity/project`.","cause":"The `uloop-cli` command was executed without `--project-path` and could not automatically detect a Unity project in the current working directory.","error":"Error: Unity project not found in current directory. Please specify --project-path."},{"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.","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.","error":"Failed to connect to uLoopMCP server. Is Unity Editor running with uLoopMCP?"},{"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.","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.","error":"Unknown command: 'my-custom-skill'. Available commands: [compile, run-tests, ...]"}],"ecosystem":"npm","meta_description":null}