unity-cli

Unity CLI

特定のバージョンを指定されていない限り、常に最新バージョンの Unity CLI を使用してください。 新しいリリースでは、これらのドキュメントに記載されているコマンドや出力フィールドが定期的に追加されます。そのため、古い CLI を使うと、ドキュメントが間違っているように見える問題が発生します。unity self-update --check --format json で確認してください。

コマンドを探す：ヘルプを grep するのではなく検索する

unity --help やグループのヘルプを grep で絞り込まないでください。 ヘルプは長く、そこから grep すると、一致箇所やその前後の文脈が抜け落ちます。CLI 独自の検索を使ってください。

unity commands --grep license                 # built-in commands, plugins and the connected Editor's Pipeline commands
unity command --query screenshot              # the same search

unity commands --grep <pattern> と unity command --query <term> は同じ検索機能です。CLI 組み込みコマンド、インストール済みかどうかを問わないプラグインカタログ、接続中の Editor の Pipeline コマンドを対象に、最も一致度の高いものから表示します。通常の単語は順不同で一致し、正規表現の文字を含めると正規表現として扱われます。各行には実行方法（invoke）が記載されます。例：unity projects link cloud、unity command create_gameobject、インストール済みプラグインの場合は unity <id>、未インストールのプラグインの場合は unity plugin install <id>。--format json では、各行に kind（command、plugin、pipeline）、path、description、matchedOn（name、description、option）も含まれるため、テーブルを解析するのではなく invoke に従って実行してください。

• 特定の Editor を検索するには unity command --query <term> に --project-path <project> を指定します。Player を検索するには --runtime <pattern> を指定します（例：unity command --query screenshot --runtime MyGame）。
• commands --grep は Editor の応答を最大 3 秒待ちます。command --query は応答があるまで待ちます。Editor を検索しなかった場合、最後の行にその理由（Editor がない、時間内に応答がない、複数の Editor がある）と実行すべきコマンドが表示されます。まず unity status --until-ready --project-path <project> で Editor の準備が整うまで待ってください。接続前に Pipeline の行が表示されなくても、何も存在しない証拠にはなりません。

フィールドとフラグ：integration-advanced.md。

起動中の Unity Editor を操作する（開いている場合）

このマシンで Unity Editor が開いていれば、この CLI でリアルタイムに操作できます。プロジェクトの Pipeline パッケージ（com.unity.pipeline）を通じて、GameObject の作成や変更、シーンやアセットの編集、ヒエラルキーの確認、任意の C# の実行が可能です。すべてローカルマシン上で、現在のユーザーアカウントを使い、開いている Editor を対象に実行されます。リモートアクセスではなく、ターミナルですでに持っている以上の権限を与えるものでもありません。Editor が利用できる場合は、シーンやアセットのファイルを手動で編集するのではなく、Editor を操作してください。

unity status                    # confirm a connected Editor (look for state "ready")
unity command                   # list the commands the Editor exposes
unity command editor.playmode start   # run one — e.g. enter Play mode
# Run arbitrary C# — e.g. add a GameObject named "Joe" — when the Editor exposes script eval:
unity command script eval 'new UnityEngine.GameObject("Joe");'

シーンを編集するだけでなく、実行中のゲームを検証しますか？ Play モードに入ることは準備であり、検証ではありません。 Editor のフォーカスが外れていたり、デスクトップがロックされていたりすると、unity status が再生中と報告していてもフレーム 1 で停止することがあります。また、スクリーンショットには動いているように見える静止フレームや、単色の画面がレンダリングされる場合があります。ゲームが実際に進行していることの確認、画面のキャプチャ、コンソールの読み取り、script eval を使ったリアルタイム調整までを順に行う手順は、 playmode-verification-loop.md にあります。

複数の Editor が開いていますか？ --project-path を指定してください

Editor を操作するコマンドには、すべて --project-path <path> を指定できます。複数の Editor が起動している可能性がある場合は、必ず指定してください。 指定しない場合、CLI は現在のディレクトリを含むプロジェクトの Editor を対象とするため、対象はシェルの cwd に応じて変わります。

unity command editor.playmode start --project-path /path/to/MyProject

複数の Editor が同じプロジェクトを共有している場合（worktree、複製したプロジェクト、Multiplayer Play Mode のプレイヤーなど）に対象を固定するには、unity command、list、job、mcp で --port <number>、--pid <number>、または --instance <name>（MPPM インスタンス名または vpId）も指定できます。該当する起動中の Editor がない状態で固定先を指定すると、終了コード 12 と EDITOR_NOT_RUNNING が返されます。unity status のインスタンスにある project フィールドが、--project-path に指定する値です。unity command／list／job／mcp で、該当する起動中のプロジェクトがない場合は、候補を一覧表示して AMBIGUOUS_EDITOR エラーになります。詳細。 複数のワークツリーやエージェントセッションで作業していますか？ ワークツリーごとに Editor を 1 つ使用してください。 unity vcs git worktree add <branch> --into <path> で各ワークツリーを作成すると、配置先を選べます。--into は省略可能です。--format json は実際のワークツリーとプロジェクトのパスを報告し、人間向けの出力でホームディレクトリのパスに含まれるアカウント名を伏せるのはその出力だけです。Unity プロジェクトがリポジトリのルートにある場合、プロジェクトは <path> です。そうでない場合は <path>/<its folder> です。unity open <project> で、そのプロジェクト専用の Editor を開いてください。その後、Editor に到達するすべての呼び出しで、そのプロジェクトを必ず指定してください。--project-path <full project path> を渡すか、次のように変数を呼び出しの先頭に付けます：UNITY_PROJECT_PATH=<full project path> unity command editor status。ほとんどのエージェントツールはコマンドを毎回新しいシェルで実行するため、ある呼び出しでの export や変数の単独代入は、次の呼び出しには引き継がれません。unity open、status、command、list、job、mcp は、パスを指定しない場合にこの変数を読み取ります。recompile、close、mcp configure は読み取りません。これらにはパスを渡してください。変数がない場合、パスなしの unity open は現在のディレクトリのプロジェクトを開きますが、それはソースのチェックアウトのままです。unity status --until-ready --project-path <project> も含め、毎回同じフルパスでその Editor を指定してください。存在するパスを指定すると、そのプロジェクトだけが対象になります。一方、名前だけを指定すると、パスにその名前を含む兄弟プロジェクトも対象になります。自分のチェックアウト（またはその Multiplayer Play Mode クローン）ではないプロジェクトの Editor を操作しないでください。兄弟ワークツリーで開いている Editor も、あなたの Editor とまったく同じように、あらゆるコマンドに応答します。そこに送ったコマンドはそのチェックアウトのシーンを編集し、Play モード、再コンパイル、インポートもそのチェックアウトのコードに対して実行されます。自分の Editor が開いていない場合は、開いてください。終了してしまった場合は、実行中の Editor を借りずに、そのことをユーザーに伝えてください。

プロジェクトに com.unity.pipeline パッケージが必要です（Unity 6.0 以降）。unity pipeline install で一度追加してください。ヘッドレス Editor を起動して操作する方法、unity list によるツールの検出方法、カスタム [CliCommand] ツールの作成方法など、詳細は integration-advanced.md をご覧ください。

このパッケージには、さらに詳しい unity-pipeline エージェントスキルも含まれています。これは Library/PackageCache 内にあり、クライアントからは見えません。このスキルを含むプロジェクトで、unity skill install <client> --local を一度実行すると、このスキルの隣にコピーされます。

接続できない、またはコマンドがタイムアウトしますか？ まず Safe Mode かどうかを確認してください。 プロジェクトに C# のコンパイルエラーがあると、Editor は Safe Mode で起動します。このモードでは Pipeline パッケージが読み込まれないため、unity command、unity list、unity recompile はまったく接続できません（unity status は Editor のログを読み取って Safe Mode を報告するため、この確認には接続しません）。特に unity recompile については、次の点に注意してください。これはすでに実行中の Editor に新たに発生させたエラーを報告しますが、コードに問題がある状態で起動した Editor はパッケージを読み込めないため、問い合わせ先がなく、エラーを報告せずに終了コード 7 で終了します。闇雲にファイルを編集するのではなく、unity status を実行してください（Safe Mode とコンパイルエラーの一覧が報告されます。--format json では safeMode.compileErrors に表示されます）。次にエラーを修正してください。コンパイルに成功すると、Editor は Safe Mode を終了します。復旧手順の全容については、integration-advanced.md → Safe Mode からの復旧（コンパイルエラーによる接続失敗）をご覧ください。

