unity-cli

KO | EN

gitlite — search

#python #ai-agent #agentic-ai #automation #mcp-server #claude-code #genpark #llm-tools #llm #ai #mcp #ai-agents

★ 39 Open GitHub ↗

CLI tool for controlling Unity Editor via command line - Play Mode, console logs, tests, scenes, GameObjects and more

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Unity CLI

[![CI](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml)
[![Complexity](https://img.shields.io/badge/complexity-A%2FB-brightgreen)](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml)
[![Maintainability](https://img.shields.io/badge/maintainability-A-brightgreen)](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com/bigdra50/unity-cli)
[![Unity](https://img.shields.io/badge/Unity-2022.3%2B-black?logo=unity)](https://unity.com/)
[![openupm](https://img.shields.io/npm/v/com.bigdra50.unity-bridge?label=openupm&registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.bigdra50.unity-bridge/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bigdra50/unity-cli)

[日本語版](README.jp.md)

A CLI tool for controlling Unity Editor from the command line.

## Overview

Execute Unity Editor operations from CLI: Play Mode control, console log retrieval, test execution, scene/GameObject manipulation, and more.

```bash
# Play Mode control
u play
u stop

# Get console logs (error and above)
u console get -l E

# Execute menu items
u menu exec "Assets/Refresh"

# Execute ContextMenu
u menu context "DoSomething" -t "/Player"
```

Key features:
- Execute Unity Editor operations from CLI
- Support for MenuItem / ContextMenu execution
- Simultaneous control of multiple Unity instances
- Domain reload resilience (auto-reconnection)
- UI Toolkit VisualElement tree inspection (dump, query, inspect, click, scroll, text)
- Dynamic API invocation (`u api call/schema` — 5,243+ Unity static methods)
- Monkey testing (`u uitree monkey`) and structural snapshots (`u uitree snapshot`)
- Open projects with appropriate version (Unity Hub integration)
- Project information retrieval (no Relay Server required)

## Requirements

- [uv](https://docs.astral.sh/uv/) (Python package manager)
- Python 3.11+
- Unity 2022.3+
- Unity Hub (for `open`/`editor` commands)

## Quick Start

### 1. Unity Setup

Add the UnityBridge package to your Unity project:

```bash
# Via OpenUPM (recommended)
openupm add com.bigdra50.unity-bridge

# Or via git URL
# Window > Package Manager > + > Add package from git URL...
# https://github.com/bigdra50/unity-cli.git?path=UnityBridge
```

### 2. Connection

In Unity Editor, open `Window > Unity Bridge`:
1. Click Start Server (launches Relay Server)
2. Click Connect (Unity → Relay connection)

The toolbar indicator (right side) shows connection status and allows toggle via click.

### 3. CLI Operations

```bash
# Run directly with uvx (no installation required)
uvx --from git+https://github.com/bigdra50/unity-cli u state

# Play Mode control
uvx --from git+https://github.com/bigdra50/unity-cli u play
uvx --from git+https://github.com/bigdra50/unity-cli u stop

# Get console logs (error and above)
uvx --from git+https://github.com/bigdra50/unity-cli u console get -l E
```

## Installation

```bash
# Global installation
uv tool install git+https://github.com/bigdra50/unity-cli

# With interactive UI (editor selection prompt)
uv tool install "git+https://github.com/bigdra50/unity-cli[interactive]"

# CLI commands (both aliases work the same)
unity-cli state    # Full name
u state            # Short alias

u play
u console get -l E | head -10  # Last 10 error+ logs

# Run Relay Server standalone
unity-relay --port 6500
```

## CLI Commands

### Version

```bash
u version                     # Show CLI version
```

### Shell Completion

```bash
# Zsh
u completion -s zsh > ~/.zsh/completions/_unity-cli

# Bash
u completion -s bash >> ~/.bashrc

# Fish
u completion -s fish > ~/.config/fish/completions/unity-cli.fish

# PowerShell
u completion -s powershell >> $PROFILE
```

### Open Project

```bash
# Open project with appropriate version (reads ProjectVersion.txt)
u open ./MyUnityProject

# Specify editor version
u open ./MyUnityProject --editor 2022.3.10f1

# Non-interactive mode (for CI/scripts)
u open ./MyUnityProject --non-interactive

# Wait until exit
u open ./MyUnityProject --wait
```

### Editor Management

```bash
# List installed editors
u editor list

# Install editor
u editor install 2022.3.10f1

# Install with modules
u editor install 2022.3.10f1 --modules android ios webgl

# Install non-release version with changeset
u editor install 6000.1.0a1 --changeset abc123
```

### Project Information (No Relay Server Required)

```bash
# Full project info
u project info ./MyUnityProject

# Unity version only
u project version ./MyUnityProject

# Package list
u project packages ./MyUnityProject
u project packages ./MyUnityProject --include-modules  # Include built-in modules

# Tags & layers
u project tags ./MyUnityProject

# Quality settings
u project quality ./MyUnityProject

# Assembly Definition list
u project assemblies ./MyUnityProject

# JSON output
u --json project info ./MyUnityProject
```

### Basic Operations (via Relay Server)

```bash
# Check editor state
u state

# Play Mode control
u play
u stop
u pause

# Console logs
u console get                  # All logs (plain text)
u console get --json           # All logs (JSON format)
u console get -s               # All logs with stack traces
u console get -l W             # Warning and above (warning, error, exception)
u console get -l E             # Error and above (error, exception)
u console get -l +W            # Warning only
u console get -l +E+X          # Error and exception only
u console get | head -20       # Last 20 entries
u console get | grep "error"   # Filter by text
u console clear                # Clear console

# Asset refresh
u refresh

# Editor selection
u selection

# Screenshot (capture is default, --burst for burst mode)
u screenshot                           # GameView (default)
u screenshot -s scene                  # SceneView
u screenshot -s camera                 # Camera.Render
u screenshot -p ./output.png           # Custom path
u screenshot --super-size 2            # 2x resolution (game only)
u screenshot -s camera -c "Main Camera" -W 1920 -H 1080
u screenshot --burst -n 10             # Burst: 10 frames
u screenshot --burst -n 5 -f jpg -q 80 # Burst with format/quality

# Pipe-friendly: outputs path only when piped
u screenshot -s game | mcat -i   # Inline display in terminal
u screenshot -s game | pbcopy    # Copy path to clipboard
u screenshot -s game | xargs open  # Open with default viewer
```

### Instance Management

```bash
# List connected instances
u instances

# Specify target instance
u --instance /Users/dev/MyGame state
u --instance /Users/dev/Demo play
```

### Test Execution

```bash
# EditMode tests
u tests run edit

# PlayMode tests
u tests run play

# Filtering
u tests run edit --test-names "MyTests.SampleTest"
u tests run edit --group-pattern ".*Integration.*"
u tests run edit --categories "Unit" "Integration"
u tests run edit --assemblies "MyGame.Tests"

# Fire and forget
u tests run edit --no-wait

# List available tests
u tests list edit
u tests list play

# Check running test status
u tests status
```

### Scene Operations

```bash
# Active scene info
u scene active

# Hierarchy
u scene hierarchy                    # Root only (depth 1)
u scene hierarchy --depth 2          # Up to 2 levels
u scene hierarchy --page-size 100    # Custom page size

# Scene operations
u scene load --name MainScene
u scene load --path "Assets/Scenes/Sub.unity" --additive
u scene save
u scene save --path "Assets/Scenes/NewScene.unity"
```

### GameObject Operations

```bash
# Find
u gameobject find "Main Camera"
u gameobject find "Player" --iterate-all

# Create
u gameobject create --name "MyCube" --primitive Cube --position 0 1 0

# Modify
u gameobject modify --name "MyCube" --position 5 0 0 --rotation 0 45 0

# Delete
u gameobject delete --name "MyCube"
```

### Component Operations

```bash
# List components
u component list -t "Main Camera"

# Inspect component
u component inspect -t "Main Camera" -T Camera

# Add component
u component add -t "Player" -T Rigidbody

# Remove component
u component remove -t "Player" -T Rigidbody
```

### Menu / ContextMenu

```bash
# Execute menu
u menu exec "Edit/Play"
u menu exec "Assets/Refresh"
u menu exec "Window/General/Console"

# List menus
u menu list                    # All menus
u menu list -f "Assets"        # Filter
u menu list -f "Play" -l 20    # Limit count

# Execute ContextMenu (scene objects)
u menu context "Reset" -t "/Player"

# Execute ContextMenu (ScriptableObject)
u menu context "DoSomething" -t "Assets/Data/Config.asset"

# Execute ContextMenu (Prefab)
u menu context "Initialize" -t "Assets/Prefabs/Enemy.prefab"
```

### Asset Operations

```bash
# Create Prefab
u asset prefab -s "Player" -p "Assets/Prefabs/Player.prefab"

# Create ScriptableObject
u asset scriptable-object -T "GameConfig" -p "Assets/Data/Config.asset"

# Asset info
u asset info "Assets/Data/Config.asset"
```

### UI Toolkit Tree Inspection

Inspect and interact with UI Toolkit VisualElement trees. Uses ref IDs for element targeting.

```bash
# List panels / dump tree
u uitree dump
u uitree dump -p "PanelSettings" --json

# Query elements (AND conditions)
u uitree query -p "PanelSettings" -c "action-btn"

# Inspect
u uitree inspect ref_3 --style --children

# Interact
u uitree click -p "PanelSettings" -n "BtnStart"
u uitree text -p "PanelSettings" -n "ScoreLabel"
u uitree scroll -p "PanelSettings" -n "ScrollView" --y 500

# Monkey test (random interactions + error monitoring)
u uitree monkey -p "PanelSettings" -c "action-btn" --count 50 --seed 42

# Structural snapshots (save/diff/list/delete)
u uitree snapshot save -p "PanelSettings" --name baseline
u uitree snapshot diff -p "PanelSettings" --name baseline
```

### Dynamic API Invocation

Call any Unity public static method via reflection. 5,243+ methods available.

```bash
# Search methods
u api schema --type AssetDatabase
u api schema --namespace UnityEditor --limit 20

# Call methods
u api call UnityEngine.Application get_unityVersion
u api call UnityEditor.AssetDatabase Refresh
u api call UnityEditor.EditorApplication ExecuteMenuItem --params '["Window/General/Console"]'

# Offline schema (cached per Unity version)
u api schema --offline --type PlayerSettings
```

### Frame Recording

```bash
# Start recording (camera-based, configurable FPS/format/resolution)
u recorder start --fps 30 -f jpg -q 80
u recorder start --fps 60 -W 1920 -H 1080 -o ./frames

# Stop recording and get results
u recorder stop

# Check recording status
u recorder status
```

### Configuration

```bash
# Show current configuration
u config show

# Generate default .unity-cli.toml
u config init
u config init -o ./custom-config.toml
u config init --force                  # Overwrite existing
```

## Options

### Common Options

| Option | Description | Default |
|--------|-------------|---------|
| `--relay-host` | Relay Server host | 127.0.0.1 |
| `--relay-port` | Relay Server port | 6500 |
| `--instance`, `-i` | Target Unity instance | default |
| `--timeout`, `-t` | Timeout (seconds) | 10.0 |
| `--json`, `-j` | Output JSON format | false |
| `--quiet`, `-q` | Suppress success messages | false |
| `--verbose` | Show request/response on stderr | false |

### Tests Options

| Option | Description |
|--------|-------------|
| `--test-names`, `-n` | Test names (exact match) |
| `--group-pattern`, `-g` | Regex pattern for test names |
| `--categories`, `-c` | NUnit categories |
| `--assemblies`, `-a` | Assembly names |
| `--no-wait` | Return immediately without waiting for results |

### Scene Hierarchy Options

| Option | Description | Default |
|--------|-------------|---------|
| `--depth`, `-d` | Hierarchy depth | 1 (root only) |
| `--page-size` | Page size | 50 |
| `--cursor` | Pagination cursor | 0 |

## Exit Codes

| Code | Name | Description |
|------|------|-------------|
| 0 | SUCCESS | Command completed successfully |
| 1 | USAGE_ERROR | Invalid arguments or validation failure |
| 2 | TRANSIENT_ERROR | Retryable: instance reloading, busy, timeout |
| 3 | CONNECTION_ERROR | Relay Server not running or unreachable |
| 4 | OPERATION_ERROR | Command failed (instance not found, protocol error, etc.) |
| 5 | TEST_FAILURE | Tests ran but some failed |

```bash
u state; echo $?              # 0 = connected, 3 = relay not running
u tests run edit; echo $?     # 0 = all passed, 5 = some failed
u play --quiet 2>/dev/null; echo $?  # Suppress output, check exit code only
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `UNITY_CLI_QUIET` | Set to `1` to suppress success messages |
| `UNITY_CLI_VERBOSE` | Set to `1` to log request/response to stderr |
| `UNITY_CLI_JSON` | Set to `1` for JSON output by default |
| `UNITY_CLI_NO_PRETTY` | Set to `1` to disable Rich formatting |
| `NO_COLOR` | Set to disable colors (standard) |

## AI Agent Skills

Workflow skills for AI coding agents (Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, Windsurf, etc.). Conforms to the [agentskills.io](https://agentskills.io/specification) spec.

### Option 1: GitHub CLI (recommended, gh 2.90.0+)

```bash
# Interactive: pick skills from a list
gh skill install bigdra50/unity-cli

# Install a single skill
gh skill install bigdra50/unity-cli unity-verify

# Install all skills at once (Claude Code, user scope)
for s in unity-shared unity-verify unity-debug unity-build \
         unity-scene unity-asset unity-perf unity-ui unity-api; do
  gh skill install bigdra50/unity-cli "$s" --agent claude-code --scope user
done

# Pin to a specific release
gh skill install bigdra50/unity-cli unity-verify --pin v3.11.0
```

Supports 40+ agents via `--agent` (claude-code, github-copilot, cursor, codex, gemini-cli, ...). Default scope is `project`; use `--scope user` for global install.

### Option 2: Skills CLI (cross-agent, no gh required)

```bash
# Install all skills (project-local)
npx skills add github:bigdra50/unity-cli

# Install globally (user-level)
npx skills add github:bigdra50/unity-cli -g

# Install specific skills only
npx skills add github:bigdra50/unity-cli -s unity-ui unity-api
```

See [Skills CLI](https://skills.sh/) for details.

### Option 3: Manual (git clone)

```bash
git clone https://github.com/bigdra50/unity-cli.git

# Single skill
cp -r unity-cli/skills/unity-verify ~/.claude/skills/

# All skills
cp -r unity-cli/skills/* ~/.claude/skills/
```

### Skills

| Skill | Description |
|-------|-------------|
| `unity-verify` | Compile & test validation (refresh → error check) |
| `unity-debug` | Error investigation |
| `unity-build` | Build pipeline |
| `unity-scene` | Scene construction |
| `unity-asset` | Asset & dependency management |
| `unity-perf` | Profiler analysis |
| `unity-ui` | UI testing (uitree + monkey + snapshot → PlayMode) |
| `unity-api` | Dynamic API invocation (5,243+ methods) |
| `unity-shared` | Common rules (loaded automatically by other skills) |

## Recipes

See [docs/recipes.md](docs/recipes.md) for piping, scripting, and tool composition examples.

```bash
u screenshot -s game | mcat -i         # Inline display in terminal
u console get -l E | head -10                  # Last 10 errors
u instances --json | jq -r '.[].instance_id'   # Extract paths
```

## Architecture

```mermaid
flowchart TB
    subgraph CLI["u (Python)"]
        direction TB
        RC[RelayConnection: TCP communication]
        EB[Exponential Backoff: 500ms → 8s]
        RID[request_id: idempotency guarantee]
    end

subgraph Relay["Relay Server (Python)"]
        direction TB
        IR[InstanceRegistry: multiple Unity management]
        Cache[RequestCache: idempotency cache]
        HB[Heartbeat: Single Outstanding PING]
        Q[Queue: FIFO max 10]
    end

subgraph Unity["UnityBridge (C#)"]
        direction TB
        Client[RelayClient: connection management]
        Dispatcher[CommandDispatcher: BridgeTool attribute]
        Reload[BridgeReloadHandler: reconnection]
    end

CLI -->|TCP:6500| Relay
    Relay -->|TCP:6500| Unity
```

## Protocol Specification

See [docs/protocol-spec.md](docs/protocol-spec.md) for details.

- Framing: 4-byte big-endian length + JSON
- State Machine: DISCONNECTED → READY → BUSY → RELOADING
- Heartbeat: 5s interval, 15s timeout (3 retries)
- Retry: Exponential Backoff (500ms → 8s, max 30s)

## Troubleshooting

```bash
# Check if Relay Server is running
lsof -i :6500            # macOS / Linux
netstat -ano | findstr :6500   # Windows

# Check connected instances
u instances

# Check Unity console for errors
u console get -l E
```

## v2.x → v3.0 Migration

| Change | v2.x | v3.0 |
|--------|------|------|
| Command name | `unity-mcp` | `unity-cli` |
| Connection target | Unity direct (6400) | Relay Server (6500) |
| Protocol | 8-byte framing | 4-byte framing |
| Multiple instances | Not supported | Supported |

```bash
# v2.x
unity-mcp --port 6400 state

# v3.0
u state  # Via Relay
u --instance /path/to/project state  # Specific instance
```

## License

MIT License

unity-cli

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README