경고: 알파 품질 소프트웨어입니다. 이 프로젝트는 초기 단계이며 AI 코딩 어시스턴트와 함께 상당 부분 '느낌'으로 제작되었습니다. 버그, 누락된 기능, 거친 부분이 있을 수 있습니다. mxcli는 Mendix 프로젝트 파일을 손상시킬 수 있으므로 항상 사본에서 작업하거나 버전 관리를 사용하십시오. 자체 위험 부담 하에 사용하세요. 이 도구는 Mendix 11.6을 기준으로 개발 및 테스트되었으며, 다른 버전은 현재 검증되지 않았습니다.
Studio Pro에서 mxcli를 사용하여 프로젝트를 편집하지 마십시오. Studio Pro는 외부적으로 업데이트할 수 없는 메모리 캐시를 유지합니다. 먼저 Studio Pro에서 프로젝트를 닫고, mxcli를 실행한 다음, 프로젝트를 다시 여십시오.
AI 코딩 어시스턴트(Claude Code, GitHub Copilot, OpenCode, Cursor, Continue.dev, Windsurf, Aider 등)가 Mendix 애플리케이션 프로젝트를 읽고, 이해하고, 수정할 수 있도록 하는 명령줄 도구입니다.
문서 보기 | 부트스트랩 프롬프트 사용 -- Mendix 프로젝트를 가장 빠르게 시작하는 방법: 빈 리포지토리에 Claude Code 클라우드 세션에 붙여넣기만 하면 되며, 로컬 설치가 필요하지 않습니다.
배너를 클릭하여 대화형 버전을 여세요.
Mendix 프로젝트는 AI 에이전트가 직접 읽을 수 없는 바이너리 .mpr 파일에 저장됩니다. mxcli는 다음 기능을 제공함으로써 이 격차를 해소합니다:
MDL (Mendix Definition Language) - Mendix 모델을 쿼리하고 수정하기 위한 SQL과 유사한 구문
다중 도구 지원 - Claude Code, GitHub Copilot, OpenCode, Cursor, Continue.dev, Windsurf, Aider 등과 작동합니다
전체 텍스트 검색 - 모든 문자열, 메시지 및 소스 정의에 걸쳐 검색
코드 탐색 - 호출자(callers), 피호출자(callees), 참조(references) 및 영향 분석(impact analysis) 찾기
카탈로그 쿼리 - 프로젝트 메타데이터의 SQL 기반 쿼리
린팅 (Linting) - 일반적인 문제를 확인하여 프로젝트 검사
Unix 파이프 지원 - 스크립팅 및 체이닝을 위해 설계된 출력 형식
mxcli는 단 하나의 가정 위에 구축되었습니다. 즉, 에이전트가 간결하고 사람이 읽기 쉬운 DSL(Domain Specific Language)을 작성하면, mxcli의 결정론적 계층이 실제 모델 변경에 필요한 수많은 저수준 변형(mutations), 유효성 검사(validations), 및 도구 호출로 변환하는 것입니다. 다음은 차별화 요소들입니다:
토큰 효율성(Token efficiency) - 에이전트가 여러 개의 작고 장황한 도구 호출 대신, 하나의 더 큰 MDL 스크립트를 방출합니다. MDL은 원시 모델 JSON보다 5~10배 밀도가 높으며, 하나의 스크립트는 하나의 모델 턴을 의미하므로, 오케스트레이션(orchestration) 오버헤드가 적어 비용이 낮고 실행 속도가 빠릅니다.결정론적 레이어의 복잡성(Complexity in the deterministic layer) - 하나의 MDL 구문은 여러 문서(또는 MCP 도구 호출)에 결정론적으로 매핑됩니다. LLM이 의도를 명시하면, mxcli가 팬아웃(fan-out), 순서 지정, 그리고 읽기-수정-쓰기(read-modify-write) 장부를 처리합니다.인간이 읽을 수 있는 DSL - MDL은 SQL, Ada, PL/SQL에서 영감을 받았습니다. LLM이 생성한 스크립트는 사람이 검토하고, 감사하며, 작성하기 쉽습니다. 읽기 쉬운 코드는 검토 가능한 코드입니다.헤드리스 에이전트 루프(Headless agentic loop) - Studio Pro를 열 필요 없이 Mendix 애플리케이션을 구축하고 테스트할 수 있습니다.대규모 애플리케이션 이해 - 쿼리 가능한 카탈로그와 의존성 그래프 테이블 덕분에 에이전트가 간단한 SQL을 통해 복잡한 앱을 탐색할 수 있습니다.정밀한 스킬(Precise skills) - 구체적인 DSL은 스킬 파일이 정확히 어떤 MDL을 생성해야 하는지에 대한 특정하고 복사 가능한 예시를 포함하도록 하여, 더 신뢰할 수 있는 출력을 만듭니다.안전성을 갖춘 강력함(Power with safety) - mxcli init는 에이전트가 볼 수 있고, 할 수 있고, 수정할 수 있는 범위를 정확하게 제한하는 Dev Container를 제공합니다. 결정론적 검증(Deterministic verification) - mxcli check와 mxcli lint는 생성된 프로젝트를 결정론적 규칙에 따라 검증하며, LLM의 판단을 배제하여 피드백 루프를 빠르고 신뢰할 수 있게 유지합니다.장기적으로: 더 작은 로컬 모델 - 제약된 DSL을 생성하는 것이 도구 호출을 오케스트레이션하는 것보다 LLM에게 간단하며, 문법(grammar)은 문법 제약 디코딩(grammar-constrained decoding)을 통해 강제할 수 있습니다. 전체적인 근거는 문서의 설계 원칙(Design Principles)을 참조하십시오.Mxcli는 다음과 같은 사용 사례 중 일부를 가능하게 하는 도구입니다. MDL, Mendix Definition Language는 Studio Pro의 시각적 모델과 동일한 추상화 수준에서 텍스트 기반 모델을 제공하는 DSL입니다. Mxcli 명령줄 도구를 사용하여 프로젝트에 대해 명령을 실행함으로써 프로젝트를 조사하고 변경할 수 있습니다.
repl 모드에서 mxcli를 사용하면 Mendix 프로젝트와 대화형으로 작업할 수 있습니다. 이는 데이터베이스 작업을 할 때 psql이나 sqlplus를 사용하는 것과 유사합니다. 사용 가능한 Mendix 문서 목록을 확인하고, MDL 소스를 보고, 변경 사항을 적용할 수 있습니다.
mxcli init을 실행하면 AGENTS.md, CLAUDE.md 및 Mendix 전용 스킬 같은 에이전트 코딩 도구를 위한 설정 파일을 설치합니다. 또한 Vscode에서 프로젝트를 열 때 사용할 devcontainer도 구성해주므로, 에이전트 코더가 어떤 부분을 영향을 미치고 볼 수 있는지 제한할 수 있습니다.
이 스크린샷은 Claude가 Mendix 프로젝트에 대해 에이전트 검색을 수행하기 위해 mxcli 명령어를 사용하는 방법을 보여줍니다. 이는 지정된 모듈의 페이지 목록을 가져오고, 구조를 사용하여 모듈 내 모든 문서의 개요를 얻으며, 특정 페이지의 소스를 설명합니다. 이 정보를 바탕으로 프로젝트를 수정하는 계획을 세울 수 있습니다.
스킬 문서들은 에이전트 코딩 도구에게 Mendix 프로젝트를 구축하는 방법을 가르칩니다. 디자인 패턴과 모범 사례로 자체 스킬을 추가할 수 있습니다. MDL을 사용하면 에이전트가 필요한 Mendix 문서를 얼마나 구체적으로 생성해야 하는지 지정할 수 있습니다.
Mxcli는 프로젝트에 대한 정보를 담은 일련의 데이터베이스 테이블을 구축합니다. 이를 통해 프로젝트 문서에 대해 유연한 에이전트 검색이 가능해집니다.
카탈로그 테이블들은 Starlark API로 노출되어, 사용 가능한 데이터를 커스텀 Mendix 린터 규칙에서 사용할 수 있게 합니다.
mxcli를 사용하는 가장 쉬운 방법은 vscode입니다. vscode 내부에서 Claude Code를 실행할 수 있으며, mxcli는 Mendix vscode 확장을 설치하여 Mendix 프로젝트 검토 및 이해에 도움을 줍니다.
프로젝트 구조는 Mendix Studio Pro의 앱 탐색기(app explorer)와 유사하게 모든 모듈과 문서를 보여줍니다. 이 VSCode 확장 기능은 또한 일부 Mendix 문서 유형에 대한 시각화를 제공하여, VSCode를 벗어나지 않고도 생성된 문서를 검토할 수 있도록 보장합니다.
Claude 코드는 PAD(portable application distribution)를 사용하여 Mendix 프로젝트를 시작할 수 있습니다. 이 과정은 Mendix 런타임을 하나의 Docker 컨테이너에서, PostgreSQL을 다른 Docker 컨테이너에서 실행합니다. 이를 통해 VS Code를 벗어나지 않고도 Mendix 프로젝트를 테스트할 수 있습니다.
Devcontainer는 playwright-cli와 함께 사용하도록 구성되어 있어 Claude Code가 실행 중인 애플리케이션을 테스트할 수 있게 합니다.
Claude 코드는 기존 데이터를 마이그레이션하거나, 애플리케이션을 실행할 때 PostgreSQL 컨테이너에 데모 데이터를 생성할 수 있습니다.
모든 것이 하나의 명령어로 구성된 새로운 Mendix 프로젝트를 만드세요:
mxcli new MyApp --version 11.8.0
이 명령어는 MxBuild를 다운로드하고, 빈 Mendix 프로젝트를 생성하며, AI 도구링과 Dev Container를 설정하고, 올바른 mxcli 바이너리를 설치합니다. 결과 폴더를 VS Code에서 열고 Dev Container에서 다시 열면 바로 사용할 준비가 됩니다.
CLI를 갖춘 장치가 없나요? Claude Code를 웹에서 사용하여 브라우저에서 Mendix 앱을 전체적으로 구축할 수 있습니다 (iPad에서도 작동) — mxcli는 클라우드 컨테이너에 전체 도구 체인을 제공하고 이를 커밋하여 향후 세션이 자체 부트스트랩되게 합니다. GitHub 템플릿을 선택할 필요가 없습니다. 전체 워크플로우:
빈 GitHub 리포지토리를 생성합니다 — 앱이 존재하고 세션이 실행되는 곳입니다.(선택 사항) 브라우저 미리보기를 위한 허브 키를 받습니다: https://hub.mxcli.org/cli에서 열고, GitHub로 로그인한 후 허브 키를 생성합니다.리포지토리에 Claude Code 환경을 만듭니다. MXCLI_HUB_KEY=<키> (2단계에서)를 설정하고 GitHub Releases, Mendix의 CDN, 그리고 hub.mxcli.org에 대한 아웃바운드 HTTPS를 허용합니다.
.부트스트랩 프롬프트를 붙여넣습니다 세션에. 에이전트는 mxcli를 설치하고, mxcli new → mxcli init을 실행하며, FINDINGS.md를 시작하고, 설정을 커밋하며, mxcli run --local --setup --ensure-db로 앱을 부팅하여 테스트 가능한 상태가 되게 합니다.아래의 따뜻한 루프(warm loop)로 반복합니다; 공유 가능한 브라우저 미리보기를 위해 --hub https://hub.mxcli.org를 추가합니다.
웹에서 개발하기 (Claude Code)는 전체 워크플로우를 안내하며, 부트스트랩 프롬프트에는 정확한 복사-붙여넣기 텍스트가 포함되어 있습니다.
다음으로 **로컬 개발 루프(warm local dev loop)**를 반복합니다. 이 루프는 Docker가 필요 없는 약 1초 간의 편집→테스트 사이클입니다:
mxcli run --local -p app.mpr --watch --screenshot # 실시간 리로드 + 자동 스크린샷
mxcli run --local
은 mxbuild --serve를 유지하며, 독립적인 런타임(standalone runtime)을 제공합니다. 즉, 페이지/마이크로플로우 편집이 몇 초 만에 실시간으로 적용됩니다(실시간 reload_model, 또는 엔티티 변경 시 재시작 + DDL). 또한 --screenshot은 Playwright를 사용하여 각 페이지를 캡처합니다. 로컬 개발 루프를 참조하세요.
앱을 공개 URL의 브라우저에서 미리 보기하려면 --hub를 추가하세요. 앱 자체는 로컬에 머무르며 단일 443 연결을 통해 리버스 터널링(reverse-tunnels)됩니다. 따라서 출구 전용 환경(egress-only environments, 예: 웹상의 Claude Code)에서도 작동합니다:
mxcli run --hub https://hub.example.com -p app.mpr # -> 공유 가능한 미리 보기 URL
mxcli tunnel-hub --domain example.com
은 한 번 작은 VPS에서 실행하는 정적 릴레이(static relay)입니다. 이 도구는 프로젝트, 솔루션, 브랜치 및 워크트리 전반에 걸쳐 서브도메인별로 여러 미리 보기를 지원하며, hub.example.com/에서 정렬 가능한 가용성 개요를 제공합니다. 로컬 개발 루프 → 외부 브라우저 미리 보기를 참조하세요.
이 터널은 리눅스 컨테이너(Linux container) 밖으로 미리 보기를 내보내기 위해 존재하며, 이전에 실행된 유일한 환경입니다. 따라서 오직 Linux 전용으로 구축되었습니다. 범용 터널링 도구를 Windows 및 macOS 바이너리에 임베딩하면, 해당 플랫폼에서는 절대 사용할 수 없으므로 Microsoft Defender와 기업 EDR(Endpoint Detection and Response)에 의해 플래그가 지정되어 대부분의 Mendix 개발자가 사용하는 관리형 사내 노트북에서 mxcli 사용이 차단됩니다. 이러한 플랫폼에서도 명령어는 여전히 존재하며 도움말을 표시하지만, 설명 메시지와 함께 실패합니다. --hub와 tunnel-hub를 사용하려면 프로젝트의 devcontainer 내부에서 mxcli를 실행해야 하며, 이들은 Linux 전용입니다. 나머지 모든 mxcli run --local 기능은 영향을 받지 않습니다. 스캐너를 피하기 위해 종속성을 난독화하지 않았습니다. 해결책은 해당 기능을 사용하지 않는 곳에 배포하는 것이 아닙니다. 근거: ADR-0009.
기존 Mendix 프로젝트의 경우, mxcli init을 사용하여 AI 도구 및 Dev Container를 추가하세요:
두 접근 방식 모두 스킬(skills)이 포함된 .ai-context/ 폴더, 격리된 개발을 위한 .devcontainer/ 폴더, 그리고 도구별 설정 파일을 생성합니다. VS Code / Cursor에서 프로젝트를 열고 Dev Container에서 다시 연 다음, AI 어시스턴트를 시작하세요:
claude # 또는 Cursor, Continue.dev 등을 사용합니다.
| 도구 | 설정 파일 | 설명 |
|---|
| Claude Code | .claude/, CLAUDE.md | 스킬 및 명령어 전체 통합 지원 |
| OpenCode | .opencode/, opencode.json | 스킬, 명령어 및 린트 규칙 |
| Cursor | .cursorrules | 간결한 MDL 참조 및 명령어 가이드 |
| Continue.dev | .continue/config.json | 사용자 지정 명령어 및 슬래시 명령어 |
| Windsurf | .windsurfrules | Codeium의 AI와 MDL 규칙 |
| Aider | .aider.conf.yml | 터미널 기반 AI 페어 프로그래밍 |
| Universal | AGENTS.md | 모든 도구에서 작동합니다。 |
# 지원되는 도구 목록 보기
mxcli init --list-tools
# 기존 프로젝트에 도구 추가
...
릴리스 페이지에서 미리 빌드된 바이너리를 다운로드하세요. 에셋은 mxcli-<os>-<arch>라는 이름의 원시 바이너리입니다 (추출할 것은 없습니다). mxcli는 빠르게 변화하는 알파 버전이므로, 롤링되는 nightly 빌드를 사용하는 것이 좋습니다(새 기능이 가장 먼저 적용됩니다). 재현성을 위해 vX.Y.Z 릴리스를 고정하세요:
# Linux/macOS — nightly
curl -fsSL -o mxcli \
...
또는 소스에서 빌드하세요 (Go + Make — make build는 go install이 할 수 없는 ANTLR 파서 생성을 실행합니다):
git clone https://github.com/mendixlabs/mxcli.git
cd mxcli
make -C mdl/grammar bootstrap # 일회성: 고정된 ANTLR 생성기를 설치합니다
...
생성기 버전은 고정되어 있으며 핵심적입니다. go.mod의 ANTLR 런타임과 일치해야 하며, 그렇지 않으면 생성된 파서가 컴파일되지 않습니다. antlr4-tools는 첫 실행 시 ANTLR jar를 다운로드하므로, 빌드는 Go뿐만 아니라 네트워크와 JVM이 필요합니다. 이미 PATH에 antlr4 런처가 있는 경우(예: brew install antlr4) 부트스트랩 과정은 건너뛰세요.
go install …@latest
is not supported: the generated ANTLR parser isn't committed, so a module-source build fails. Use a pre-built binary or make build.
# 모든 모듈 목록 보기
mxcli -p app.mpr -c "list modules"
# 모듈 내 엔티티 목록 보기
...
검증 메시지, 로그 메시지, 캡션, 레이블 및 MDL 소스 전반에서 검색:
# 검증 관련 콘텐츠 검색
mxcli search -p app.mpr "validation"
# 파이프 친화적 출력 (줄당 type<TAB>name)
...
describe로 파이프하기:
# 일치하는 첫 번째 마이크로플로우 설명
mxcli search -p app.mpr "validation" -q --format names | head -1 | awk '{print $2}' | \
xargs mxcli describe -p app.mpr microflow
...
# 마이크로플로우를 호출하는 것 찾기
mxcli callers -p app.mpr MyModule.ProcessOrder
mxcli callers -p app.mpr MyModule.ProcessOrder --transitive
...
EXPERIMENTAL: 이 명령어들은 테스트되지 않은 개념 증명(proof-of-concept)입니다. 항상 dry run을 사용하세요.