{"id":39872373,"url":"https://github.com/bigdra50/unity-cli","last_synced_at":"2026-02-22T13:30:25.578Z","repository":{"id":326582083,"uuid":"1106218776","full_name":"bigdra50/unity-cli","owner":"bigdra50","description":"CLI tool for controlling Unity Editor via command line - Play Mode, console logs, tests, scenes, GameObjects and more","archived":false,"fork":false,"pushed_at":"2026-02-13T00:33:21.000Z","size":896,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-13T09:50:29.492Z","etag":null,"topics":["cli","developer-tools","python","unity","unity3d"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bigdra50.png","metadata":{"files":{"readme":"README.jp.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-28T20:39:07.000Z","updated_at":"2026-02-13T00:33:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bigdra50/unity-cli","commit_stats":null,"previous_names":["bigdra50/unity-mcp-client","bigdra50/unity-cli"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/bigdra50/unity-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigdra50%2Funity-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigdra50%2Funity-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigdra50%2Funity-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigdra50%2Funity-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigdra50","download_url":"https://codeload.github.com/bigdra50/unity-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigdra50%2Funity-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29567616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T00:47:08.760Z","status":"online","status_checked_at":"2026-02-18T02:00:09.468Z","response_time":162,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","python","unity","unity3d"],"created_at":"2026-01-18T14:18:27.410Z","updated_at":"2026-02-22T13:30:25.565Z","avatar_url":"https://github.com/bigdra50.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unity CLI\n\n[![CI](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml)\n[![Complexity](https://img.shields.io/badge/complexity-A%2FB-brightgreen)](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml)\n[![Maintainability](https://img.shields.io/badge/maintainability-A-brightgreen)](https://github.com/bigdra50/unity-cli/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)\n[![Unity](https://img.shields.io/badge/Unity-2022.3%2B-black?logo=unity)](https://unity.com/)\n[![openupm](https://img.shields.io/npm/v/com.bigdra50.unity-bridge?label=openupm\u0026registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.bigdra50.unity-bridge/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bigdra50/unity-cli)\n\n[English](README.md)\n\nコマンドラインから Unity Editor を操作する CLI ツール。\n\n## 概要\n\nPlay Mode 制御、コンソールログ取得、テスト実行、シーン/GameObject 操作など、Unity Editor の主要機能を CLI から実行できます。\n\n```bash\n# Play Mode 制御\nu play\nu stop\n\n# コンソールログ取得（エラー以上）\nu console get -l E\n\n# メニュー実行\nu menu exec \"Assets/Refresh\"\n\n# ContextMenu 実行\nu menu context \"DoSomething\" -t \"/Player\"\n```\n\n主な特徴:\n- Unity Editor の主要操作を CLI で実行\n- MenuItem / ContextMenu の実行に対応\n- 複数 Unity インスタンスの同時制御\n- ドメインリロード耐性（自動再接続）\n- UI Toolkit VisualElementツリーの検査（dump, query, inspect + ref ID方式）\n- プロジェクトを適切なバージョンで開く（Unity Hub連携）\n- プロジェクト情報取得（Relay Server不要）\n\n## 動作要件\n\n- [uv](https://docs.astral.sh/uv/) (Python パッケージマネージャー)\n- Python 3.11+\n- Unity 2022.3+\n- Unity Hub（`open`/`editor`コマンド使用時）\n\n## クイックスタート\n\n### 1. Unity側セットアップ\n\nUnityプロジェクトにUnityBridgeパッケージを追加:\n\n```bash\n# OpenUPM経由（推奨）\nopenupm add com.bigdra50.unity-bridge\n\n# または git URL で追加\n# Window \u003e Package Manager \u003e + \u003e Add package from git URL...\n# https://github.com/bigdra50/unity-cli.git?path=UnityBridge\n```\n\n### 2. 接続\n\nUnity Editorで `Window \u003e Unity Bridge` を開き:\n1. Start Server をクリック（Relay Server起動）\n2. Connect をクリック（Unity → Relay接続）\n\nツールバー右側のインジケータで接続状態を確認でき、クリックで接続/切断をトグルできます。\n\n### 3. CLIで操作\n\n```bash\n# uvx で直接実行（インストール不要）\nuvx --from git+https://github.com/bigdra50/unity-cli u state\n\n# Play Mode制御\nuvx --from git+https://github.com/bigdra50/unity-cli u play\nuvx --from git+https://github.com/bigdra50/unity-cli u stop\n\n# コンソールログ取得（エラー以上）\nuvx --from git+https://github.com/bigdra50/unity-cli u console get -l E\n```\n\n## インストール\n\n```bash\n# グローバルインストール\nuv tool install git+https://github.com/bigdra50/unity-cli\n\n# インタラクティブUI付き（エディタ選択プロンプト）\nuv tool install \"git+https://github.com/bigdra50/unity-cli[interactive]\"\n\n# CLIコマンド（すべてのエイリアスが同じ動作）\nunity-cli state    # フルネーム\nunity state        # 短縮形\nu state            # 最短形\n\nu play\nu console get -l E | head -10  # 最新10件のエラー以上\n\n# Relay Server 単体起動\nunity-relay --port 6500\n```\n\n## CLI コマンド\n\n### バージョン\n\n```bash\nu version                     # CLIバージョンを表示\n```\n\n### シェル補完\n\n```bash\n# Zsh\nu completion -s zsh \u003e ~/.zsh/completions/_unity-cli\n\n# Bash\nu completion -s bash \u003e\u003e ~/.bashrc\n\n# Fish\nu completion -s fish \u003e ~/.config/fish/completions/unity-cli.fish\n```\n\n### プロジェクトを開く\n\n```bash\n# プロジェクトを適切なバージョンで開く（ProjectVersion.txt参照）\nu open ./MyUnityProject\n\n# エディタバージョンを指定\nu open ./MyUnityProject --editor 2022.3.10f1\n\n# 非インタラクティブモード（CI/スクリプト向け）\nu open ./MyUnityProject --non-interactive\n\n# 終了まで待機\nu open ./MyUnityProject --wait\n```\n\n### エディタ管理\n\n```bash\n# インストール済みエディタ一覧\nu editor list\n\n# エディタインストール\nu editor install 2022.3.10f1\n\n# モジュール付きでインストール\nu editor install 2022.3.10f1 --modules android ios webgl\n\n# 非リリース版をchangeset指定でインストール\nu editor install 6000.1.0a1 --changeset abc123\n```\n\n### プロジェクト情報（Relay Server不要）\n\n```bash\n# プロジェクト全情報\nu project info ./MyUnityProject\n\n# Unityバージョンのみ\nu project version ./MyUnityProject\n\n# パッケージ一覧\nu project packages ./MyUnityProject\nu project packages ./MyUnityProject --include-modules  # 組み込みモジュールも含める\n\n# タグ・レイヤー\nu project tags ./MyUnityProject\n\n# 品質設定\nu project quality ./MyUnityProject\n\n# Assembly Definition一覧\nu project assemblies ./MyUnityProject\n\n# JSON出力\nu --json project info ./MyUnityProject\n```\n\n### 基本操作（Relay Server経由）\n\n```bash\n# エディタ状態確認\nu state\n\n# Play Mode制御\nu play\nu stop\nu pause\n\n# コンソールログ\nu console get                  # 全件（プレーンテキスト）\nu console get --json           # 全件（JSON形式）\nu console get -s               # スタックトレース付き\nu console get -l W             # warning以上（warning, error, exception）\nu console get -l E             # error以上（error, exception）\nu console get -l +W            # warningのみ\nu console get -l +E+X          # errorとexceptionのみ\nu console get | head -20       # 最新20件\nu console get | grep \"error\"   # テキストでフィルタ\nu console clear                # コンソールクリア\n\n# アセットリフレッシュ\nu refresh\n\n# エディタ選択状態\nu selection\n\n# スクリーンショット（デフォルトは capture、--burst で burst モード）\nu screenshot                           # GameView（デフォルト）\nu screenshot -s scene                  # SceneView\nu screenshot -s camera                 # Camera.Render\nu screenshot -p ./output.png           # 出力パス指定\nu screenshot --super-size 2            # 2倍解像度（game only）\nu screenshot -s camera -c \"Main Camera\" -W 1920 -H 1080\nu screenshot --burst -n 10             # Burst: 10フレーム連続撮影\nu screenshot --burst -n 5 -f jpg -q 80 # Burst + フォーマット/品質指定\n\n# パイプ時はパスのみ出力\nu screenshot -s game | mcat -i   # ターミナルにインライン表示\nu screenshot -s game | pbcopy    # パスをクリップボードにコピー\nu screenshot -s game | xargs open  # デフォルトビューアで開く\n```\n\n### インスタンス管理\n\n```bash\n# 接続中インスタンス一覧\nu instances\n\n# 特定インスタンスを指定\nu --instance /Users/dev/MyGame state\nu --instance /Users/dev/Demo play\n```\n\n### テスト実行\n\n```bash\n# EditModeテスト\nu tests run edit\n\n# PlayModeテスト\nu tests run play\n\n# フィルタリング\nu tests run edit --test-names \"MyTests.SampleTest\"\nu tests run edit --group-pattern \".*Integration.*\"\nu tests run edit --categories \"Unit\" \"Integration\"\nu tests run edit --assemblies \"MyGame.Tests\"\n\n# 結果を待たず即時リターン\nu tests run edit --no-wait\n\n# テスト一覧\nu tests list edit\nu tests list play\n\n# 実行中テストのステータス確認\nu tests status\n```\n\n### シーン操作\n\n```bash\n# アクティブシーン情報\nu scene active\n\n# 階層取得\nu scene hierarchy                    # ルートのみ（depth 1）\nu scene hierarchy --depth 2          # 2階層まで\nu scene hierarchy --page-size 100    # ページサイズ指定\n\n# シーン操作\nu scene load --name MainScene\nu scene load --path \"Assets/Scenes/Sub.unity\" --additive\nu scene save\nu scene save --path \"Assets/Scenes/NewScene.unity\"\n```\n\n### GameObject操作\n\n```bash\n# 検索\nu gameobject find \"Main Camera\"\nu gameobject find \"Player\" --iterate-all\n\n# 作成\nu gameobject create --name \"MyCube\" --primitive Cube --position 0 1 0\n\n# 変更\nu gameobject modify --name \"MyCube\" --position 5 0 0 --rotation 0 45 0\n\n# 削除\nu gameobject delete --name \"MyCube\"\n```\n\n### コンポーネント操作\n\n```bash\n# コンポーネント一覧\nu component list -t \"Main Camera\"\n\n# コンポーネント詳細\nu component inspect -t \"Main Camera\" -T Camera\n\n# コンポーネント追加\nu component add -t \"Player\" -T Rigidbody\n\n# コンポーネント削除\nu component remove -t \"Player\" -T Rigidbody\n```\n\n### メニュー/ContextMenu\n\n```bash\n# メニュー実行\nu menu exec \"Edit/Play\"\nu menu exec \"Assets/Refresh\"\nu menu exec \"Window/General/Console\"\n\n# メニュー一覧\nu menu list                    # 全メニュー\nu menu list -f \"Assets\"        # フィルタリング\nu menu list -f \"Play\" -l 20    # 件数制限\n\n# ContextMenu実行（シーン内オブジェクト）\nu menu context \"Reset\" -t \"/Player\"\n\n# ContextMenu実行（ScriptableObject）\nu menu context \"DoSomething\" -t \"Assets/Data/Config.asset\"\n\n# ContextMenu実行（Prefab）\nu menu context \"Initialize\" -t \"Assets/Prefabs/Enemy.prefab\"\n```\n\n### アセット操作\n\n```bash\n# Prefab作成\nu asset prefab -s \"Player\" -p \"Assets/Prefabs/Player.prefab\"\n\n# ScriptableObject作成\nu asset scriptable-object -T \"GameConfig\" -p \"Assets/Data/Config.asset\"\n\n# アセット情報\nu asset info \"Assets/Data/Config.asset\"\n```\n\n### UI Toolkit ツリー検査\n\nEditorパネルとRuntimeパネルのUI Toolkit VisualElementツリーを検査する。Playwright MCP風のref ID方式で、ツリーをダンプしてからref IDで個別要素を詳細取得するフローが可能。\n\n```bash\n# パネル一覧（Editor + Runtime）\nu uitree dump\n\n# 指定パネルのVisualElementツリーをダンプ\nu uitree dump -p \"Toolbar\"\n\n# 深度制限\nu uitree dump -p \"Toolbar\" -d 3\n\n# JSON出力\nu uitree dump -p \"Toolbar\" --json\n\n# type/name/USSクラスで検索（AND条件）\nu uitree query -p \"PanelSettings\" -t Button\nu uitree query -p \"PanelSettings\" -n \"StartBtn\"\nu uitree query -p \"PanelSettings\" -c \"primary-button\"\n\n# ref IDで要素詳細を取得（dump/query時に割り当て）\nu uitree inspect ref_3\n\n# resolvedStyle（レイアウト、色、フォント、マージン等）を含める\nu uitree inspect ref_3 --style\n\n# 直接の子要素情報を含める\nu uitree inspect ref_3 --children\n\n# パネル + 名前で指定（事前のdump不要）\nu uitree inspect -p \"Toolbar\" -n \"Play\"\n```\n\n### フレーム記録\n\n```bash\n# 記録開始（カメラベース、FPS/フォーマット/解像度を指定可能）\nu recorder start --fps 30 -f jpg -q 80\nu recorder start --fps 60 -W 1920 -H 1080 -o ./frames\n\n# 記録停止と結果取得\nu recorder stop\n\n# 記録ステータス確認\nu recorder status\n```\n\n### 設定\n\n```bash\n# 現在の設定を表示\nu config show\n\n# デフォルト .unity-cli.toml を生成\nu config init\nu config init -o ./custom-config.toml\nu config init --force                  # 既存を上書き\n```\n\n## オプション\n\n### 共通オプション\n\n| オプション | 説明 | デフォルト |\n|-----------|------|-----------|\n| `--relay-host` | Relay Serverホスト | 127.0.0.1 |\n| `--relay-port` | Relay Serverポート | 6500 |\n| `--instance`, `-i` | 対象Unityインスタンス | デフォルト |\n| `--timeout`, `-t` | タイムアウト（秒） | 10.0 |\n| `--json`, `-j` | JSON形式で出力 | false |\n| `--quiet`, `-q` | 成功メッセージを抑制 | false |\n| `--verbose` | リクエスト/レスポンスをstderrに出力 | false |\n\n### tests専用オプション\n\n| オプション | 説明 |\n|-----------|------|\n| `--test-names`, `-n` | テスト名（完全一致） |\n| `--group-pattern`, `-g` | テスト名の正規表現パターン |\n| `--categories`, `-c` | NUnitカテゴリ |\n| `--assemblies`, `-a` | アセンブリ名 |\n| `--no-wait` | 結果を待たず即時リターン |\n\n### scene hierarchy オプション\n\n| オプション | 説明 | デフォルト |\n|-----------|------|-----------|\n| `--depth`, `-d` | 階層の深さ | 1（ルートのみ） |\n| `--page-size` | ページサイズ | 50 |\n| `--cursor` | ページネーションカーソル | 0 |\n\n## 終了コード\n\n| コード | 名前 | 説明 |\n|--------|------|------|\n| 0 | SUCCESS | コマンド成功 |\n| 1 | USAGE_ERROR | 不正な引数、バリデーション失敗 |\n| 2 | TRANSIENT_ERROR | リトライ可能: リロード中、ビジー、タイムアウト |\n| 3 | CONNECTION_ERROR | Relay Server未起動・接続不可 |\n| 4 | OPERATION_ERROR | コマンド失敗（インスタンス未検出、プロトコルエラー等） |\n| 5 | TEST_FAILURE | テスト実行は完了したが一部失敗 |\n\n```bash\nu state; echo $?              # 0 = 接続中, 3 = relay未起動\nu tests run edit; echo $?     # 0 = 全通過, 5 = 一部失敗\nu play --quiet 2\u003e/dev/null; echo $?  # 出力抑制、終了コードのみ確認\n```\n\n## 環境変数\n\n| 変数 | 説明 |\n|------|------|\n| `UNITY_CLI_QUIET` | `1` で成功メッセージを抑制 |\n| `UNITY_CLI_VERBOSE` | `1` でリクエスト/レスポンスをstderrに出力 |\n| `UNITY_CLI_JSON` | `1` でデフォルトJSON出力 |\n| `UNITY_CLI_NO_PRETTY` | `1` でRich装飾を無効化 |\n| `NO_COLOR` | 設定でカラーを無効化（標準） |\n\n## Claude Code プラグイン（試験的）\n\nClaude Code を使った Unity 開発に unity-cli を組み込みやすくするための補助プラグインです。ルーティング、検証、デバッグなどのスキルを提供します。\n\n```bash\n# マーケットプレイスから追加\n/plugin marketplace add bigdra50/unity-cli\n\n# インストール\n/plugin install unity-cli@unity-tools\n```\n\n| スキル | 内容 |\n|-------|------|\n| `/unity-preflight` | コンパイル・テスト検証 |\n| `/unity-debug` | エラー調査 |\n| `/unity-build` | ビルドパイプライン |\n| `/unity-scene` | シーン構築 |\n| `/unity-asset` | アセット・依存関係管理 |\n| `/unity-perf` | プロファイラ分析 |\n| `/unity-ui` | UI Toolkit / uGUI 検査 |\n\n## Recipes\n\nパイプ、スクリプト、ツール連携の例は [docs/recipes.md](docs/recipes.md) を参照。\n\n```bash\nu screenshot -s game | mcat -i         # ターミナルにインライン表示\nu console get -l E | head -10                  # エラー直近10件\nu instances --json | jq -r '.[].instance_id'   # パス抽出\n```\n\n## アーキテクチャ\n\n```mermaid\nflowchart TB\n    subgraph CLI[\"u (Python)\"]\n        direction TB\n        RC[RelayConnection: TCP通信]\n        EB[Exponential Backoff: 500ms → 8s]\n        RID[request_id: 冪等性保証]\n    end\n\n    subgraph Relay[\"Relay Server (Python)\"]\n        direction TB\n        IR[InstanceRegistry: 複数Unity管理]\n        Cache[RequestCache: 冪等性キャッシュ]\n        HB[Heartbeat: Single Outstanding PING]\n        Q[Queue: FIFO max 10]\n    end\n\n    subgraph Unity[\"UnityBridge (C#)\"]\n        direction TB\n        Client[RelayClient: 接続管理]\n        Dispatcher[CommandDispatcher: BridgeTool属性]\n        Reload[BridgeReloadHandler: 再接続]\n    end\n\n    CLI --\u003e|TCP:6500| Relay\n    Relay --\u003e|TCP:6500| Unity\n```\n\n## プロトコル仕様\n\n詳細は [docs/protocol-spec.md](docs/protocol-spec.md) を参照。\n\n- Framing: 4-byte big-endian length + JSON\n- State Machine: DISCONNECTED → READY → BUSY → RELOADING\n- Heartbeat: 5秒間隔、15秒タイムアウト（3回リトライ）\n- Retry: Exponential Backoff（500ms → 8s、最大30秒）\n\n## トラブルシューティング\n\n```bash\n# Relay Serverが起動しているか確認\nlsof -i :6500\n\n# 接続中インスタンス確認\nu instances\n\n# Unityコンソールでエラー確認\nu console get -l E\n```\n\n## v2.x → v3.0 マイグレーション\n\n| 変更点 | v2.x | v3.0 |\n|--------|------|------|\n| コマンド名 | `unity-mcp` | `unity-cli` |\n| 接続先 | Unity直接 (6400) | Relay Server (6500) |\n| プロトコル | 8-byte framing | 4-byte framing |\n| 複数インスタンス | 非対応 | 対応 |\n\n```bash\n# v2.x\nunity-mcp --port 6400 state\n\n# v3.0\nu state  # Relay経由\nu --instance /path/to/project state  # 特定インスタンス\n```\n\n## ライセンス\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigdra50%2Funity-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigdra50%2Funity-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigdra50%2Funity-cli/lists"}