Unity CLI 에 대해 알아보자

1. Unity CLI란?

Unity CLI는 Unity Hub 화면을 열지 않고 터미널에서 Unity 개발환경을 관리하는 공식 명령줄 도구입니다.

주요 역할은 다음과 같습니다.

• Unity Editor 설치
• Android·iOS·WebGL 모듈 설치
• 설치된 Editor 목록 확인
• 프로젝트에 맞는 Unity 버전으로 실행
• Unity 계정 로그인
• CLI 업데이트
• CI/CD 환경 자동 구성

기존 Unity Hub의 CLI 기능과 달리, 독립된 unity 네이티브 실행 파일로 제공되므로 CI 서버나 AI 에이전트가 호출하기에 적합합니다.

현재 글 작성 시점 기준으로 Unity CLI와 Unity Pipeline 모두 experimental 단계입니다.

---

2. 설치

macOS / Linux

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh \
  | UNITY_CLI_CHANNEL=beta bash

Windows PowerShell

$env:UNITY_CLI_CHANNEL='beta'
irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

설치 후 터미널을 다시 열고 확인합니다.

unity --version

---

3. Unity Editor 설치

최신 LTS 설치

unity install lts

특정 버전 설치

unity install 6000.3.7f1

플랫폼 모듈과 함께 설치

unity install lts -m android ios webgl

기존 Editor에 모듈 추가

unity install-modules -e 6000.3.7f1 -m android ios

주의할 점은 모듈 추가가 가능한 Editor가 다음 방식으로 설치된 경우에 한정된다는 것입니다.

• Unity Hub로 설치
• Unity CLI로 설치

수동으로 복사하거나 직접 배치한 Editor는 모듈 추가 대상이 아닐 수 있습니다.

---

4. Unity 프로젝트 실행

unity open ./MyProject

open은 생략할 수도 있습니다.

unity ./MyProject

Unity CLI가 프로젝트의 설정을 읽고 해당 프로젝트에 필요한 Unity Editor 버전을 찾아 실행합니다.

즉, 프로젝트마다 Unity 버전이 다를 때 직접 Editor 실행 경로를 지정하는 작업을 줄일 수 있습니다.

---

5. 인증과 업데이트

Unity 계정 로그인

unity auth login

로그인 상태 확인

unity auth status

Unity CLI 업데이트

unity upgrade

헤드리스 서버나 CI 환경에서는 환경변수를 이용한 서비스 계정 인증도 지원하는 구조입니다.

---

6. CI/CD 활용

Unity CLI는 자동화 도구가 결과를 읽기 쉽도록 구조화된 출력 형식을 지원합니다.

JSON 출력

unity editors --format json

TSV 출력

unity editors --format tsv

표준 출력과 오류 출력이 분리되고 종료 코드도 명확합니다.

종료 코드의미

0	성공
1	오류
130	사용자 또는 작업 취소

확인 질문 없이 자동 설치할 수도 있습니다.

unity install lts \
  -m android ios \
  --accept-eula \
  --yes

환경이나 인증 문제를 진단할 때는 다음 명령을 사용합니다.

unity doctor

GitHub Actions 같은 CI에서는 다음 작업을 자동화할 수 있습니다.

저장소 체크아웃
→ Unity CLI 설치
→ 지정 Unity 버전 설치
→ 플랫폼 모듈 설치
→ 인증
→ 테스트
→ 빌드
→ 결과 및 종료 코드 확인

---

7. Unity CLI와 Unity Pipeline의 차이

두 도구의 역할을 구분하는 것이 중요합니다.

구분Unity CLIUnity Pipeline

주요 목적	Unity 설치 및 실행환경 관리	실행 중인 Editor·Player 외부 제어
Editor 설치	가능	담당하지 않음
모듈 설치	가능	담당하지 않음
프로젝트 실행	가능	실행 후 내부 조작
Play 모드 제어	Pipeline을 통해 가능	가능
Unity API 호출	직접적인 핵심 기능 아님	가능
C# 코드 실행	직접적인 핵심 기능 아님	eval 지원
AI 에이전트 연동	환경 관리 담당	실제 Editor 조작 담당

정리하면 다음과 같습니다.

Unity CLI
= Unity 개발환경을 설치하고 프로젝트를 실행하는 도구