サンドボックス内でコーディングエージェントとして実行中で、unity status がインスタンスなしと報告しますか？ 制限の厳しいサンドボックスでは、実際に実行中の Editor がこの CLI から見えないことがあります。それだけを根拠に Editor が停止していると判断しないでください。詳しくは、integration-advanced.md → サンドボックス化されたエージェントツールによって実行中の Editor が見えなくなる場合をご覧ください。 呼び出しがタイムアウトした場合、または Editor のライフサイクルで問題が発生した場合は、ユーザーに伝えてください。黙って回避してはいけません。 まず、セーフモード、サンドボックス、Editor がまだインポート中または読み込み中である可能性を除外してください。--format json で errors[0].code を確認し、インポートに時間がかかる場合は --timeout を長めに設定してください。それでも次のいずれかに該当する場合は、報告してください。

• タイムアウトするコマンド
• unity status --until-ready の実行中に ready に到達しない Editor（終了コード 6）
• コマンドの実行中に切断される接続
• 実行中に終了または再起動する Editor
• Editor が起動しない unity open

ループで黙って再試行したり、別の Editor に切り替えたり、シーンやアセットのファイルを手作業で編集したりしてはいけません。実行した内容、発生した問題、すでに試したことを伝えてください。その後、unity bug --area pipeline-package（Editor 自体が終了した、または起動しなかった場合は --area editor）で報告することを提案し、まずユーザーに確認してください。unity bug はログを Unity に送信するため、自分の判断で実行してはいけません。

CLI をインストールする（未インストールの場合）

まず、CLI が利用可能か確認します。

which unity && unity --version

見つからない場合は、インストールします。

macOS / Linux

curl -fsSL https://unity.com/install.sh | bash

Windows（PowerShell）

irm https://unity.com/install.ps1 | iex

インストール後、新しいシェルを開いて unity が PATH に含まれていることを確認し、unity --version で検証します。インストールスクリプトが失敗する場合、またはバイナリが依然として見つからない場合は、ユーザーに伝えて処理を停止してください。コマンド自体が権限エラーまたはクラッシュで失敗する場合は、インストールが破損している可能性があります。インストールスクリプトを再実行するよう提案してください。

---

グローバルフラグ

以下はすべてのコマンドで使用できます。

フラグ	説明
--format <fmt>	出力形式：human（デフォルト）、json、tsv、ndjson、github。UNITY_FORMAT 環境変数でも指定できます。
--json	--format json のグローバルな省略形で、すべてのコマンドで使用できます（例：unity status --json、unity doctor --json）。別の --format（例：--json --format tsv）と併用すると、使用方法エラー（終了コード 2）になります。--json は UNITY_FORMAT より優先されます。
--no-banner	ブランドヘッダーを非表示にします。スクリプトで使用します。
--no-header	tsv テーブルのヘッダー行を省略します。ヘッダー行は列名で、json の各行で使用されるキー（version、upgradeTo など）と同じです。tsv の結果が空の場合はヘッダー行のみになるため、--no-header を指定すると何も出力されません。
--no-pager	ページ送りを無効にします。長い一覧（unity command、releases、editors、changelog、logs）で使用される外部ページャーと、unity projects list の対話型ページャーの両方に適用されます。UNITY_NO_PAGER でも指定できます（値の有無で判定されるため、0 を含む任意の値で無効になります）。
--non-interactive	すべての対話型プロンプトを無効にします。CI で使用します。
--quiet	human および tsv 出力で通知、警告、進行状況を非表示にします。エラーと終了コードはそのままです。json 出力は変わらず、ndjson 出力も同様ですが、一部の一覧では行が省略されます（Notes を参照）。
--verbose	失敗時にエラーの詳細（スタックトレースと原因チェーン）をすべて出力します。UNITY_VERBOSE でも指定できます。
--proxy <url>	この呼び出しで使用する HTTP/HTTPS/SOCKS/PAC プロキシ URL です。UNITY_PROXY でも指定できます。標準の HTTPS_PROXY／HTTP_PROXY／ALL_PROXY 環境変数、および永続化された proxy.json の設定より優先されます。
--proxy-disable	環境変数、永続化された設定、システム設定を含むすべてのプロキシ設定を無視し、この呼び出しでプロキシを無効にします。
--log-proxy	外向きリクエストごとに、秘匿情報を伏せたエントリーを proxy-request.json に記録します。プロキシの問題を再現するために使用します。UNITY_LOG_PROXY=1 または proxyRequestLogging 設定でも指定できます。
--no-log-proxy	プロキシリクエストのログ記録がグローバルに有効な場合に、1 回の呼び出しだけ記録を無効にします。
--color <auto|always|never>	この呼び出しでの色付き出力を制御し、NO_COLOR／FORCE_COLOR および TTY の自動検出より優先します。human 出力だけでなく、ANSI を出力するすべての箇所（ヘルプ、テーブル、スピナー、エラー）に適用されます。
--no-color	--color never の省略形です。--color／--no-color のうち、コマンドラインで後に指定した方が有効になります。

出力をプログラムで解析する場合は、必ず --format json を使用してください。 代わりに tsv を読み取る場合は、列を位置ではなくヘッダー名で選択してください。コマンドの tsv 列は名前と順序が維持され、情報を追加するフラグ（editors --long など）は列を末尾に追加するだけです。tsv の失敗メッセージは stderr に出力されるため、stdout にはデータのみが含まれます。

--accelerator <host:port> と --no-accelerator はルートのグローバルフラグではありません。run、test、build でのみ、コマンド名の後に指定できます。build-run-test.md を参照してください。

プロセス内でページ送りを行うコマンドは unity projects list だけです。 1 画面に 10 件のプロジェクトを表示し、stdout がターミナルの場合に限り、画面ごとにキー入力を待ちます。stdout がリダイレクトされている場合、--format json または --format ndjson を指定した場合、--all、--watch、または --no-pager／UNITY_NO_PAGER を指定した場合は、ページ送りされません。

ただし、すべての機械処理向け形式でページ送りが回避されるわけではありません。 独自の非対話型レンダリングを行うのは json と ndjson だけです。ターミナルでは --format tsv と --format github は人間向けのテーブル表示にフォールバックし、human と同様にページ送りされます。そのため、TTY で --format tsv を指定しても、TSV 出力にもページ送りなしにもなりません。stdout をリダイレクトする（機械処理向け形式では通常この方法を使います）か、--no-pager を指定してください。なお、これは下記の外部ページャーと逆の動作です。外部ページャーは human 専用です。ここでは 2 つの仕組みの動作が異なり、意外な挙動をするのは projects list の方です。 長い一覧は、git log と同様に外部ページャーを介して表示されます。 unity command（引数なしの一覧）、unity releases、unity editors、unity changelog、unity logs は、ターミナル上で人間向けの出力を less -RFX に渡します。出力が1画面に収まる場合、-F によって自動的に終了します。$UNITY_PAGER、次に $PAGER を設定すると選択内容を上書きでき、シェル経由で実行されるため、PAGER="less -S" のように指定できます。空の値は無効化の指定として扱われず、無視されます。projects list のページャーとは異なり、こちらは**human の場合に限って**使用されます。また、stdout がリダイレクトされている場合、マシン向けの形式（json、tsv、ndjson、github）の場合、--quiet、TERM=dumb、ストリーミングモード（editors --watch、logs --follow）の場合、unity command <name> のように名前が指定されている場合、または unity shell 内では使用されません。ページャーに問題がある場合、ページ送りができなくなるだけで、出力は失われません。存在しないものを指定した $PAGER は、何かが起動する前に判明します。起動後に終了した場合は、ページャーの終了ステータスに基づいて出力がターミナルに再表示されます（正常終了は通常の q として扱われ、出力は破棄されます。異常終了の場合は再表示されます）。読み込みを行わずに終了ステータス 0 を返すページャー（PAGER=true）は、q と区別できないため、出力は失われます。ただし、単に待機するページャーは問題ではありません。CLI はページャーとともに待機します。

