unity-cli

日本語 | 中文 | Français | Deutsch | Italiano | Español

unity-cli is a Rust CLI that lets Claude Code control Unity Editor over direct TCP. It is the successor to unity-mcp-server, redesigned from Node.js + MCP to a native binary workflow.

Why unity-cli

• Operate Unity from Claude Code with focused skills and typed commands.
• Access 101 Unity Tool APIs across scene, asset, code, test, UI, and editor domains.
• Run as a single binary with fast startup and low overhead.

How It Works

Claude Code
  -> Skills (on demand)
  -> unity-cli
  -> Unity Editor (TCP bridge)

Some code tools (read, search, find_symbol, find_refs, etc.) run locally without a Unity connection.

Getting Started

Editor compatibility

The Bridge requires Unity 2022.3 or newer. The macOS matrix covers 2022.3.62f3, 6000.0.84f1, 6000.3.25f1, 6000.4.11f1, 6000.5.3f1, 6000.6.3f1, 6000.7.0a2 and 6000.7.0b2 (acceptance E2E: PASS on 2026-09-30). See the verification dates and results before choosing a version. Unity 6000.7 Editor runs on Mono; CoreCLR Player builds are outside this matrix.

Recommended: Claude Code Plugin

Install the unity-cli plugin from Claude Code Marketplace:

/plugin marketplace add akiojin/unity-cli

The plugin ships skills; the binary and the Unity bridge are bootstrapped on demand. When a task needs Unity and unity-cli is missing, the unity-cli-usage skill has the agent run the Quick Install script below and then unity-cli setup in your Unity project (it tells you before editing Packages/manifest.json).

Codex Skills

When using this repository with Codex, skills are available via .codex/skills/ (symlinks to the plugin source). No additional setup is required - just clone the repository.

Quick Install (recommended)

macOS (Apple silicon / Intel) and Linux:

curl -fsSL https://raw.githubusercontent.com/akiojin/unity-cli/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/akiojin/unity-cli/main/scripts/install.ps1 | iex

Both installers download the release binary into the managed layout ~/.unity/tools/unity-cli/{rid}/ and verify it against the release SHA256SUMS before installing; a checksum mismatch aborts the install and leaves the existing binary untouched. install.sh symlinks it to ~/.local/bin/unity-cli; install.ps1 adds the managed directory to the user PATH. Set UNITY_CLI_VERSION=v0.16.0 to pin a release. After the initial install the CLI checks for updates automatically in the background, and every update is verified against the same checksums.

If ~/.local/bin is not in your PATH, add the following to your shell profile (e.g. ~/.zshrc or ~/.bashrc):

export PATH="$HOME/.local/bin:$PATH"

Set UNITY_CLI_NO_AUTO_UPDATE=1 to disable auto-update.

Package Managers

brew install akiojin/tap/unity-cli     # macOS / Linux (Homebrew)
winget install akiojin.unity-cli       # Windows (winget)

Package-manager installs are updated by brew upgrade / winget upgrade. On Intel macOS, reference embeddings (unity-cli reference embed-build / embed-search) load ONNX Runtime dynamically; the Homebrew formula installs onnxruntime, otherwise run brew install onnxruntime or set ORT_DYLIB_PATH.

Manual Install

Download the latest binary from GitHub Releases, or install from a local checkout:

git clone https://github.com/akiojin/unity-cli.git
cd unity-cli
cargo install --path .

One-command project setup (binary check → bridge install → Editor connection):

cd /path/to/YourUnityProject
unity-cli --output json setup --launch-editor

setup adds the OpenUPM scoped registry and com.akiojin.unity-cli-bridge (pinned to the CLI version) to Packages/manifest.json, optionally launches the project's Unity Hub Editor, waits for the bridge, and returns one JSON report. unity-cli bridge install | upgrade | status manage the package on their own; install is idempotent, and setup / system ping report a versionCheck when the CLI and bridge versions differ. When the project still uses only the legacy Input Manager and the Editor is closed, install also sets activeInputHandler to Both in ProjectSettings/ProjectSettings.asset, so the Input System dependency imports without a blocking restart prompt.

Unity-side bridge package, manual alternatives (choose one):

OpenUPM:

openupm add com.akiojin.unity-cli-bridge

Git URL (Unity Package Manager):

https://github.com/akiojin/unity-cli.git?path=UnityCliBridge/Packages/unity-cli-bridge

Connection check:

unity-cli system ping
unity-cli doctor --output json   # when ping fails: SAFE_MODE / BRIDGE_NOT_INSTALLED / PORT_IN_USE / ...

Managed binary maintenance:

unity-cli cli doctor
unity-cli cli install

unityd and lspd automatically refresh their managed unity-cli / C# LSP binaries on daemon startup. The managed copies live under UNITY_CLI_TOOLS_ROOT (or the OS default tools directory) and are updated without an interactive confirmation prompt.

Skills (14)

These skills are written as workflow guides, not just command catalogs. They are designed to trigger from natural Unity requests such as "create a test scene", "trace references to this MonoBehaviour", or "run PlayMode tests and capture a screenshot".

Quick Examples

# Connectivity
unity-cli system ping

# Create a scene
unity-cli scene create MainScene

# Create a GameObject through raw tool call
unity-cli raw create_gameobject --json '{"name":"Player"}'

# Search C# code (local tool)
unity-cli tool call search --json '{"pattern":"PlayerController"}'

# Inspect machine-readable tool schema
unity-cli tool schema create_scene --output json

# Dry-run mutating tool calls (no side effects)
unity-cli --dry-run tool call create_scene --json '{"sceneName":"PreviewScene"}'

# Run EditMode tests
unity-cli tool call run_tests --json '{"mode":"editmode"}'

GWT Spec Workflow

Feature specifications are managed in GitHub Issues labeled gwt-spec. Use the Issue body as the source of truth for Spec, Plan, Tasks, and TDD.

Contributing

External contributions should target the develop branch. Read CONTRIBUTING.md before opening a PR, especially for branch policy, required CI, and skill documentation changes.

Configuration

Legacy MCP-prefixed variables are not supported. Use UNITY_CLI_* only.

Documentation

• Full command and tool catalog: docs/tools.md
• Development workflow and CI: docs/development.md
• Contribution guide: CONTRIBUTING.md
• Release process: RELEASE.md
• Attribution templates: ATTRIBUTION.md

License

MIT. See ATTRIBUTION.md for redistribution attribution templates.