Unity Pipeline
= 실행 중인 Unity Editor와 Player를 외부에서 조작하는 도구

---

8. Unity Pipeline 설치

프로젝트를 실행한 상태에서 다음 명령으로 Pipeline 패키지를 추가합니다.

unity pipeline install

Unity Pipeline은 제공된 글 기준으로 Unity 6.0 LTS 이상을 대상으로 하며, 로컬 API를 통해 Unity CLI와 Editor를 연결합니다.

사용 가능한 명령 목록을 확인합니다.

unity command

특정 명령을 실행합니다.

unity command <command-name>

예를 들면 프로젝트에 등록된 테스트나 에디터 도구를 다음처럼 호출하는 구조입니다.

unity command run-tests
unity command enter-play-mode
unity command generate-assets

단, 실제 명령 이름은 프로젝트에 등록된 명령에 따라 달라집니다.

---

9. 프로젝트 전용 CLI 명령 만들기

C# 정적 메서드에 CliCommand 속성을 붙이면 프로젝트 전용 명령을 만들 수 있습니다.

using Unity.Pipeline.Commands;
using UnityEngine;

public static class MyPipelineCommands
{
    [CliCommand("greet", "Log a greeting and return its length")]
    public static int Greet(
        [CliArg("name", "Who to greet", Required = true)] string name)
    {
        Debug.Log($"Hello, {name}!");
        return name.Length;
    }
}

터미널에서는 다음처럼 실행합니다.

unity command greet --name World

별도의 복잡한 등록 코드 없이 속성이 붙은 메서드가 자동으로 검색됩니다.

이 방식으로 다음 기능을 CLI 명령으로 공개할 수 있습니다.

• 씬 생성 및 변경
• GameObject 배치
• 프리팹 생성
• 에셋 임포트
• 테스트 실행
• 프로젝트 검증
• 빌드
• Play 모드 진입
• 커스텀 에디터 도구 실행

---

10. Unity Editor 안에서 C# 실행

Unity Pipeline은 실행 중인 Editor 내부에서 C# 표현식이나 코드를 실행하는 eval 기능을 제공합니다.

Unity 버전 확인

unity command eval "return Application.version;"

Play 모드 상태 확인

unity command eval \
  "return UnityEditor.EditorApplication.isPlaying;"

C# 파일 실행

unity command eval_file "path/to/script.cs"

코드는 Roslyn으로 컴파일되어 Unity Editor의 메인 스레드에서 실행됩니다.

장점은 전체 프로젝트를 다시 컴파일하거나 도메인을 리로드하지 않고도 Unity API를 호출할 수 있다는 점입니다.

다만 eval은 임의의 Unity API를 실행할 수 있으므로 보안상 매우 강력한 기능입니다. 제공된 글에 따르면 실행 시 보안 토큰이 필요합니다.

---

11. 개발용 Player 제어

Unity Pipeline 런타임 컴포넌트를 Development Build에 포함하면 Editor뿐 아니라 실행 중인 게임 Player도 제어할 수 있습니다.

unity command --runtime <player-name>

가능한 활용 사례는 다음과 같습니다.

• Player 로그 수집
• 게임 상태 조회
• 런타임 API 호출
• 자동 QA 수행
• 개발용 Player 코드 핫리로드
• 특정 위치나 게임 상태 재현
• 테스트 캐릭터 또는 데이터를 주입

이 기능은 기본적으로 비활성화되어 있고 로컬호스트 접속을 전제로 합니다.

따라서 배포용 본 게임보다는 다음 환경에 적합합니다.

• 개발용 빌드
• 내부 QA 빌드
• 자동 테스트용 빌드
• 에이전트 검증용 빌드

---

12. AI 에이전트와의 연동

Unity CLI와 Pipeline이 중요한 이유는 AI가 단순히 C# 코드만 작성하는 수준에서 벗어나 실제로 Unity를 실행하고 결과를 검증할 수 있는 기반을 제공하기 때문입니다.

기존 AI 코딩 흐름은 보통 다음과 같았습니다.

AI가 코드 작성
→ 사람이 Unity Editor 실행
→ 사람이 컴파일 오류 확인
→ 사람이 Play 모드 실행
→ 결과를 다시 AI에게 설명