ブランド化された Unity ヘッダー（ロゴ、ワードマーク、CLI バージョン）は、起動時に表示される画面、すなわち unity、unity --help / -h、unity help と、初回実行時の同意プロンプトの上に表示されます。TTY 上でのみ表示され、表示は最大1回です。狭いターミナル、Unicode が使えない環境、または NO_COLOR が設定されている場合は、コンパクトな色なしテキストに切り替わります。パイプに渡される出力には影響しません。スクリプトで表示を抑制するには --no-banner を使用してください。引数なしの unity は使い方を表示して、終了コード 0 で終了します。

環境変数

CLI の環境変数にはすべて UNITY_ プレフィックスが付きます。CLI フラグは常に、対応する環境変数より優先されます。

変数	対応するフラグ	説明
UNITY_FORMAT	--format	出力形式（human、json、tsv、ndjson、github）。HUB_FORMAT は非推奨のエイリアスです。
UNITY_EDITOR_VERSION	--editor-version	エディターバージョン（例：2023.3.0f1、latest、lts）。
UNITY_ARCHITECTURE	--architecture	チップアーキテクチャ（x86_64、arm64）。
UNITY_PROJECT_PATH	パス引数	パスが指定されていない場合のプロジェクトパスです。open（および projects open）、エディターに接続するコマンド status、command、list、job、mcp、さらに pipeline install／upgrade と collaboration コマンドで使用されます。recompile、close（および projects close）、mcp configure では読み込まれません。
UNITY_QUIET	--quiet	必須ではない出力を抑制します。
UNITY_VERBOSE	--verbose	失敗時にエラーの詳細をすべて表示します。
UNITY_NON_INTERACTIVE	--non-interactive	対話型プロンプトを無効にします。
UNITY_NO_BANNER	--no-banner	ブランドバナーを抑制します。
UNITY_NO_PAGER	--no-pager	ページ送りを無効にします。長い一覧に使用する外部ページャーと、unity projects list の対話型ページャーの両方が対象です。値の有無で判定されるため、0 を含む任意の値が有効です。
UNITY_PAGER	—	長い一覧に使用するページャーです。$PAGER と既定値の less -RFX より優先されます。シェル経由で実行されるため、フラグを使用できます（less -S）。空の値は無視され、無効化にはなりません。
PAGER	—	UNITY_PAGER と同じですが、そちらが未設定または空の場合にのみ参照されます。
LESS / LV / LESSCHARSET / MORE	—	これらを設定していない場合に限り、ページャーに渡されます。既定値はそれぞれ FRX、-c、utf-8、FRX です。LESSCHARSET は、ロケールで UTF-8 が宣言されていない場合でもマルチバイト文字を読みやすくします。macOS／BSD の more は別名で less であり、$MORE を読み取るため、MORE がないと PAGER=more は1行だけでもキー入力を待つことになります。
UNITY_RUN_TIMEOUT	--timeout	unity run のタイムアウト（秒）です。
UNITY_TEST_TIMEOUT	--timeout	unity test のタイムアウト（秒）です。
UNITY_CLOUD_ORG	--cloud-org	単一の呼び出しで使用する、アクティブな Unity Cloud 組織の ID または名前です。
UNITY_CLOUD_PROJECT	--cloud-project	Cloud プロジェクトの ID または名前です（サービスアカウントには ID が必要です）。Cloud Build のインベントリで使用されます。Pipeline Automation のインベントリは組織単位です。
UNITY_NO_CLOUD	--no-cloud	projects create と projects upgrade で Unity Cloud へのリンクを拒否します。値の有無で判定されるため、0 を含む任意の値が有効です。projects create と projects upgrade では、明示的に指定した --cloud、--cloud-project、--cloud-org、--coppa が優先されます。この変数が設定されている場合、それらのフラグで上書きしない限り、projects create --vcs uvcs は拒否されます。
UNITY_SERVICE_ACCOUNT_ID	—	非対話型（CI）認証に使用するサービスアカウントのクライアント ID です。
UNITY_SERVICE_ACCOUNT_SECRET	—	非対話型（CI）認証に使用するサービスアカウントのクライアントシークレットです。
UNITY_PROXY	--proxy	HTTP／HTTPS／SOCKS／PAC プロキシ URL です。HTTPS_PROXY／HTTP_PROXY／ALL_PROXY と、保存済みの proxy.json 設定より優先されます。
UNITY_NO_UPDATE_CHECK	—	バックグラウンドの「更新があります」チェックを無効にします（unity config update-check を参照）。
UNITY_NO_AGENT_HINTS	—	AI エージェントが unity を実行した際に、Unity のエージェントプラグインまたはスキルの使用を提案しないようにします。対象は、Claude Code のインストールプロンプト、unity setup codex／unity setup grok のヒント、unity skill install のヒント（--format json のエンベロープ内の notifications にある AGENT_PLUGIN_AVAILABLE エントリ）です。値の有無で判定されます。ヒントでは、コマンドを実行する前にユーザーの承認を得るよう求められます。
UNITY_NO_CONSENT_PROMPT	—	初回実行時に一度だけ表示される分析データの同意プロンプトを、選択を記録せずに抑制します。これは、対話型ターミナル上でプロンプトを決して受け取らないようにする必要があるラッパースクリプト向けです。unity analytics opt-in を実行するまで、分析データの収集はオフのままです。UNITY_NON_INTERACTIVE とは異なり、コマンドの動作にはそれ以外の変更を加えません。
UNITY_NO_CRASH_REPORT	—	匿名のクラッシュ／エラー報告（Sentry）を完全に無効にします。
UNITY_LOG_PROXY	--log-proxy	外部へのリクエストごとに、情報を伏せたエントリを proxy-request.json に1件記録します。真偽値として扱われる値：1、true。
UNITY_ACCELERATOR	--accelerator	Unity Accelerator のエンドポイント（host:port）です。保存済みの accelerator.json より優先されます。--accelerator が指定されている場合はそちらが優先されます。
UNITY_NO_ELEVATE	--no-elevate	Windows：install／install-modules で昇格（UAC）インストールヘルパーをスキップし、インストールサービスを非昇格で実行します。Windows でアカウントに管理者権限が必要な場合、エディターの NSIS インストーラーは引き続き必要に応じて昇格を求めます。管理者トークンでは常に求められ、標準ユーザーでは求められません。
UNITY_INSTALL_RETRIES	--retries（install-modules のみ）	転送または検証に失敗したエディターまたはモジュールのダウンロードを、install と install-modules が再試行する回数です。0 にすると再試行は無効になります。unity install には --retries フラグがないため、このコマンドでは変数を設定してください。
UNITY_NO_AUTH_BROKER	—	常駐の認証ブローカーをスキップし、OS のキーチェーンから認証情報を直接読み取ります。既定では、トークンを必要とするすべてのコマンドは、必要に応じて起動し、アイドル状態が2分続くと終了するブローカーを経由します（auth-license-cloud.md を参照）。
UNITY_CLI_HOME	—	すべてのプラットフォーム（Windows を含む）で、インストールスクリプトと unity self-install が使用するインストールルートです。バイナリは既定の場所ではなく、<UNITY_CLI_HOME>/bin に配置されます。
UNITY_NO_EDITOR_IDENTITY_SERVER	—	Hub が実行されていない場合に unity open が起動し、エディターのサインイン照会に応答するバックグラウンドの ID ヘルパーを無効にします（projects-templates.md を参照）。値の有無で判定されます。
UNITY_EXPERIMENTAL_FEX_EMU	なし	Linux arm64 のみ。実験的機能であり、サポート対象外です。FEX-Emu を使って x86_64 エディターを実行します。1、true、yes のいずれかで有効になり、FEX-Emu と x86_64 RootFS がインストールされている場合にのみ適用されます（unity doctor で確認できます）。FEX-Emu では C# スクリプトのコンパイル時にクラッシュすることが確認されています。editors-install.md を参照してください。
CI サービスアカウント認証： ブラウザーの OAuth フローをスキップするには、UNITY_SERVICE_ACCOUNT_ID と UNITY_SERVICE_ACCOUNT_SECRET の両方を設定します。これにより、シークレットがプロセスの引数リストやシェル履歴に残りません。これらは unity auth login の --client-id／--secret-from-stdin 入力に対応しますが、環境変数から認証情報を読み込むだけではログインは完了しません。対話型フローは実行されず、認証情報もキーチェーンに保存されません。

