unity-cli

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

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