Unity CLI 소개: 터미널에서 Unity 관리하기

요약 (TL;DR)

현재 사용 가능: Unity CLI는 에디터, 모듈, 프로젝트 및 인증(auth)을 터미널에서 관리하고 상호 작용하는 독립적인 unity 바이너리입니다. UI가 필요 없으며, 명령줄을 통해 설치할 수 있습니다.

• 자동화에 최적화됨: 구조화된 JSON/TSV 출력, 명확한 종료 코드, 비대화형(non-interactive) 설치 및 CI를 위한 서비스 계정 인증을 지원합니다.
  오늘도 사용 가능: 실험적인 com.unity.pipeline 패키지는 CLI가 로컬 API를 통해 실행 중인 에디터 또는 개발 플레이어 빌드를 구동할 수 있게 합니다. [CliCommand] 속성을 사용하여 자체 명령을 노출할 수도 있습니다. unity command eval은 실행 중인 에디터나 플레이어 내부에서 C# 코드를 실시간으로 실행하고 결과를 반환하며, 프로젝트 단위의 재컴파일이나 도메인 리로드가 필요 없습니다.
• 이들을 결합하여 AI 에이전트가 Unity를 작동할 수 있게 합니다: 라이브 프로젝트를 관찰하고, 그 위에 행동을 취하며, 결과를 검증합니다.
• Unity CLI에 대한 비디오 개요를 보고 싶다면 여기에서 확인할 수 있습니다.

개발의 영역은 점점 더 터미널로 이동하고 있습니다. 스크립트 내에서, CI 환경에서, 그리고 점점 AI 에이전트의 손을 거치면서 말입니다. 오늘 Unity가 그곳에서 여러분을 만납니다. Unity CLI는 모든 레벨에서 Unity를 터미널로 가져옵니다: 하나의 바이너리로 에디터를 설치하고 관리하며, 스크립트에서 실행 중인 에디터를 구동하고, 심지어 재컴파일 없이 프로젝트 내부의 C# 코드를 실시간으로 실행할 수 있습니다. 이것은 단일하고 빠른 unity 명령어이며, 각 레이어는 이전보다 더 나아갑니다: CLI가 Unity를 관리하고, Pipeline 패키지가 이를 구동하며, eval이 그 내부까지 도달합니다. CLI와 Pipeline 패키지 모두 오늘 사용 가능합니다.

이 기능들이 결합될 때 무엇이 가능한지 살펴보기 전에 먼저 살펴보겠습니다:

*이 25초 클립에서 개발자가 AI 에이전트에게 일반 영어로 작성된 버그 보고서(

Unity CLI란 무엇인가

CLI는 단일의 독립적인 바이너리 형태로 제공됩니다. 설치할 의존성이 없으며, 설치 과정에서 자동으로 PATH에 추가됩니다. 단순히 unity로 실행하고 unity upgrade로 제자리에서 업데이트하면 됩니다. 에디터와 프로젝트 외에도 모듈 및 인증(authentication)까지 처리하므로, 새 컴퓨터에는 다른 것이 필요하지 않습니다.

네이티브 바이너리이기 때문에 시작 속도가 빠릅니다. 반면 이전의 Unity Hub 헤드리스 경로(-- --headless)는 눈에 띄게 시간이 더 오래 걸렸습니다. 이 시간 차이는 스크립트나 에이전트가 작업당 수십 번 호출하는 경우 누적되어 큰 영향을 미칩니다.

시작하기

플랫폼의 패키지 관리자를 사용하여 설치하세요:

# macOS 또는 Linux
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
# Windows
...

(참고: brew, winget, apt와 같은 표준 패키지 관리자에 대한 지원은 곧 제공될 예정입니다. 최신 정보는 CLI 문서를 참조하세요.)

사용 가능한 기능을 탐색해 보세요:

unity --help

필요한 모듈과 함께 에디터를 설치하는 것은 한 줄로 끝납니다:

unity install 6000.2.10f1 -m android ios webgl

이후 명령어들은 예상하는 방식으로 작동합니다: unity editors를 사용하여 설치된 내용을 확인하고, unity open을 사용하여 적절한 에디터가 해결된 프로젝트를 실행하며, unity auth login을 사용하여 로그인할 수 있습니다. 특정 버전이 어떤 모듈 ID를 가지고 있는지 확실하지 않다면? unity modules list 6000.2.10f1 명령어가 도움을 줄 것입니다.

자동화에 최적화됨

CLI는 단순히 대화형 셸(shell) 내부가 아닌, 자동화 환경에서 작동하도록 구축되었습니다. 모든 명령어는 파이프를 통해 도구(tooling)로 바로 전달할 수 있는 구조화된 출력(structured output)을 생성할 수 있습니다:

unity editors --format json
unity editors --format tsv

오류는 stderr로, 결과는 stdout으로 전송되며, 종료 코드는 간단한 규칙(0 성공, 1 오류, 130 취소)을 따르므로 파이프라인에서 실패를 감지하기 쉽습니다.

수동 개입 없이 설치하려면 모든 프롬프트(prompt)를 건너뛰세요:

unity install 6000.2.10f1 -m android ios --accept-eula --yes

헤드리스 빌드 에이전트에서 실행될 경우, 환경 변수를 통해 서비스 계정으로 인증합니다. 브라우저나 수동 단계가 필요 없습니다. 그리고 unity doctor는 환경, 자격 증명(credential), 구성 문제를 진단해 줍니다.

Editor와 통신하기

설치 관리는 이야기의 절반에 불과합니다. Unity CLI는 실행 중인 Editor를 구동할 수도 있습니다.

프로젝트에 추가되면 com.unity.pipeline은 실행 중인 Editor가 사용자의 머신에서 CLI로부터 명령을 받을 수 있게 합니다. 이는 Unity 6.0 LTS 및 그 이후 버전에서 작동하며, Editor를 스크립트, CI 작업(CI jobs), 에이전틱 도구(agentic tools)를 위한 프로그래밍 가능한 자동화 대상으로 변환합니다.

프로젝트에 추가하는 것은 단 하나의 명령입니다:

unity pipeline install

unity pipeline list로 어떤 프로젝트가 이를 설치했는지 확인할 수 있습니다. 패키지가 준비되면, 연결된 Editor(또는 Player 런타임)에 등록된 명령을 터미널에서 직접 실행할 수 있습니다:

# 연결된 Editor가 노출하는 명령 목록 보기
unity command
# 그중 하나 실행하기
...

이러한 명령들은 고정된 세트가 아닙니다. 프로젝트의 모든 정적 메서드(static method)는 [CliCommand] 속성을 추가하고 매개변수에 *[CliArg]*를 붙임으로써 하나의 명령이 됩니다:

using Unity.Pipeline.Commands;
using UnityEngine;
public static class MyPipelineCommands
...

패키지는 등록 단계 없이 이를 자동으로 발견합니다. unity command greet --name World는 연결된 Editor에 대해 실행하고 결과를 반환합니다.

Pipeline 패키지는 오늘 이용 가능합니다. 현재 **실험적(experimental)**이므로, 변화할 것으로 예상해야 합니다. 이 패키지는 과거에는 Editor에서 사람이 필요했던 작업—임포트 트리거, 테스트 실행, 사용자 지정 도구 등—을 자동화할 수 있게 해줍니다.

에디터에서 그치지 않습니다. 런타임 컴포넌트를 개발 빌드에 드롭하면 실행 중인 게임이 동일한 종류의 API를 노출합니다. CLI를 사용하여 *unity command --runtime <플레이어 실행 이름>*으로 지정하여 실시간 로그를 가져오거나, 런타임 상태를 조회하거나, 이미 재생되고 있는 빌드의 코드를 핫 리로드할 수 있습니다. 이는 기본적으로 localhost 전용이며 (개발 및 QA 빌드에 한해서만, 절대 프로덕션 환경에서는 안 됩니다), 실행 중인 플레이어를 스크립트, 테스트 리그(test rig) 또는 AI 에이전트가 구동할 수 있는 무언가로 바꿔줍니다.

Unity CLI <-> 실행 중인 Editor를 com.unity.pipeline을 통해 연결

eval을 사용하여 C# 스크립트 실행

등록된 명령어들은 예상했던 작업을 다룹니다. unity command eval은 아직 예상하지 못한 작업까지 처리합니다. 이는 실행 중인 에디터 내부의 임의 C# 표현식을 평가하고 그 결과를 반환합니다. 즉, 터미널에서 프로젝트로 연결되는 실시간 Read-Eval-Print Loop (REPL)을 제공하는 것입니다.

unity command eval "return Application.version;"
unity command eval "return UnityEditor.EditorApplication.isPlaying;"
unity command eval "var s = Application.dataPath; return s.Length;" --json
...

이 기능은 Roslyn으로 컴파일되어 에디터의 메인 스레드에서 실행되므로, 프로젝트가 접근할 수 있는 모든 엔진 또는 에디터 API에 도달할 수 있습니다. 그리고 동일한 --runtime 플래그는 이를 라이브 플레이어에 겨냥합니다. 이 강력함이 양방향으로 작용하기 때문에, eval은 보안 토큰 뒤에 보호됩니다. 미리 정의된 명령어도 없고, 플러그인도 없고, 재컴파일할 필요도 없습니다. 만약 C#로 질문을 표현할 수 있다면, 실행 중인 Unity 인스턴스에게 물어볼 수 있습니다.

장점은 속도입니다. 일반적인 변경 및 확인 주기(편집, 재컴파일, 다시 시작)는 최소 몇 초가 걸리지만, eval은 이미 구동된 인스턴스를 대상으로 밀리초 단위로 답변합니다. 스크립트나 에이전트가 세션 동안 수행하는 많은 호출을 통틀어 이 차이는 누적되며, 이것이 바로 AI 에이전트에게 느린 피드백 루프 대신 긴밀한(tight) 피드백 루프를 제공하는 핵심입니다.

AI 지원 개발을 위한 기반 시설

이러한 구성 요소들(스크립터블 CLI, 프로그래밍 가능한 Editor, 실시간 REPL)은 단순한 편리함을 넘어섭니다. 이들이 바로 본문 상단의 데모를 가능하게 하는 것이며, Unity를 AI 에이전트가 실제로 작업할 수 있는 환경으로 만듭니다.

AI 코딩 어시스턴트는 코드와 콘텐츠 작성에는 능합니다. 하지만 프로젝트 실행, 오류 확인, 재시도 등 주변적인 모든 영역에서는 역사적으로 어려움을 겪어왔습니다. 어시스턴트는 게임플레이 스크립트를 생성할 수는 있지만, 그것이 작동하는지 테스트를 실행할 수는 없습니다. Unity CLI와 파이프라인 레이어는 이 간극을 메웁니다.

두 가지 속성이 차이를 만듭니다. 첫째, CLI는 에이전트가 이해하는 언어를 사용합니다. 구조화된 JSON과 예측 가능한 종료 코드(exit-code) 계약은 모델에게 스크랩된 콘솔 텍스트 대신 깨끗하고 파싱 가능한 결과를 제공한다는 의미입니다. CI에서 신뢰성을 높이는 것과 같은 자질들이 에이전트가 호출하는 도구로서의 신뢰성으로 이어집니다.

둘째, Pipeline 패키지는 Editor를 자체 설명적으로 만듭니다. 인자 없이 unity command를 실행하면 연결된 Editor가 노출하는 작업을 보고합니다. 에이전트는 하드코딩된 목록에 의존하기보다 런타임에 자신이 무엇을 할 수 있는지 발견합니다. 그리고 명령어가 간단한 속성(attributes)으로 등록되기 때문에, 팀은 프로젝트별 특정 작업을 에이전트가 호출할 수 있는 도구로 노출할 수 있습니다. 이는 각 등록된 명령어가 이미 에이전트가 어떻게 호출하는지 알고 있는 종류의 도구에 자연스럽게 매핑됨을 의미합니다.

이것들을 결합하면 실제 피드백 루프를 얻게 됩니다. 어시스턴트는 프로젝트를 열고, 변경 사항을 적용하고, 테스트를 실행하고, 동작 확인을 위해 Play 모드로 진입하며, 결과를 읽고, 다음에 무엇을 할지 결정할 수 있습니다. 이 모든 과정에서 인간이 출력을 주고받을 필요가 없습니다. 이것은 제안하는 어시스턴트에서 검증할 수 있는 어시스턴트로의 변화입니다. 또한 이는 새롭게 등장하는 에이전트 표준에도 자연스럽게 부합합니다. 각 등록된 명령어는 함수 호출(function-calling) 모델이나 MCP 서버가 이미 어떻게 호출하는지 알고 있는 종류의 도구에 매핑됩니다.

그리고 에이전트가 무엇을 할 수 있는지에 대한 고정된 목록은 없습니다. 왜냐하면 eval은 프로젝트가 호출할 수 있는 모든 API에 접근하기 때문에, 에이전트의 기능 표면(capability surface)은 Unity와 동일합니다. 즉 렌더링, 물리(physics), 애니메이션, 에셋 데이터베이스, Editor 자체, 그리고 사용자가 추가하는 모든 코드를 포함합니다. 이러한 도달 범위는 10년 이상의 API 작업의 결과이며, 에이전트는 별도의 통합 없이 이를 활용할 수 있습니다.

Unity 전체 API로 연결되는 하나의 파이프라인

우리는 이 여정의 초기에 있으며, 기본적인 요소들(primitives)은 이미 오늘날 존재합니다. Unity를 위한 AI 지원 도구(AI-assisted tooling)를 구축하고 있다면, Pipeline 패키지부터 시작하는 것이 좋습니다.

Unity의 AI 기능과의 관계

만약 사용자가 인-에디터 어시스턴트 스위트와 같은 Unity의 AI 기능을 사용한다면, 이것이 그 아래층을 구성합니다. Unity의 AI는 프로젝트에 대해 추론하고 무엇을 할지 결정하는 부분입니다. CLI와 Pipeline 패키지는 이러한 결정을 실행으로 옮기는 실행 표면(execution surface)이며, 빠르고 로컬하며 토큰 제한이 있습니다. 동일한 표면은 Unity 자체 도구가 MCP 서버를 통해 라우팅하든, 타사 어시스턴트가 사용하든, 아니면 사용자가 직접 작성하는 스크립트가 사용하든 모든 에이전트에게 열려 있습니다. Unity의 AI는 이 표면을 사용하는 소비자 중 하나일 뿐이며, 대체재가 아닙니다.

현재 이용 가능

Unity CLI가 출시되었습니다. 이를 설치하고 unity --help를 실행한 다음, 다음 빌드 스크립트나 CI 작업에 통합하거나 에이전트로 자동화할 수 있습니다. 문서에 전체 명령어 참조가 포함되어 있습니다. 무엇을 만들고 있는지 알려주세요. 여러분의 피드백은 다음 방향을 결정하는 데 도움이 됩니다.

안전 항구 성명(Safe harbor statement): 이 로드맵은 Unity가 제품군 개발에 대해 현재 가지고 있는 의도를 나타냅니다. 이는 정보 제공 목적으로만 제공되며, 특정 기능이나 기능을 제공하겠다는 약속이 아닙니다. 제공된 정보는 언제든지 변경될 수 있으며, Unity는 미래 출시의 내용, 시기 또는 성격에 대해 어떠한 보증도 하지 않습니다. 사용자는 이 로드맵을 비즈니스 중요 결정에 의존해서는 안 됩니다.