ヘルプの表示

任意の階層のコマンドやサブコマンドに -h または --help を追加できます。例：unity --help、unity projects create --help。

どのコマンドを使えばよいかわからない場合は、ヘルプを grep するのではなく、検索してください。unity --help と不明なコマンドのエラーの末尾にも、この案内が表示されます。各検索の最後には、検索対象から除外されたソースと、そのソースを検索するコマンドが示されます（JSON の data.hint）。何も見つからないと結論付ける前に、そのコマンドを実行してください。

終了コード

まず終了コードを確認し、次に JSON または NDJSON エンベロープ内の errors[0].code を確認してください。Retry は、同じコマンドを変更せずに再実行したときに成功する可能性があるかどうかを示します。unity commands --json には、この表が exitCodes として含まれており、各終了コードに対応するエラーコードも記載されています。6 は、より具体的なコードがないすべての失敗を表します。プロジェクトが見つからない場合、Editor が実行されていない場合、不明な Editor コマンドの場合、タイムアウトの場合には、それぞれ固有のコード（11～14）があります。

コード	名前	再試行	意味
0	SUCCESS	いいえ	コマンドが成功しました。
1	ERROR	いいえ	想定外またはサポートされていない状態です。
2	BAD_ARGS	いいえ	使用方法のエラーです。不明なコマンドやオプション、または不正な値が指定されています。
3	AUTH_ERROR	いいえ	サインインしていない、セッションの有効期限が切れている、または権限が拒否されました。
4	NEEDS_CONFIG	いいえ	必要なツール、設定、リンクなどのセットアップが不足しています。
6	COMMAND_FAILED	いいえ	より具体的なコードで示されない理由により、コマンドが失敗しました。
7	NETWORK_UNREACHABLE	はい	必要なサービスに接続できませんでした。
8	TESTS_FAILED	いいえ	テストが実行され、一部が失敗しました。
9	INSTALL_LOCKED	はい	別のプロセスがインストールロックを保持しています。
10	READY_TIMEOUT	はい	Editor が時間内に準備完了になりませんでした。
11	NOT_FOUND	いいえ	コマンドで指定されたものが存在しません。プロジェクト、リリース、モジュールなどが該当します。
12	EDITOR_UNREACHABLE	はい	実行中の Editor から応答がありません。実行中の Editor がない、一致する Editor がない、または接続が拒否された場合です。
13	REMOTE_COMMAND_FAILED	いいえ	Editor は応答しましたが、その名前のコマンドはありません。
14	TIMEOUT	はい	Editor リクエスト、HTTP リクエスト、バッチ実行などの処理がタイムアウトしました。
130	INTERRUPTED	はい	Ctrl-C（SIGINT）によって中断されました。
141	OUTPUT_CLOSED	いいえ	stdout の読み取り側がパイプを閉じました。
143	TERMINATED	はい	SIGTERM によって終了しました。

8 は unity test 専用です。テストは実行されましたが、一部が失敗しました。実行が完了しなかった場合は 6、タイムアウトした場合は 14 で終了するため、CI では再試行でき、失敗したテストをむやみに再実行することもありません。9 の場合、同じインストール内の先行する項目はすでに配置されている可能性があります（data.completedUids）。10 は unity open --until-ready 専用です。Editor は引き続き実行中です。

コマンド

各コマンドの構文、フラグ、使用例を含む完全なリファレンスは、references/ 以下のグループ別ファイルにあります。必要なコマンドグループのファイルをお読みください。上記のすべてのグローバルフラグ、環境変数、終了コードは、すべてのコマンドに適用されます。すべてのコマンドで -h / --help も使用できます（ヘルプの利用を参照）。

コマンド	リファレンスファイル
auth（login / logout / status / list / switch / default / consumers / revoke）、license（activate / return / server）、cloud（org / project）	auth-license-cloud.md
pipeline cloud-build（groups / builds / project / tooling などのターゲット）、pipeline automation（apps / pipelines / jobs / automations / bots / profiles / templates、および apps versions、pipelines versions、jobs stats）	cloud-automation.md
editors（list / running / add / default / path / install-path / info / upgrade / prune / verify / module）、install、uninstall、modules、install-modules、terms（accept / status）	editors-install.md
projects（list / create / new / clone / open / link / require / upgrade / export / import / pin / size / clean / exec。ヘルプには「ローカルの Unity プロジェクトを作成、開く、アップグレード、リンクする（Unity Cloud、GitHub/GitLab）」と表示されるため、フォルダーを Unity Cloud にリンクするには cloud ではなく projects link cloud を使用します）、open、close、releases、templates（list / info / create / pack / delete）、assets（inspect / export）	projects-templates.md
config（proxy / update-check / accelerator / get / set / list / unset / resolve）、context（save / use / list / current / delete）、hub install	config-hub.md
run、test、build（および build run）、recompile、watch（test）	build-run-test.md
logs、doctor、env、version、cache、ci init、analytics、changelog、docs（および toc）、language、completion、bug、self-update、self-uninstall、diagnose proxy、diagnose accelerator、diagnose update	diagnostics-maintenance.md。Unity ドキュメントの検索、引用、バージョン照合については、docs-workflow.mdを参照してください
mcp（および configure）、setup claude / codex / grok / antigravity、skill（install / refresh / show）、plugin（install / remove / upgrade / list / changelog）、ローカルの pipeline（install / upgrade / list / list-versions）、command / commands / status / list、job（status / wait / cancel）、開いているモーダルダイアログへの応答（command editor.dialog list / answer / dismiss）、shell	integration-advanced.md
vcs — setup / status / sync / switch / doctor / providers / merge-setup / conflicts / explain / resolve / diff / blame / summarize / affected / hooks、vcs git（migrate-lfs / worktree）、vcs uvcs（locks / changesets / review）	version-control.md
collaboration（別名 collab）— annotations / attachments / thumbnail / reactions / read / subscribe / jira	collaboration.md

一般的なワークフロー

クラウドビルドまたは Pipeline Automation リソースを調べる

cloud-automation.md を参照して、両方のグループにおけるすべての読み取り専用コマンド、コンテキスト／認証、コマンドごとのフィルターと並べ替え、出力フィールド、ページネーション（--page／--limit を無視せず拒否するリーフを含む）、エラー、秘匿化について確認してください。pipeline cloud-build は Build Automation を読み取り、pipeline automation は Pipeline Automation を読み取ります。どちらも、実行中の Editor やローカルの Pipeline パッケージは必要ありません。サービスアカウントには数値の組織 ID を使用してください。これらのコマンドはビルド／ジョブの実行、ログ／アーティファクトの取得、設定の変更を行いません。

JSON／NDJSON は、Collab と同様に、API の完全な形式の結果を data の下に返します。NDJSON には最後の結果が 1 つ含まれ、アイテムフレームはありません。参照ドキュメントで定められた範囲のシークレット保護と、パブリック API の秘匿化に関する前提に従い、ネイティブフィールドと自由形式のメタデータを保持してください。テーブルの射影は別のままです。明示的に指定されたローカルビルドターゲットには _local が保持され、存在しないターゲットはローカル扱いになりません。これらの規約は、今後の cloud-automation 関連作業にも適用されます。

シーン、GameObject、アセットを編集する — まず unity status を実行

