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

Recommended: Claude Code Plugin

Install the unity-cli plugin from Claude Code Marketplace:

/plugin marketplace add akiojin/unity-cli

The marketplace plugin installs skills only. Install the unity-cli binary separately using one of the manual options below.

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)

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

This downloads the latest release binary to ~/.unity/tools/unity-cli/{rid}/ and symlinks it to ~/.local/bin/unity-cli. After the initial install the CLI checks for updates automatically in the background — no manual upgrades needed.

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.

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 .

Unity-side bridge package (choose one):

OpenUPM (recommended):

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

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 Migration (Issue-first)

If you need to migrate local specs/SPEC-* directories to GitHub issues, use:

scripts/migrate-specs-to-issues.sh --dry-run --specs-dir "$(pwd)/specs"

If the plan looks correct, run without --dry-run:

scripts/migrate-specs-to-issues.sh --specs-dir "$(pwd)/specs"

The script writes progress/results to migration-report.json and applies the gwt-spec label to the created issues.

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.