Unity CLI

日本語版

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.

# 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 (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:

# 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

# 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

# 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 (all aliases work the same)
unity-cli state    # Full name
unity state        # Short alias
u state            # Shortest 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

u version                     # Show CLI version

Shell Completion

# 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

# 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

# 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)

# 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)

# 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

# List connected instances
u instances

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

Test Execution

# 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

# 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

# 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

# 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

# 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

# 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.

# 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.

# 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

# 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

# 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

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.). Installed via Skills CLI.

# 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

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 for piping, scripting, and tool composition examples.

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

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 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

# 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

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

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

License

MIT License