シーン、GameObject、プレハブ、アセットを編集する前に、unity status を実行して、接続中の Editor を検出してください。 接続可能な Editor がある場合は、プロジェクトファイルには手を加えず、ライブコマンドで操作してください。Editor は変更を実際のアクティブシーンに適用し、メモリ上の状態との同期も維持します。

unity status                       # is an Editor connected? (look for state "ready")
unity command                      # discover the scene/GameObject commands THIS Editor exposes
# then drive it with the commands it lists — for example, if your Editor exposes them:
unity command gameobject create   # act on the live, active scene
unity command scene save          # persist the active scene

コマンド名は Editor によって定義されるため、正確な一覧を確認するには unity command（または unity list）を実行してください。名前を推測しないでください。

ライブ Editor に接続できる場合、.unity、.prefab、.asset の YAML を手作業で編集しないでください。 ファイルを直接編集すると、次のような問題が起きる可能性があります。

• エラーが起きやすい — fileID と GUID を手作業で割り当てる必要があり、間違えやすいです。
• 実行中の Editor からは再インポートするまで認識されないため、変更が適用されずに失敗することがあります。
• 誤ったファイルを編集しやすい — たとえば、Editor のアクティブシーンが実際には Demo2.unity なのに SampleScene.unity に書き込み、見た目は正しい YAML ができてもユーザーには何の変化も見えないことがあります。

Editor に接続できないと結論づける前に、偽陰性となる次の 2 つの可能性を除外してください。どちらも、実際に Editor が閉じている場合と同じように見え、時間に追われていると見落としやすいものです。

• Safe Mode。 このプロジェクトで Editor が実際に起動しているのに unity command が接続できない場合、Editor が存在しないのではなく、コンパイルエラーによってSafe Modeで停止している可能性があります。unity status を実行してください。Safe Mode（コンパイルエラーを含む STATUS_SAFE_MODE）と報告された場合は、C# ソースを編集してコンパイルエラーを修正するのが正しい対応であり、代替策ではありません。integration-advanced.md → Safe Mode からの復旧を参照してください。
• サンドボックス化されたエージェントシェル。 このエージェントのようなコーディングエージェントでは、シェルコマンドが制限の厳しいサンドボックス内で実行されるのが一般的です。そのサンドボックスによって、実際に起動している Editor が unity status から見えなくなることがあります。これは、この事前確認に到達するすべてのシーン／GameObject／プレハブ／アセットのタスクに当てはまります。ライブ Editor を必要としない方法（たとえば通常の Editor API を使ってアセットを生成する方法）で完了できるタスクでも、「Editor がない」と判断され、作業が頓挫する可能性があります。「インスタンスがない」ことを Editor が停止している証拠と見なさないでください。また、ライブ接続で行う操作を再現しようとして、別のヘッドレス Editor プロセスを操作するなど、開示せずに第三の方法を即興で使うことも避けてください。サンドボックスによって実際の Editor が見えていない可能性があることを明確に伝え、代替策に移る前に Editor が実際に開いているか確認してください。詳細は、integration-advanced.md → サンドボックス化されたエージェントツールによって起動中の Editor が見えなくなる場合を参照してください。

上記の両方を除外してから、ファイルを直接編集する方法に切り替えてください。その場合は、「ライブ Editor は検出されなかったため、ファイルを直接編集します」と明示してください。

アセット、テクスチャ、スプライト、画像、または3Dモデルを生成する：ai カタログプラグインを確認する

「プロジェクト用のテクスチャ／スプライト／画像／3Dモデルを生成して」というリクエストに別の方法で応える前に、Unity AI Generators プラグイン（ai）がインストールされているか確認してください。 これはまさにこの種のリクエストに対応する、Unity 独自のカタログプラグインであり、ほとんどの場合、これを使うほうが適切です。以下と同じ3段階のパターン（意図を認識し、カタログを確認し、インストール前に尋ねる）は、このプラグインに限らず、CLI に付属するどのカタログプラグインにも適用できます。unity plugin list は、インストール済みかどうかにかかわらず、常にカタログ全体を表示するため、ほかに何が利用できるかを調べる方法でもあります。

1. インストールされているか確認します。

   unity plugin list --format json
   

   id が "ai" のエントリを見つけ、installed フィールド（true／false）を確認します。

2. インストールされていない場合は、ユーザーに伝えてから尋ね、決して黙ってインストールしないでください。 Unity がこの用途に対応する AI Generators プラグインを提供していることを明確に伝え、実行前にユーザーの承諾を待ちます。

   unity plugin install ai
   

   拒否は通常の応答です。ほかの場合に行うはずだった対応に切り替え、同じ会話の中で再度尋ねないでください。

   ai はアルファ版であり、アルファ版の期間中は Unity 社内ネットワーク上の Unity スタッフに利用が限定されています。一般ユーザーが unity plugin install ai を実行すると、サインインを求めるメッセージ（「Unity AI Generators is currently limited to Unity staff. Sign in with a Unity staff account…」）が表示される場合があります。そこを通過しても、実行環境から必要なネットワークに接続できなければ、通常のダウンロード失敗になります。いずれもリクエストの問題ではありません。メッセージを伝え、ほかの拒否の場合と同様に別の方法に切り替えてください。

3. 同じセッション内で、プラグインのエージェントスキルを取り込みます。 カタログプラグインはペイロードに独自のエージェントスキルを含めることができ（ai は含めています）、プラグインをインストールしただけでは、そのスキルは自動的に利用可能になりません。このスキル自体と同じ方法でミラーリングする必要があります。

   unity skill install <client>     # e.g. claude-code, first time this session
   unity skill refresh              # already mirrored earlier? re-render it fresh
   

   unity plugin install の最後の行には、適用すべきコマンドがすでに示されています。スキルを含むコピーをインストールした直後は unity skill install、すでにミラーリング済みでプラグイン内のコピーだけが更新された場合は unity skill refresh が示されます。unity skill list --format json で保存先を確認し（skill フィールドにプラグイン独自のスキル名がある行を探します。例：unity-ai）、path を確認してから、そのファイルを読んでプラグインのコマンドを実行してください。このスキルには unity 自体の説明しかないため、ここからコマンドの仕様を推測しないでください。

これらの手順を行う前にコマンドを実行した場合（unity ai … を直接入力した場合や、記憶を頼りに提案した場合）、人間向けと機械向け（--format json／--format ndjson）の両方の出力に、必要なインストールコマンド（unity plugin install ai）を明記した、明確で対処可能なメッセージが表示されます。安定したエラーコードは TOOL_NOT_INSTALLED です。コマンドが何も実行しなかった理由を推測せず、そのメッセージを読んでください。カタログツールを実行できないほかの2つの理由についても、同じ形式で TOOL_UNSUPPORTED_PLATFORM と TOOL_RUNTIME_NOT_INSTALLED が表示されます。

新しいプロジェクトをゼロから開始する

コンセプトに関する質問、計画中のバックグラウンドでの Editor のインストール、パッケージの選択、収益化への引き継ぎを含む、エンドツーエンドのガイド付き体験には、new-unity-project スキルを使ってください。このセクションは、そのスキルが基盤として使用する生の CLI 手順です。コマンドだけを使いたい場合は、こちらを直接使ってください。

CLI だけを使って、アイデアから実行可能なバージョン管理済みのプロジェクトを作成します。まず対象プラットフォームを決めてください。ステップ2でインストールする Editor モジュールは、対象プラットフォームによって決まります。後からモジュールを追加することもできます（unity install-modules）が、そのプラットフォームのモジュールがインストールされるまでは、そのプラットフォーム向けにプロジェクトをビルドできません。そのため、最初に決めておくのが最も簡単です。

# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md).
unity --version
unity auth status --format json      # if signed out:      unity auth login
unity license status --format json   # if none active:      unity license activate

# 2. Pick and install an Editor with the modules your target platforms need.
#    Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream
#    release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as
#    evaluation-only, never for a project you intend to ship. A deadline argues for LTS.
#    (lts / latest aliases work almost everywhere a version is accepted — `templates` is the
#     exception; see step 3.)
unity releases --stream lts --limit 5 --format json
unity install lts --module android --module ios --yes --accept-eula   # add --module webgl, etc.
unity editors --installed --format json                               # confirm it landed

