CLI 레퍼런스

MoAI-ADK 명령줄 인터페이스의 모든 명령어와 옵션을 참조하세요.

명령어 목록

moai --help

출력 예시:

MoAI-ADK - Agentic Development Kit for Claude Code

Usage:
  moai [command]

Available Commands:
  init        Interactive project setup (auto-detects language/framework/methodology)
  doctor      System health diagnosis and environment verification
  status      Project status summary including Git branch, quality metrics, etc.
  update      Update to the latest version (with automatic rollback support)
  worktree    Manage Git worktrees for parallel SPEC development
  hook        Claude Code hook dispatcher
  profile     Manage Claude Code configuration profiles
  glm         Switch to GLM backend (cost-effective) or update API key
  claude      Switch to Claude backend (Anthropic API)
  version     Display version, commit hash, and build date

Flags:
  -h, --help      help for moai
  -v, --version   version for moai

moai init

프로젝트를 초기화합니다.

moai init [PATH] [OPTIONS]

옵션

예시

# 새 프로젝트 초기화
moai init my-project
 
# 한국어, 팀 모드
moai init my-project --locale ko --mode team
 
# Python 프로젝트
moai init --language python

moai update

MoAI-ADK를 최신 버전으로 업데이트합니다.

moai update [OPTIONS]

옵션

예시

# 업데이트 확인
moai update --check
 
# 강제 업데이트
moai update --force
 
# 자동 병합
moai update --merge

moai doctor

시스템 진단을 실행합니다.

moai doctor [OPTIONS]

옵션

예시

# 전체 진단
moai doctor
 
# 상세 진단
moai doctor --verbose
 
# 수정 제안
moai doctor --fix

moai profile

Profile을 관리합니다. Profile은 독립된 Claude Code 구성 환경을 제공합니다.

Profile 하위 명령어

moai profile list

moai profile list

사용 가능한 모든 Profile과 현재 활성 Profile을 표시합니다.

moai profile setup

moai profile setup

대화형 마법사가 새 Profile을 생성합니다:

1. Profile 이름: 고유 식별자 (예: work, personal)
2. 사용자 이름: Claude Code가 사용자를 지칭할 이름
3. 언어 설정:
   • 대화 언어 (conversation_language)
   • Git 커밋 언어 (git_commit_lang)
   • 코드 주석 언어 (code_comment_lang)
   • 문서 언어 (doc_lang)
4. 모델 설정:
   • 모델 정책 (model_policy): high, medium, low
   • 기본 모델 (model): inherit, opus, sonnet, haiku, 1M context 모델
5. 실행 설정:
   • 권한 모드 (permission_mode): default, acceptEdits
6. 표시 설정:
   • 상태줄 모드 (statusline_mode): off, basic, full
   • 상태줄 테마 (statusline_theme): auto, light, dark, monokai, nord, dracula
   • 팀원 표시 (teammate_display): auto, in-process, tmux

moai profile current

moai profile current

현재 활성화된 Profile 정보를 표시합니다.

moai profile delete

moai profile delete <name>

지정된 Profile과 해당 디렉토리를 삭제합니다.

Profile 실행

Profile을 사용하여 MoAI 명령을 실행하려면 -p 플래그를 사용합니다:

# Claude 모드에서 특정 Profile 사용
moai cc -p work
 
# GLM 모드에서 특정 Profile 사용
moai glm -p personal
 
# CG 모드에서 특정 Profile 사용
moai cg -p team-project

Profile의 Claude Code 설정이 해당 세션에 적용됩니다.

Profile vs MoAI Worktree

moai glm

GLM 백엔드로 전환하거나 API 키를 업데이트합니다.

moai glm [OPTIONS] [API_KEY]

옵션

사용법

# GLM 백엔드 전환
moai glm
 
# API 키 업데이트
moai glm <api-key>
 
# Profile 지정 실행
moai glm -p work
 
# GLM Worker 모드 시작 (비용 효율적 팀 개발)
moai glm --team
 
# z.ai에서 API 키 발급받기
# https://z.ai/subscribe?ic=1NDV03BGWU

GLM Worker 모드

--team 옵션을 사용하면 비용 효율적인 GLM Worker 모드가 시작됩니다:

• 구성: Opus 모델의 리더 에이전트 + GLM-5 모델의 팀원 에이전트
• 장점: Claude 대비 70% 비용 절감, 동등한 성능
• 용도: 대규모 팀 기반 개발 시 토큰 비용 최적화

Profile 기반 설정 (v2.7.0+)

moai glm, moai cc, moai cg는 이제 영구 Profile을 지원하는 로그인 명령어입니다. Profile은 ~/.moai/claude-profiles/에 저장됩니다.

• 최초 실행 시 대화형 Profile 설정 마법사 제공
• Profile이 세션 간 유지됨
• moai glm에서 moai cg로 전환 시 GLM 설정 자동 초기화

moai claude

Claude 백엔드(Anthropic API)로 전환합니다.

$ moai claude [OPTIONS]
# 또는 단축어
$ moai cc [OPTIONS]

옵션

사용법

# Claude 백엔드 전환
moai cc
 
# Profile 지정 실행
moai cc -p work

moai cg

