# unity-cli
`unity-cli` is a Rust CLI that lets Claude Code control Unity Editor over direct TCP.
It is the successor to [`unity-mcp-server`](https://github.com/akiojin/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
```text
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](docs/editor-compatibility.md) 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:
```bash
/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:
```bash
Windows (PowerShell):
```powershell
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`):
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Set `UNITY_CLI_NO_AUTO_UPDATE=1` to disable auto-update.
### Package Managers
```bash
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](https://github.com/akiojin/unity-cli/releases), or install from a
local checkout:
```bash
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):
```bash
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**:
```bash
openupm add com.akiojin.unity-cli-bridge
```
**Git URL** (Unity Package Manager):
```text
https://github.com/akiojin/unity-cli.git?path=UnityCliBridge/Packages/unity-cli-bridge
```
Connection check:
```bash
unity-cli system ping
unity-cli doctor --output json # when ping fails: SAFE_MODE / BRIDGE_NOT_INSTALLED / PORT_IN_USE / ...
```
Managed binary maintenance:
```bash
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".
| Getting Started | `unity-cli-usage` |
| Scenes & Objects | `unity-scene-create`, `unity-scene-inspect`, `unity-gameobject-edit`, `unity-prefab-workflow` |
| Assets | `unity-asset-management`, `unity-addressables` |
| Code | `unity-csharp-navigate`, `unity-csharp-edit` |
| Runtime & Testing | `unity-playmode-testing`, `unity-input-system`, `unity-ui-automation` |
| Editor | `unity-editor-tools` |
| Maintenance | `gh-skills-sync` |
## Quick Examples
```bash
# 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](CONTRIBUTING.md) before opening a PR, especially for branch
policy, required CI, and skill documentation changes.
## Configuration
| `UNITY_PROJECT_ROOT` | Directory containing `Assets/` and `Packages/` | auto-detect |
| `UNITY_CLI_HOST` | Unity Editor host | `127.0.0.1` |
| `UNITY_CLI_PORT` | Unity Editor port | `6400` |
| `UNITY_CLI_TIMEOUT_MS` | Command timeout (ms) | `30000` |
| `UNITY_CLI_LSP_MODE` | LSP mode (`off` / `auto` / `required`) | `off` |
| `UNITY_CLI_TOOLS_ROOT` | Downloaded tools root directory | OS default |
| `UNITY_CLI_NO_AUTO_UPDATE` | Disable background auto-update (`1` to disable) | *(unset)* |
Legacy MCP-prefixed variables are not supported. Use `UNITY_CLI_*` only.
## Documentation
- Full command and tool catalog: [docs/tools.md](docs/tools.md)
- Development workflow and CI: [docs/development.md](docs/development.md)
- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Release process: [RELEASE.md](RELEASE.md)
- Attribution templates: [ATTRIBUTION.md](ATTRIBUTION.md)
## License
MIT. See [ATTRIBUTION.md](ATTRIBUTION.md) for redistribution attribution templates.