# 3. List the real template ids this Editor offers — don't guess them — and pick by RENDER
#    PIPELINE, not just by 2D/3D. Default to the URP templates:
#      3D → com.unity.template.urp-blank      ("Universal 3D")
#      2D → com.unity.template.universal-2d   ("Universal 2D": URP + the 2D packages)
#    com.unity.template.3d and com.unity.template.2d are the Built-in Render Pipeline templates
#    (displayName "… (Built-In Render Pipeline)"): deprecated from Unity 6.5, gone in 6.7. Use
#    them only when the user explicitly asks for Built-in. Confirm the pick with the JSON
#    `renderPipeline` field — it is blank for universal-2d on current releases, so match that
#    one by id.
#    NOTE: `templates` does NOT resolve the lts / latest aliases — unlike `install` and
#    `projects create`, it passes --editor straight through and rejects anything that is not a
#    concrete 6000.x.y. Use the version you just installed (read it from `editors --installed`).
unity templates list --editor <6000.x.y> --type core --format json

# 4. Create the project. The first positional arg is the NAME; --path sets the parent directory.
#    All options supplied, so it won't prompt; add --non-interactive in CI.
#    (To publish it to a remote in the same step, use the source-control forms below instead.)
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.urp-blank

# 5. Add the Pipeline package BEFORE the first open. `unity command`, `unity status` and
#    `unity command script eval` all need it, and templates don't include it. The Editor reads
#    Packages/manifest.json when it loads the project, so installing first means the package
#    is live from the first open.
unity pipeline install --project-path ~/UnityProjects/MyGame

# 6. Open the project and wait until its Editor is ready to take commands. Pass the project's
#    full path: a path that exists matches that project's Editor only, so an Editor open on a
#    sibling checkout such as ~/UnityProjects/MyGame-lighting can't end the wait.
cd ~/UnityProjects/MyGame
unity open .
unity status --until-ready --project-path ~/UnityProjects/MyGame --format json

その後、バッチモードではなく、実行中の Editor でシーンを構築します。 実行中の Editor に対して unity command script eval（または Editor 独自の unity command ツール）を使い、GameObject を作成し、コンポーネントを接続して、アセット参照を設定します。また、同じ方法で結果を読み戻します。各ステップを次に進む前に確認できます。unity run -- -executeMethod で実行するスクリプトは、Editor を開いたままにできない場合（CI、ヘッドレスのビルドマシン）の代替手段です。生成したものを確認できないため、PanelSettings が設定されていない UIDocument のように、null として保存された参照があっても成功と報告されます。バッチモードを使う場合は、作業完了とする前に、結果を実行中の Editor で開いて確認してください。操作対象となる Editor の起動方法： integration-advanced.md → 操作対象となる Editor の起動方法。

ソース管理 — ユーザーに選んでもらいます。 CLI を使えば、どのプロバイダーでも新しいリモートに新規プロジェクトを 1 ステップで公開できます。必ずトークンは stdin で渡してください（--git-token-from-stdin）。そうすれば、シークレットがシェルの履歴やプロセス一覧に残りません。プロジェクトに合わせて選び、どれか一つをデフォルトにしないでください。

• Git — GitHub / GitLab（--vcs github / --vcs gitlab）。広く普及しています。アセットの多いゲームでは、大きなバイナリで履歴が肥大化しないように Git LFS（--git-lfs）を追加してください。
• Unity Version Control — UVCS（--vcs uvcs）。Unity 独自の VCS で、大容量のバイナリアセットを扱うゲーム向けに構築されています。バイナリをネイティブに処理し（LFS は不要）、ファイルロックにも対応しているため、アートアセットの多いプロジェクトや大規模なチームには適していることがよくあります。認証には Unity へのサインインを使い、リージョンは --vcs-region で選択します。

# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you
# want to add packages/assets BEFORE the first commit (see the new-unity-project flow).
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.urp-blank \
  --vcs github --git-namespace my-org --git-repo my-game \
  --git-visibility private --git-default-branch main --git-token-from-stdin --git-lfs

# Unity Version Control (UVCS) — handles binaries natively, so no LFS:
unity projects create "MyGame" --path ~/UnityProjects \
  --editor-version lts --template com.unity.template.urp-blank \
  --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>

--git-token-from-stdin には、リテラルではなくシークレットストアからトークンを渡してください。たとえば、$GIT_TOKEN が CI／シークレットマネージャーから取得される場合は、… --git-token-from-stdin <<<"$GIT_TOKEN" のようにします（UVCS は Unity へのサインインを使うため、トークンは不要です）。

UVCS ワークスペースを日常的に使う場合：いくつかの読み取り操作はラッパー経由で、それ以外はすべて cm に直接渡します。 この使い分けには理由があり、誤った方法を推測するとユーザーの時間を無駄にするため、理解しておく価値があります。

• unity vcs uvcs <verb> は、cm のデータをプロジェクトと結び付ける読み取り操作をラップします。対象は locks（ロックを保持している人と、すでに変更したファイルをカバーするロック）、changesets、review です。これらの結合処理は cm では実行できず、安定した形式で返されるため、出力を解析するものがある場合は、こちらを優先してください。
• unity uvcs <args> は、--help や --format も含め、コマンドライン全体をそのまま cm に渡します。これは正式にサポートされた方法であり、回避策ではありません。cm がこのコマンド体系を管理し、バージョンを付けているため、ラップすると古くなる言い換えに依存することになります。部分チェックアウト、シェルフ、ロックの取得または解除にはこちらを使い、出力を人が読む場合にも利用してください。

unity vcs uvcs locks                       # who holds what, and what collides with your changes
unity uvcs lock list                       # the raw listing, cm's own flags and output
unity uvcs partial update /Assets/Levels   # cm's own vocabulary, unchanged
unity uvcs shelve -c "wip: lighting pass"

各動詞、フラグ、注意点については、version-control.md を参照してください。

unity cm <args> は、cm 独自の名前で同じパススルーを実行します。どちらも cm クライアントが必要です。コマンドで見つからないというメッセージが表示された場合は、unity plugin install plastic でインストールしてください。

セットアップ後は、vcs グループで日々の作業全体をカバーできます — status、sync、switch、merge-setup、conflicts / explain / resolve、diff、blame、summarize、affected、hooks、doctor、providers — そして、生の git よりこちらを使う理由は、Unity のセマンティクスにあります。フラグと注意点を含む完全なリファレンス： version-control.md。 Git トークンは CLI ではなく、ユーザーの認証情報マネージャーに保存してください。 トークンフラグまたは環境変数が指定されていない場合、CLI は git credential fill を呼び出し、設定済みのヘルパーが返すものを使用します。渡された情報や指示された情報を保存することはありません。CLI が Git トークンを保存できると提案しないでください。また、ユーザーがすでに動作する認証情報ヘルパーを使っている場合は、トークンフラグを安易に使わないでください。組織ごとに異なるトークンを使いたい場合は、git config --global credential.useHttpPath true と、Git Credential Manager などの複数アカウント対応ヘルパーを組み合わせてください。CLI はヘルパーがリポジトリを区別できるよう、完全なリポジトリ URL を渡しますが、ヘルパーをインストールしたり再設定したりすることはありません。UNITY_GITHUB_TOKEN／UNITY_GITLAB_TOKEN はプロバイダーごとにトークンを 1 つだけ使うため、複数の組織にまたがる CI ジョブでは、代わりに呼び出しごとに --git-token-from-stdin を渡してください。ソース管理フラグの全一覧は、references/projects-templates.md を参照してください。代わりにローカルのみの Git リポジトリを使用する場合は、Unity に適した無視設定で git を初期化し、数 GB に及ぶ Library/ やその他の生成フォルダーが決してコミットされないようにしてください。

cd ~/UnityProjects/MyGame
git init -b main
# Download (do not pipe to a shell) a maintained Unity .gitignore:
curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore

# Asset-heavy game? Keep large binaries out of git history with Git LFS:
git lfs install
git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png"   # adjust to your asset types
git add .gitattributes