CG 모드 (Claude + GLM 하이브리드) 를 활성화합니다. 리더는 Claude API를, 팀원은 GLM API를 사용하며 tmux 세션 레벨 환경 변수 격리로 구현됩니다.

moai cg [OPTIONS]

옵션

작동 방식

1. GLM 설정을 tmux 세션 환경에 주입
2. settings에서 GLM 환경 제거 — 리더 창은 Claude API 사용
3. CLAUDE_CODE_TEAMMATE_DISPLAY=tmux 설정 — 팀원은 새 창에서 GLM 환경 상속

사용법

# 1. GLM API 키 저장 (최초 1회)
moai glm sk-your-glm-api-key
 
# 2. CG 모드 활성화 (tmux 내에서 실행)
moai cg
 
# 3. 같은 창에서 Claude Code 시작
claude
 
# 4. 팀 워크플로우 실행
/moai --team "작업 설명"
 
# Profile 지정 실행
moai cg -p team-project

주의사항

모드 비교

디스플레이 모드

moai status

프로젝트 상태를 확인합니다.

moai status

출력 예시:

╭────── Project Status ──────╮
│   Mode          personal   │
│   Locale        unknown    │
│   SPECs         1          │
│   Branch        main       │
│   Git Status    Modified   │
╰────────────────────────────╯

출력 정보:

• Mode: 작업 모드 (personal, team, manual)
• Locale: 언어 설정
• SPECs: 활성 SPEC 개수
• Branch: 현재 브랜치
• Git Status: Git 상태 (Clean, Modified)

moai worktree

Git worktree를 관리하여 병렬 SPEC 개발을 수행합니다.

moai worktree [OPTIONS] COMMAND [ARGS]...

하위 명령어

moai worktree new

새 worktree를 생성합니다.

moai worktree new [OPTIONS] SPEC_ID

옵션

예시

# SPEC-001을 위한 worktree 생성
moai worktree new SPEC-001
 
# 사용자 브랜치 지정
moai worktree new SPEC-001 --branch feature-auth
 
# 기본 브랜치 변경
moai worktree new SPEC-001 --base develop

moai worktree list

활성 worktree 목록을 표시합니다.

moai worktree list [OPTIONS]

옵션

moai worktree remove

worktree를 제거합니다.

moai worktree remove [OPTIONS] SPEC_ID

옵션

worktree 워크플로우

moai hook

MoAI-ADK 이벤트를 위한 Claude Code 훅 디스패처입니다.

moai hook <event>

지원 이벤트 (16개)

예시

# PreToolUse 훅 실행
moai hook PreToolUse
 
# PostToolUse 훅 실행
moai hook PostToolUse
 
# 사용자 프롬프트 제출 훅
moai hook UserPromptSubmit

Statusline v3

MoAI Statusline v3는 Claude Code 상태줄에 실시간 API 사용량을 표시합니다.

v3 새로운 기능

색상 그라데이션

사용량 비율에 따라 색상이 부드럽게 변합니다:

• 0-30%: Green → Yellow (안전)
• 31-70%: Yellow → Orange (주의)
• 71-100%: Orange → Red (한계 근접)

API 사용량 표시

5H: 45K/200K (22%) | 7D: 180K/500K (36%)

• 5H: 최근 5시간 사용량
• 7D: 최근 7일 사용량
• 비율: 현재 할당량 대비 사용 비율

설정 방법

Profile 설정 마법사(moai profile setup)에서 다음 옵션을 선택:

1. statusline_mode: off, basic, full
2. statusline_theme: auto, light, dark, monokai, nord, dracula

사용법

# Profile 생성 시 Statusline 설정
moai profile setup
# → statusline_mode: full 선택
# → statusline_theme: auto 선택
 
# Profile과 함께 실행
moai cc -p my-profile

Task 메트릭 로깅

MoAI-ADK는 개발 세션 중 Task 도구 메트릭을 자동으로 캡처합니다.

로그 파일

• 위치: .moai/logs/task-metrics.jsonl
• 형식: JSONL (JSON Lines)

캡처 메트릭

활용

• 세션 분석 및 성능 최적화
• 에이전트 효율성 분석
• 토큰 소비 추적 및 비용 관리

Task 도구 완료 시 PostToolUse 훅이 메트릭을 자동으로 로깅합니다.

모델 정책 설정

MoAI-ADK는 Claude Code 구독 요금제에 맞춰 에이전트에 최적의 AI 모델을 할당합니다.

정책 티어

설정 방법

# 프로젝트 초기화 시 (대화형 마법사)
moai init my-project
 
# 기존 프로젝트 재설정
moai update -c
 
# 수동 설정 (.moai/config/sections/user.yaml)
# model_policy: high | medium | low

참고: 기본 정책은 High입니다. moai update 실행 후 moai update -c로 설정을 구성하세요.

1M 컨텍스트 모델

Profile 설정 중 기본 모델 선택 시 1M 컨텍스트 모델을 선택할 수 있습니다:

• claude-opus-4-6 1M context
• claude-sonnet-4-6 1M context

이 모델들은 대용량 코드베이스 분석이나 긴 문서 작업에 적합합니다.

환경 변수

참고

• 빠른 시작
• 설치
• 업데이트
• Profile