Unity CLI와 Pipeline을 연결하면 다음 흐름으로 확장할 수 있습니다.

AI가 프로젝트 분석
→ Unity 프로젝트 실행
→ C# 코드 수정
→ Unity 컴파일 상태 확인
→ 테스트 실행
→ Play 모드 진입
→ 로그 및 상태 조회
→ 오류 분석
→ 코드 재수정
→ 다시 테스트

특히 JSON 출력, 공통 종료 코드, 커스텀 CLI 명령이 있기 때문에 AI가 Unity 화면을 이미지로 분석하지 않고도 구조화된 결과를 받을 수 있습니다.

---

13. MCP와 연결했을 때의 구조

[Inference] 다음 구조는 제공된 기능 설명을 기반으로 정리한 일반적인 연동 방식입니다.

Claude Code / Codex / Gemini CLI / 자체 AI 에이전트
                    ↓
                 MCP 서버
                    ↓
               Unity CLI
                    ↓
             Unity Pipeline
                    ↓
       Unity Editor 또는 Development Player

MCP 도구는 예를 들어 다음 형태로 설계할 수 있습니다.

unity_open_project
unity_get_commands
unity_execute_command
unity_eval
unity_run_tests
unity_enter_play_mode
unity_get_console_logs
unity_build_project
unity_inspect_scene

다만 eval을 AI에게 직접 무제한 공개하는 것은 위험할 수 있으므로, 실무에서는 허용된 작업만 수행하는 커스텀 명령을 만드는 편이 더 안전합니다.

예:

[CliCommand("validate-scene", "Validate the active scene")]
public static ValidationResult ValidateScene()
{
    // 허용된 검증 작업만 수행
}

---

14. 가장 유용한 실무 활용 사례

자동 개발환경 구성

unity install 6000.3.7f1 -m android --accept-eula --yes
unity auth login
unity ./MyProject

자동 테스트

unity command run-tests

프로젝트 상태 검사

unity command validate-project

AI가 생성한 씬 검증

AI가 씬 생성 코드 작성
→ Unity CLI로 프로젝트 실행
→ Pipeline 명령으로 씬 생성
→ Play 모드 실행
→ 로그 확인
→ 실패 시 재수정

모바일 빌드 자동화

Unity 설치
→ Android 또는 iOS 모듈 설치
→ 프로젝트 열기
→ 테스트
→ 빌드 명령 실행
→ 빌드 산출물 확인

---

15. 주의할 점

아직 실험 단계

Unity CLI와 Unity Pipeline 모두 experimental이므로 명령 형식이나 API가 변경될 가능성이 있습니다.

eval 보안

eval은 Unity Editor 안에서 임의의 C# 코드를 실행할 수 있습니다. 신뢰할 수 없는 입력이나 외부 네트워크에 직접 노출하면 위험합니다.

Editor 메인 스레드

Pipeline 코드가 Editor 메인 스레드에서 실행되므로 장시간 작업을 동기적으로 실행하면 Editor가 멈춘 것처럼 보일 수 있습니다.

커스텀 명령 우선

AI 연동에서는 자유로운 eval보다 명시적으로 검증된 CliCommand를 제공하는 편이 적절합니다.

권장:
unity command build-android
unity command validate-scene
unity command run-game-tests

주의:
unity command eval "<AI가 생성한 임의 코드>"

개발용 Player에서만 사용

런타임 제어 기능은 배포용 빌드가 아니라 Development Build와 QA 환경 중심으로 사용하는 것이 적합합니다.

---

핵심 요약

Unity CLI
- Unity Editor 설치
- 플랫폼 모듈 설치
- 프로젝트 실행
- 계정 인증
- CI 환경 구성

Unity Pipeline
- 실행 중인 Editor 제어
- 커스텀 CLI 명령 실행
- C# 코드 실행
- Play 모드와 테스트 제어
- Development Player 제어

두 도구를 결합하면
AI가 Unity 프로젝트를 수정하는 데서 끝나지 않고
실행·테스트·로그 확인·재수정까지 자동화할 수 있다.

가장 중요한 변화는 Unity Hub를 CLI로 대체하는 것 자체가 아니라, Unity Editor를 AI 에이전트가 검증 가능한 형태로 외부 제어할 수 있게 되었다는 점입니다.