git add -A
git status                             # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged
git commit -m "Initial Unity project: MyGame"
git ls-files | grep -c '^Library/'     # must print 0

CLI が対応する範囲と、対応しない範囲。 CLI はエディター、プロジェクト、ソース管理に対応します。トップレベルのパッケージコマンドはありません。テンプレート以外の UPM（Unity Package Manager）パッケージを追加するには、unity-package-management スキルを使ってください。このスキルは、unity command を通じて Pipeline の package add コマンドを実行し、フォールバックとしてヘッドレスの C# スクリプトを使います。収益化やバックエンドについては、専用スキルに引き継いでください。implement-in-app-purchases（IAP）、levelplay-unity-integration（広告）、または build-live-game（アカウント、クラウドセーブ、経済システム、リモート設定、リーダーボード）を使います。上記の手順 5 と 6 が完了したら、開いているエディターで作業してください。

エディターがすでに開いている状態で Pipeline パッケージをインストールしましたか？ エディターがマニフェストの変更を読み取るのは、次に更新するときです。それまでは unity status は STATUS_PIPELINE_LOAD_PENDING を報告します（このコードが導入される前の CLI リリースでは STATUS_NO_INSTANCES を報告します）。起動中またはインポート中のエディターも、完了するまでは同じコードを報告するため、まず完了を待ってください（unity status --until-ready）。CLI 自体では更新をトリガーできません。エディターの起動が完了している場合は、ユーザーに Unity Editor ウィンドウへ切り替えてもらってから、unity status --until-ready を再実行してください。最初の起動前（手順 5）にインストールすれば、この問題を完全に回避できます。

不足しているエディターを見つけてインストールする

# 1. Check what's installed
unity editors --installed --format json

# 2. Browse available LTS versions
unity releases --lts --limit 5 --format json

# 3. Install
unity install 6000.0.47f1 --yes --accept-eula

正しいエディターでプロジェクトを開く

# 1. Check the project's required editor version
unity projects info /path/to/MyProject --format json
# Look at "editorVersion" in the result

# 2. Confirm that editor is installed
unity editors --installed --format json

# 3. Open (warns if the editor version is missing)
unity open /path/to/MyProject

CI：ライセンスをアクティベートしてからビルドする

# 1. Activate a license without signing in; a service account cannot activate one.
#    A perpetual or legacy serial: store it as the CI secret UNITY_LICENSE_SERIAL
#    (the name `unity ci init` generates) and pass it to the step, e.g. in GitHub
#    Actions `env: { UNITY_LICENSE_SERIAL: ${{ secrets.UNITY_LICENSE_SERIAL }} }`.
#    A serial tied to a subscription needs a signed-in user, so for those seats use
#    --floating, or the offline --generate-request / --file path (see "Headless /
#    fleet license activation" in references/auth-license-cloud.md).
unity license activate --serial "$UNITY_LICENSE_SERIAL"   # or: unity license activate --floating

# 2. Only if the job also runs cloud commands: export UNITY_SERVICE_ACCOUNT_ID and
#    UNITY_SERVICE_ACCOUNT_SECRET from the CI secret store. Every later command reads
#    them directly, with no `unity auth login` and nothing written to a credential
#    store (which a headless runner may not have).

# 3. Build
unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

# 4. Return the license when done (serial or assigned seats)
unity license return --yes

CI：ヘッドレスビルド

バッチモード、ログ記録、CI フラグに対応している専用の unity build コマンドを優先してください。

unity build /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --target StandaloneLinux64 \
  --execute-method Builder.PerformBuild \
  --allow-install
echo "Exit code: $?"

または unity run を使ってください（バッチモードは自動的に有効になるため、-batchmode／-quit は渡さないでください）。

unity run /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --allow-install \
  -- -executeMethod Builder.PerformBuild -logFile build.log
echo "Exit code: $?"

プレイヤービルド用のスクリプトを作成していますか？ 各 MonoBehaviour は、それぞれのクラス名を付けた .cs ファイルに単独で記述してください。1 つのファイルに複数記述しても、エディターと Play Mode では問題なく動作することがありますが、ビルドしたプレイヤーは起動時に level0 などのシーンファイルが破損しているというエラーを表示してクラッシュすることがあります。build-run-test.md を参照してください。

CI：テストを実行して結果を公開する

unity test /path/to/MyProject \
  --editor-version 6000.0.47f1 \
  --mode EditMode \
  --report-format junit \
  --output ./test-results.xml \
  --allow-install \
  --timeout 600
case $? in
  0) echo "All tests passed" ;;
  8) echo "Tests failed — report to developers, do not retry" ;;
  *) echo "Run did not complete — infrastructure failure, safe to retry" ;;
esac

終了コード 8 は、実行が完了し、失敗したテストが報告されたことを意味します。それ以外のゼロ以外のコードは、判定結果が出なかったことを意味します。--format json では、同じ違いが errors[0].code の TESTS_FAILED と TEST_RUN_ERROR ／ TEST_TIMED_OUT で表されます。

--report-format junit を指定すると、--output が JUnit スキーマのレポートになります。GitHub Actions と GitLab では、変換手順なしでネイティブのテスト結果として取り込めます。テストが失敗した場合も書き込まれます。既定の NUnit3 を使うにはこのフラグを省略するか、1 回の実行で両方を取得するには --report-format nunit,junit を使います。Unity Code Coverage パッケージを使ってカバレッジを収集するには --coverage を追加します。プロジェクトにパッケージがない場合は、警告を出して処理を続行します。build-run-test.md を参照してください。

パイプラインを通すためではなく、変更に取り組んでいますか？ その変更で失敗する可能性があるテストのうち、最もコストの低いものを実行してください。まず EditMode を試してください。作業中は --filter、--affected、または --rerun-failed を使ってください。作業を引き渡す前に、最終コードでモードごとに 1 回、全テストスイートを実行してください。判定結果が出ずに終了コード 6 で終了した場合を除き、変更されていないコードでテストスイートを再実行しないでください。これらの実行では NUnit の既定設定を使ってください。--affected と --rerun-failed は、上記の CI の例で出力される JUnit のみのレポートを読み取れないためです。build-run-test.md に、このルールと各フラグが読み書きするレポートが記載されています。unity test は Editor で開いているプロジェクトを拒否します。実行のためにユーザーの Editor を閉じたり、Play Mode 中にテストを開始したりしないでください。

CLI のデバッグ

# Check auth + installed editors + recent errors in one command
unity doctor --format json

# Follow live logs during an install
unity logs --follow --level info

---

通知

--format json または --format ndjson のエンベロープには、notifications 配列が含まれることがあります。これは実行したコマンドではなく、ユーザーの環境に関するアドバイスです。通知がある場合は、ユーザーに伝えてください。 そのほかに通知を確認する方法がありません。人間向けの通知はターミナルのバナーとして表示され、あなたには届かないためです。

報告する内容がない場合、キーは存在しません。そのため、 envelope.notifications ?? [] として読み取ってください。

{
  "code": "CLI_UPDATE_AVAILABLE",
  "message": "A new version of the Unity CLI is available: 1.0.0-beta.8 → 1.0.0-beta.9",
  "data": { "current": "1.0.0-beta.8", "latest": "1.0.0-beta.9" },
  "remediation": { "command": "unity self-update", "requiresUserApproval": true }
}

code に基づいて分岐してください。message はローカライズされており、表示を目的としています。data の形式は code ごとに異なります。

PLUGIN_UPDATE_AVAILABLE は、インストール済みのプラグインに新しいバージョンがあることを意味します。 data は { "plugin": "<id>", "current": "…", "latest": "…" } で、推奨される対処方法は unity plugin upgrade <id> です。古いプラグインごとに 1 件ずつエントリがあります。

remediation は、通知を解消する方法を示します。存在しない場合は情報提供のみの通知であり、実行するコマンドはありません。

FEX_EMU_EXPERIMENTAL は、Linux arm64 上で FEX-Emu を介して x86_64 Editor を実行した、または実行することを意味します。実験的であり、サポート対象外であること、また C# スクリプトのコンパイルがクラッシュすることが確認されていると、ユーザーに伝えてください。

