Quick Reference
unity-cli는 Unity 공식 CLI나 Codex 기능이 아니라 youngwoocho02/unity-cli가 배포하는 커뮤니티 도구입니다. Unity 프로젝트에 Connector를 넣고 실행 중인 Editor에 로컬 HTTP로 명령을 보내므로, 셸을 실행할 수 있는 Codex에서도 MCP 설정 없이 사용할 수 있습니다.
# 연결과 상태를 먼저 확인한다.
unity-cli status
unity-cli console --type error,warning,log
# 상태 변경은 완료를 기다리고, 결과를 다시 읽는다.
unity-cli editor play --wait
unity-cli test --mode EditMode
unity-cli console --type error,warning| 작업 | 명령 | 실행 전 확인 |
|---|---|---|
| 대상 Editor 확인 | unity-cli status | 여러 프로젝트가 열렸으면 --project 지정 |
| Play Mode 제어 | unity-cli editor play --wait | 현재 컴파일·도메인 리로드 상태 |
| 오류 확인 | unity-cli console --type error | 로그를 지우기 전 원인 보존 |
| 테스트 실행 | unity-cli test --mode EditMode | Unity Test Framework 설치 여부 |
| 임의 Editor 코드 | unity-cli exec "..." | 변경 대상, 되돌릴 방법, 실행 권한 |
설치와 연결
CLI 바이너리만 설치해도 Unity와 연결되지는 않습니다. 프로젝트에는 Git URL로 Unity Connector 패키지를 추가하고, Editor를 열어 Connector가 인스턴스를 등록하게 해야 합니다.
CLI 설치 -> unity-cli 실행 파일을 PATH에서 찾을 수 있어야 함
Unity Connector 설치 -> Packages/manifest.json 또는 Package Manager의 Git URL
Unity Editor 실행 -> Connector가 로컬 listener와 인스턴스 정보를 준비
status 확인 -> 명령 전에 프로젝트·Unity 버전·준비 상태를 확인공식 README의 Connector Git URL은 다음과 같습니다.
https://github.com/youngwoocho02/unity-cli.git?path=unity-connector여러 Editor가 열렸다면 자동 선택에 기대지 말고 대상 프로젝트를 지정합니다. 현재 문서의 전역 옵션은 --project <path>, --timeout <ms>, --ignore-version-mismatch이며, 마지막 옵션은 버전 불일치 검사를 건너뜁니다. 단순한 연결 오류를 숨길 수 있으므로, 진단 목적이 아니면 사용하지 않는 편이 낫습니다.
unity-cli --project /path/to/MyGame status
unity-cli --project /path/to/MyGame editor stopUnity가 백그라운드에서 Editor update를 제한하면 명령이 늦어질 수 있습니다. 이 도구를 지속적으로 자동화한다면 Unity Preferences의 Interaction Mode를 No Throttling으로 두는 것이 README의 권장값입니다.
명령별 책임
editor, console, test, menu, reserialize, screenshot, profiler는 정해진 Editor 작업을 호출합니다. list는 기본 도구와 프로젝트 custom tool의 입력 schema를 확인할 때 사용합니다. 명령 이름이 같아도 project custom tool은 프로젝트 코드이므로, 호출 전 schema와 구현을 확인해야 합니다.
# 테스트 이름은 부분 일치로 거를 수 있다.
unity-cli test --mode PlayMode --filter PlayerMovement
# 빌드 전 파일 저장 같은 명시적 메뉴 작업
unity-cli menu "File/Save Project"
# custom tool의 이름과 파라미터를 먼저 확인
unity-cli listexec는 예외입니다. UnityEditor, UnityEngine과 로드된 어셈블리에 접근하는 C#을 Editor에서 실행합니다. 조회라면 반환값을 명시해 읽기 작업으로 제한할 수 있지만, GameObject 생성·에셋 변경·메뉴 호출도 가능한 쓰기 표면입니다.
# 조회만 하는 예: 현재 씬 이름 반환
unity-cli exec "return EditorSceneManager.GetActiveScene().name;"프로젝트 타입을 쓰려면 필요한 namespace를 --usings로 추가할 수 있습니다. 셸 인용 문제를 피하려고 표준 입력으로 긴 코드를 넘길 수는 있지만, 코드 검토 없이 생성·삭제를 수행하게 해서는 안 됩니다.
안전한 자동화 흐름
status로 올바른 Unity 인스턴스와 준비 상태를 확인합니다.console --type error,warning으로 기존 실패를 읽고, 새 작업의 기준점을 남깁니다.- 읽기 또는 좁은 명령 하나를 실행합니다. Play Mode, 테스트,
exec는 완료를 기다립니다. - 콘솔과 테스트 결과를 다시 읽습니다. Editor 상태 변경만으로 성공 처리하지 않습니다.
editor refresh --compile과 PlayMode 테스트는 컴파일 또는 도메인 리로드를 유발할 수 있습니다. 완료 전에 곧바로 후속 명령을 보내면 timeout 또는 이전 상태의 결과를 받을 수 있습니다. --wait와 결과 확인을 한 쌍으로 둡니다.
Unity scene, asset, script와 test를 MCP tool로 직접 다루려면 MCP for Unity를 사용합니다. unity-cli의 Connector는 로컬 Go process를 통해 Editor와 통신하는 별도 구성으로, 두 도구의 설정·배포 주체·권한 흐름을 섞지 않습니다.
참고 링크
1 sources