CLI 개요
터미널에서 실행하는 moai (Go 바이너리) 의 명령어와 플래그를 한눈에 정리했습니다. Claude Code 대화창에서 입력하는 /moai (슬래시 서브커맨드) 와는 완전히 다른 도구이며, 이 페이지는 터미널 CLI 만 다룹니다.
moai CLI 가 책임지는 것은 “Claude Code 세션 바깥에서 일어나는 일” 입니다. 프로젝트 폴더를 만들고, 템플릿을 배포하고, 설정 파일을 동기화하고, 진단을 돌리고, 세션과 워크트리를 조율하는 일은 모두 Claude Code 대화가 시작되기 전에 터미널에서 이루어집니다. 반면 Claude Code 대화창 안에서 요구사항을 쓰고 SPEC 을 만들고 구현을 돌리는 일은 /moai 슬래시 서브커맨드의 영역입니다. 두 도구는 같은 moai 라는 이름을 공유할 뿐, 동작하는 층이 다릅니다 — 이 구분이 MoAI-ADK 를 처음 쓸 때 가장 흔한 혼동 포인트이므로, 자주 묻는 질문 에서도 따로 짚습니다.
이 페이지는 명령어 전체를 훑어보는 뷰입니다. 각 명령어의 플래그와 하위 명령어를 깊이 있게 보려면 CLI 레퍼런스 섹션의 커맨드별 페이지를 참조하세요.
moai --helpmoai CLI는 세 그룹으로 나뉩니다.
| 그룹 | 명령어 | 설명 |
|---|---|---|
| Launch | moai cc · moai glm | Claude Code 세션 시작 (백엔드 선택) |
| Project | moai init · moai update · moai doctor · moai status | 프로젝트 초기화, 업데이트, 진단, 상태 조회 |
| Tools | moai profile · moai inventory · moai hook · moai worktree · moai spec · moai harness · … | 설정, 인벤토리, 훅, 워크트리 등 도구 |
moai version 으로 현재 설치된 버전을 확인합니다.
moai version╭────────────────────────╮
│ │
│ moai-adk v3.0.0 │
│ │
│ │
╰────────────────────────╯
v3.0.0 none built unknown박스 배너 아래 줄은 <버전> <커밋 해시> built <빌드 시각> 순서로 표시됩니다. go install 처럼 ldflags 없이 빌드했다면 커밋은 none, 빌드 시각은 unknown 으로 나옵니다.
프로젝트를 초기화합니다. 대화형 마법사가 언어, Git 자동화, 모델 정책, 하네스 프로필 등을 설정합니다.
moai init [project-name] [OPTIONS]| 플래그 | 설명 |
|---|---|
--non-interactive | 대화형 마법사 건너뛰기 (플래그와 기본값 사용) |
--force | 기존 프로젝트 강제 재초기화 (현재 .moai/ 백업) |
--no-hooks | Git 훅 설치 건너뛰기 |
--all | 카탈로그 전체 항목 배포 (core + optional packs + harness-generated) |
--mode <ddd|tdd> | 개발 방법론 (기본값: tdd) |
--language <lang> | 주 프로그래밍 언어 |
--framework <name> | 프레임워크 이름 (기본값: 자동 감지 또는 “none”) |
--name <name> | 프로젝트 이름 (기본값: 디렉터리 이름) |
--root <path> | 프로젝트 루트 디렉터리 (기본값: 현재 디렉터리) |
--git-mode <manual|personal|team> | Git 워크플로우 모드 (기본값: manual) |
--git-provider <github|gitlab> | Git 제공자 |
--enable-lsp | LSP 연동 활성화 (기본값: true) |
--enforce-quality | 품질 게이트 강제 (기본값: true) |
--enable-design | 디자인 워크플로우 활성화 (기본값: true) |
--profile <high|medium|low> | 지원 종료 스텁 — 스크립트 호환을 위해 값만 받고 아무 효과가 없으며, moai profile setup을 가리키는 지원 종료 경고를 냅니다 |
--model-policy <high|medium|low> | 지원 종료 스텁 — 스크립트 호환을 위해 값만 받고 아무 효과가 없으며, moai profile setup을 가리키는 지원 종료 경고를 냅니다 |
--high | 지원 종료 스텁 — 사라진 --model-policy high의 별칭. 같은 지원 종료 경고를 냅니다 |
# 새 프로젝트 초기화 (대화형 마법사)
moai init my-project
# 기존 폴더에 설치
cd my-existing-project
moai init
# 비대화형 (CI/CD)
moai init --non-interactive자세한 마법사 단계는 초기 설정 페이지를 참조하세요.
MoAI-ADK를 최신 버전으로 업데이트합니다. 플래그 없이 실행하면 바이너리와 템플릿을 함께 갱신하고, 사용자가 직접 만든 자산은 알아서 보존합니다.
moai update [OPTIONS]| 플래그 | 설명 |
|---|---|
--check | 새 버전이 있는지만 확인 (업데이트 안 함) |
-c, --config | 설정 마법사 다시 실행 (템플릿 동기화 안 함) |
--force | 강제 업데이트 (버전 일치 스킵, 백업+병합 강제, 아카이브 드리프트 덮어쓰기) |
--yes | 모든 확인 자동 승인 (CI/CD 모드) |
--templates-only | 바이너리 업데이트 건너뛰고 템플릿만 동기화 |
--binary | 템플릿 동기화 건너뛰고 바이너리만 업데이트 |
--dry-run | 파일시스템 변경 없이 계획된 작업만 표시 |
--no-hooks | Git 훅 설치 건너뛰기 |
--verbose | 모든 경고 표시 (진단 모드) |
--shell-env | Claude Code 용 셸 환경변수 구성 |
--profile <high|medium|low> | 지원 종료 스텁 — 스크립트 호환을 위해 값만 받고 아무 효과가 없으며, moai profile setup을 가리키는 지원 종료 경고를 냅니다 |
# 기본 업데이트 (바이너리 + 템플릿)
moai update
# 새 버전이 있는지 확인만
moai update --check
# 설정 마법사 다시 실행
moai update -c
# 템플릿만 동기화
moai update --templates-only자세한 업데이트 절차는 업데이트 페이지를 참조하세요.
시스템 진단을 실행합니다. Git, 프로젝트 구조, 설정 파일, 언어별 개발 도구를 검사합니다.
moai doctor [OPTIONS]| 플래그 | 설명 |
|---|---|
-v, --verbose | 상세 도구 버전 및 언어 감지 결과 표시 |
--fix | 누락 도구 수정 제안 |
--export <path> | 진단 결과를 JSON 파일로 내보내기 |
--check <tool> | 특정 도구만 확인 (예: git, go, config) |
| 명령어 | 설명 |
|---|---|
moai doctor sandbox | 샌드박스 백엔드 가용성 진단 |
moai doctor permission | 권한 해석 진단 |
moai doctor hook | 30개 훅 이벤트 커버리지 표 표시 |
moai doctor config dump | 병합된 설정을 provenance 와 함께 덤프 |
moai doctor config diff <tier-a> <tier-b> | 두 설정 티어를 비교 |
# 전체 진단
moai doctor
# 상세 진단
moai doctor --verbose
# 진단 결과 내보내기
moai doctor --export diagnostics.json프로젝트 상태를 한눈에 조회합니다. 초기화 여부, SPEC 개수, 설정 파일 수를 표시합니다.
moai status플래그가 없는 읽기 전용 명령어입니다. 자세한 출력 내용은 프로젝트 상태 페이지를 참조하세요.
활성 세션, 워크트리, 하네스를 통합 조회하는 읽기 전용 명령어입니다.
moai inventory [OPTIONS]| 플래그 | 설명 |
|---|---|
--json | 구조화된 JSON 출력 |
--project-root <path> | 프로젝트 루트 경로 (기본값: 현재 디렉터리) |
자세한 JSON 스키마와 활용 예시는 moai inventory 페이지를 참조하세요.
Claude Code 설정 프로필을 관리합니다. 프로필마다 모델·언어·표시 설정을 따로 둘 수 있습니다.
moai profile [COMMAND]| 명령어 | 설명 |
|---|---|
moai profile list | 사용 가능한 모든 프로필 표시 |
moai profile setup | 대화형 설정 마법사 실행 |
moai profile current | 현재 활성 프로필 표시 |
moai profile delete <name> | 지정된 프로필 삭제 |
프로필 실행은 -p 플래그로 지정합니다:
moai cc -p work # work 프로필로 Claude 실행
moai glm -p cost-save # cost-save 프로필로 GLM 실행자세한 내용은 프로필 관리 페이지를 참조하세요.
Claude Code 훅 이벤트를 처리하는 디스패처입니다. settings.json 의 훅 설정에서 moai hook <event> 형태로 호출됩니다.
moai hook <event>moai hook 디스패처에는 표준 Claude Code 훅 이벤트와 MoAI 전용 내부 액션을 합쳐 42개의 서브커맨드가 있습니다. 이름은 모두 kebab-case 입니다. 아래는 대표적인 이벤트입니다.
훅 이벤트 수와 서브커맨드 수는 다릅니다.
moai doctor hook이 보여 주는 30개는 Claude Code가 정의한 훅 이벤트 종류이고, 여기 42개는moai hook이 받는 서브커맨드 수입니다. MoAI 전용 내부 액션이 이벤트 없이도 서브커맨드로 존재하기 때문에 두 숫자는 일치하지 않습니다.
| 이벤트 | 설명 |
|---|---|
session-start | 세션 시작 |
session-end | 세션 종료 |
pre-tool | 도구 실행 전 (PreToolUse) |
post-tool | 도구 실행 후 (PostToolUse) |
post-tool-failure | 도구 실행 실패 후 |
stop | 세션 정지 |
stop-failure | 정지 실패 |
compact | 컨텍스트 압축 전 (PreCompact) |
post-compact | 컨텍스트 압축 후 |
notification | 시스템 알림 |
subagent-start | 서브에이전트 시작 |
subagent-stop | 서브에이전트 종료 |
user-prompt-submit | 사용자 프롬프트 제출 |
permission-request | 권한 요청 |
permission-denied | 권한 거부 |
teammate-idle | 팀원 유휴 상태 |
task-completed | 작업 완료 |
task-created | 작업 생성 |
worktree-create | 워크트리 생성 |
worktree-remove | 워크트리 제거 |
instructions-loaded | 인스트럭션 로드 완료 |
config-change | 설정 변경 |
cwd-changed | 작업 디렉토리 변경 |
file-changed | 파일 변경 |
elicitation | MCP elicitation 요청 |
elicitation-result | MCP elicitation 결과 |
MoAI 전용 서브커맨드도 포함됩니다.
| 서브커맨드 | 설명 |
|---|---|
stop-goal | 턴 종료 시 활성 세션 goal 평가 |
pre-push | 커밋 메시지를 컨벤션에 맞게 검증 |
spec-status | git 커밋 시 SPEC status 자동 갱신 |
harness-classify | 하네스 분류기 실행 및 티어 승급 기록 |
harness-observe · harness-observe-stop · harness-observe-subagent-stop · harness-observe-user-prompt-submit | 하네스 사용 로그 기록 |
훅은 사용자가 직접 실행하지 않습니다 — Claude Code의 settings.json 이 자동으로 호출합니다.
Git worktree를 관리해 여러 SPEC을 병렬로 개발합니다.
moai worktree <COMMAND> [ARGS]...| 명령어 | 설명 |
|---|---|
moai worktree sync [branch-name] | base 브랜치와 worktree 동기화 |
moai worktree done <branch-name> | 브랜치의 worktree 제거, 선택적으로 브랜치 삭제 |
moai worktree remove <path> | 지정 경로의 worktree 제거 |
moai worktree clean | stale 참조 정리, 병합된/방치된 worktree 정리 |
moai worktree recover | worktree 레지스트리 복구 |
moai worktree snapshot | 작업 트리 상태 스냅샷 캡처 |
moai worktree verify | 작업 트리 상태를 스냅샷과 대조 검증 |
moai worktree restore | 스냅샷 HEAD 상태로 작업 트리 복원 |
워크트리 안으로 들어가는 일은 런처가 맡습니다. 조회는 git 을 그대로 씁니다.
moai cc -w feat-login # 워크트리에서 작업 시작 (없으면 생성)
moai cc -w feat-login --spawn # 현재 세션은 두고 새 tmux 창에서 열기
git worktree list # 워크트리 목록moai cc와 moai glm은 선택한 백엔드로 Claude Code를 실행합니다. 기존 CG 설정은 실행 전에 이전해야 합니다.
moai cc [-p profile] [-- claude-args...]
moai glm [-p profile] [-- claude-args...]moai cg는 폐기되었습니다. Claude나 GLM을 실행하지 않고 설정 이전 안내와 함께 종료합니다. moai cc의 별칭이 아닙니다. llm.team_mode: cg가 남은 프로젝트는 세션을 실행하기 전에 이전할 구성을 명시적으로 선택해야 합니다. CG 폐기와 설정 이전
세 런치 명령어가 공통으로 지원하는 플래그입니다.
| 플래그 | 설명 |
|---|---|
-p, --profile <name> | 이름 있는 Claude 프로필 사용 |
--permission-mode <mode> | 권한 모드 (default, acceptEdits, plan, auto, bypassPermissions, dontAsk) |
-b, --bypass | --permission-mode bypassPermissions 단축 |
moai cc 는 추가로 다음 플래그를 지원합니다.
| 플래그 | 설명 |
|---|---|
-c, --continue | 이전 세션 이어가기 |
-m, --model <model> | 모델 선택 덮어쓰기 |
--chrome / --no-chrome | Claude Code 에 그대로 전달합니다. 런처가 스스로 붙이지 않으므로 --no-chrome 을 넘기지 않는 한 /chrome 으로 연결할 수 있습니다 |
auto권한 모드는 GLM(제3자 제공자)에서는 사용할 수 없습니다 —moai cc에서만 지원됩니다.
moai cc는 세션 모델을 위에서부터 차례로 찾고, 처음 나온 값을 --model로 Claude Code에 넘깁니다.
- 명시한
--model인자 - 프로필의 모델(
moai profile setup에서 고른 값) - 환경변수
ANTHROPIC_MODEL(이번 실행에만 적용) - 프로젝트
.claude/settings.local.json의model(이 프로젝트에만 적용) - 그 프로필의 사용자 범위
settings.json에/model로 저장해 둔 값 — 실행 때model: opus (user /model)한 줄로 알려 줍니다 - 위가 모두 비어 있으면 아무것도 넘기지 않습니다. 이때는 프로젝트
.claude/settings.json의model핀이 세션 모델이 되고, 런처가 그 값과 바꾸는 방법을 알려 줍니다
더 구체적이고 더 최근에 직접 지정한 쪽이 이깁니다. 3번과 4번은 Claude Code가 직접 적용하므로 런처는 --model을 넘기지 않고 비켜 줍니다. 프로젝트 설정은 사용자 범위 설정보다 우선하므로, 5번 단계가 없으면 /model로 고른 모델이 프로젝트 핀에 가려집니다. moai glm은 이 규칙을 따르지 않습니다. GLM은 모델을 슬롯 별칭으로 넘겨야 하고, Anthropic 계정에서 /model로 고른 값은 다른 모델 계열이라 엉뚱한 슬롯으로 연결되기 때문입니다.
| 명령어 | 설명 |
|---|---|
moai glm setup <api-key> | GLM API 키 저장 |
moai glm status | 현재 GLM 자격증명 상태 표시 |
moai glm tools | Z.AI MCP 서버 도구 관리 (활성/비활성) |
현재 세션에 조건 기반 자율 goal 루프를 등록·조회·해제합니다. 조건이 충족될 때까지 매 턴 종료 시 평가됩니다.
moai goal <COMMAND>| 명령어 | 설명 |
|---|---|
moai goal arm <condition> | 활성 세션에 goal 등록·활성화 |
moai goal status | 활성 세션의 goal 상태 출력 |
moai goal clear | 활성 세션의 goal 해제 |
/clear 경계를 넘어 세션을 이어가기 위한 auto-resume 핸드오프 대기 레코드를 관리합니다.
moai handoff <COMMAND>| 명령어 | 설명 |
|---|---|
moai handoff save | 붙여넣기용 resume 본문을 대기 레코드로 저장 |
moai handoff clear | 대기 핸드오프 레코드 제거 |
여러 세션이 서로 부딪히지 않도록 활성 세션 조율 레지스트리를 관리합니다.
moai session <COMMAND>| 명령어 | 설명 |
|---|---|
moai session current | 현재 오케스트레이터 세션 UUID 출력 |
moai session list | 활성 세션 목록 (--filter-spec 로 필터링 가능) |
moai session register <session_id> <spec_id> <phase> | 레지스트리에 세션 등록 |
moai session deregister <session_id> | 레지스트리에서 세션 제거 (idempotent) |
moai session heartbeat <session_id> | 세션 last_heartbeat 갱신 |
moai session purge | 오래된 항목 제거 (기본값: 마지막 heartbeat 30분 초과) |
moai session doctor | 세션 레지스트리가 비어 있는 원인 진단 |
브라우저에서 쓰는 설정 편집기, MoAI Web Console을 실행합니다.
moai web [OPTIONS]| 플래그 | 설명 |
|---|---|
--port <N> | 127.0.0.1 에 바인딩할 TCP 포트 (기본값: 3041) |
--no-open | 브라우저 자동 열기 안 함 |
--no-reuse | 오래된 moai 인스턴스로부터 포트 회수 안 함 |
버전, 커밋 해시, 빌드 날짜를 표시합니다.
moai version
moai --version # 동일에이전트마다 모델을 배정하던 예전의 성능 티어 시스템은 물러났습니다. v3.2부터 서브에이전트는 메인 세션의 모델과 추론 깊이를 그대로 따릅니다 — 서브에이전트를 부를 때 model도 effort도 넘기지 않으며, MoAI 에이전트 정의는 어느 쪽도 선언하지 않습니다. 모델 정책의 자리에 남은 것은 세션 수준 선택 하나입니다. moai profile setup의 세션 모델 정책 질문은 이 프로필로 실행하는 Claude 세션의 기본 추론 강도(추론 강도를 따로 고르지 않았을 때의 폴백)를 정합니다.
| 예전 값 | 지금의 의미 |
|---|---|
| high | 세션 effort 폴백 high |
| medium | 세션 effort 폴백 medium |
| low | 세션 effort 폴백 low |
# 세션 모델 정책을 포함한 프로필 전체 설정
moai profile setup
# 사라진 에이전트별 플래그는 지원 종료 경고만 내고 아무 효과가 없습니다
moai init my-project --model-policy high예전의 --model-policy, --profile, --high, --medium-alias, --low 플래그는 지원 종료 스텁입니다. 값은 스크립트 호환을 위해 받아들이지만 아무 효과가 없고 moai profile setup을 안내하는 경고를 냅니다. 세션 수준의 모델·effort 조절은 모델 정책 페이지, 매트릭스의 물러남은 프로필 매트릭스 페이지를 참조하세요.