requiresUserApproval: true の場合は、remediation.command を自分で実行してはいけません。 通知とコマンドを提示し、ユーザーが判断できるようにしてください。

---

注意事項

• --non-interactive と --yes を併用すると、すべてのプロンプトが抑制されます。CI では両方を使用してください。
• 短いフラグの意味は、どのコマンドでも共通です。--yes がある場合、-y は常に --yes を意味し、-a は --architecture を意味します。unity projects list と unity projects size では「すべてのプロジェクト」を --all と表記します。-a ではなく、こちらを指定してください。CLI が引き続き受け付ける古い表記（-a、status の --project、--template-version、--hub-version、--package-version、--list-components、--install-dir、--childModules、--wait-timeout、--git-token-stdin、command の --group_by、collaboration annotations の --local-space、collaboration の --project-id と --organization-id、projects list の -v、releases と vcs git migrate-lfs の --since）を指定すると、使用すべき表記を示す警告が出力されます。editors と projects list の --verbose も同様に警告が出ます。このフラグは引き続きすべての列を表示しますが、現在は --long と表記します。--format json では、警告はエンベロープの warnings に含まれます。新しい表記を使い、解析するログに警告が残らないようにしてください。
• すべてのコマンドで、--timeout は数字で記述した整数の秒数（--timeout 600）を受け取ります。UNITY_BUILD_TIMEOUT、UNITY_RUN_TIMEOUT、UNITY_TEST_TIMEOUT も同様です。単位、少数、指数表記（30s、5m、1.5、1e3）は使用法エラー（終了コード 2）になるため、分は自分で秒に換算してください。
• --format json は常に機械可読な出力を生成します。人間向けのテキストを解析するより、こちらを優先してください。エラーエンベロープも成功時のエンベロープと同じ 2 つのスペースでインデントされ、整形出力されます。
• success が true になるのは、終了コードが 0 の場合に限ります。 ステータスコマンドの回答が「いいえ」の場合（サインアウト状態の unity auth status、ライセンスがない場合の unity license status、準備完了状態の Editor がない場合の unity status）、コマンドは失敗となります。success: false となり、回答を示す名前が errors[0].code に入り、レポートは引き続き data に含まれます。何も見つからないリスト（Editor がない場合の unity editors running）は、空のリストを返して成功します。
• 失敗は stderr ではなく stdout から読み取ってください。 コマンドが失敗しても、完全なドキュメントが stdout に書き込まれます。--format json では success: false と値が設定された errors 配列を持つエンベロープが出力され（分岐には、安定したトークンである errors[0].code を使用してください）、--format ndjson では通常の終端 {"type":"result","success":false,…} フレームが出力されます。成功時も含め、すべての ndjson ストリームは終端の {"type":"result"} フレームを正確に 1 つ含みます。 そのフレームがないストリームは途中で切れています。テーブル形式のリスト（unity editors、unity editors upgrade --check、unity templates list、unity releases、unity projects list、unity context list、unity auth list、unity modules list、unity list、unity doctor、unity cloud org list、unity cloud project list）では、最初に 1 行につき 1 レコードが出力され、各行には type フィールドがありません。その後、data が {"count": N} の終端フレームが出力されます。単一レコードの回答（unity version、unity language、unity config proxy、unity cache info など）はそのフレームのみで、その data は --format json と同じです。unity env は行を出力した後、フレームを出力します。--quiet は json の出力を変更しません。ndjson の出力も通常は変更しませんが、unity editors upgrade、unity editors module list、unity install-modules、unity build --list-targets、unity build --list-profiles、unity env では、既知のバグにより --quiet を指定すると行が出力されなくなります（終端フレームは出力されます）。これらの行が必要な場合は、--quiet を指定しないでください。どちらの形式でも、警告は warnings にのみ表示され、stderr には出力されません。--watch を指定したリストは Ctrl-C で終了するまで実行され、終端フレームは出力されません。いくつかのコマンド（unity install-modules --list など）では、成功した ndjson ストリームが終端フレームなしで終了する既知のバグがあります。分岐には data ではなく、必ず success を使用してください。 失敗時の data は通常 null ですが、常にそうとは限りません。unity editors add が一部失敗した場合はパスごとの行が含まれ、曖昧な unity auth switch の場合は、判別に使える data.candidates が含まれます。success と終了コードを確認してください。空の stdout を失敗のシグナルとして扱わず、これらの形式では人間向けの診断情報のみが含まれる stderr を解析しないでください。ゼロ以外の終了コードで stdout が空の場合、そのコマンドに既知のバグがあるということであり、コードで想定すべき出力形式ではありません。
• unity <version> [path] は、unity open [path] --editor-version <version> の省略形です。lts、latest、または 6000.0.47f1 のような完全なバージョン文字列を使用できます。
• CLI は kubectl スタイルのプラグインに対応しています。PATH 上にある任意の unity-<name> バイナリを、unity <name> として呼び出せます。
• ターミナル出力は、サーバーから渡された値（プロジェクトタイトル、Editor のバージョン、モジュール名）による制御文字やエスケープシーケンスの注入を防ぐよう強化されています。テーブル、リスト、ツリーの出力では C0 制御文字と SGR 以外のエスケープシーケンスが除去されます。さらに、Commander の使用法エラー、unity bug のログアーカイブに関する警告、unity projects add／remove の機械向け（tsv）出力でも除去されます。SGR の色／スタイルコードは保持されます。
• CLI はバグ修正に役立てるため、クラッシュとエラーを匿名で Sentry に報告します（IP アドレスとホスト名は含まれず、ホームディレクトリのパスやトークンのような値は送信前に除去されます）。この動作は Unity Hub と同様です。分析への参加を選択すると、匿名化されたマシン ID も追加で送信されます。参加を選択しなかったユーザーは、完全に匿名のままです。報告を完全に無効にするには、UNITY_NO_CRASH_REPORT を設定してください。これとは別に、分析／同意の状態にかかわらず、実行のたびに匿名の cli telemetry 使用状況 ping が 1 回送信されます。詳しくは diagnostics-maintenance.md を参照してください。
• unity --version は、現在使用しているバージョンを表示します。unity self-update --check --format json は、インストール済みのチャンネルに新しいバージョンがあるかどうかを示します（ベータ版を使用している場合は、次のベータ版が対象です）。安定版リリースを確認するには、たとえば GA リリース後にベータ版から移行する場合、unity self-update --check --channel stable --format json を実行します。
• 特定のバージョンを使うよう指示されていない限り、常に最新バージョンの Unity CLI を使用してください。 CLI の新しいバージョンでは、このドキュメントに記載されているコマンドや出力フィールドが定期的に追加されます。そのため、古いバージョンでは、ドキュメントが間違っているように見える形で動作に失敗します。
• 0.1.0-beta.8 以降、CLI はバックグラウンドで新しいバージョンを確認し、目立たない「アップデートがあります」という通知を表示します（対話型セッションのみ。コマンドが遅延することはありません）。unity config update-check off または UNITY_NO_UPDATE_CHECK 環境変数で無効にできます。
• 同じ確認は、CLI がインストールしたプラグイン（unity plugin install）も対象です。新しいバージョンがある場合、プラグイン名と unity plugin upgrade の実行を促す通知が、最大で 1 日に 1 回表示されます。無効化には同じ 2 つの方法を使います。
• --format json と --format ndjson では、同じ通知がエンベロープの notifications 配列に含まれます。 詳しくは、以下の 通知 を参照してください。MCP 経由では、セッションごとに 1 回、サーバーの initialize instructions に文章として届きます。
• すべての CLI コマンドからの外向き HTTP 通信は、解決されたプロキシに従います（unity config proxy を参照）。無効な --proxy 値（不正な URL または未対応のスキーム）を指定すると、無視されるのではなく、使用法エラー（終了コード 2）になります。CLI が実際に解決した内容は、unity env --format json または unity doctor --format json で確認できます。どちらも有効なプロキシ URL、その取得元、認証情報の取得元を表示します。