> For the complete documentation index, see [llms.txt](https://clunk.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://clunk.gitbook.io/docs/undefined-2/cli-ci.md).

# CLI와 CI

Windows PowerShell에서 Clunk CLI로 검사·수정·검사 증명서를 만드는 방법

Clunk CLI는 로컬 파일의 실제 바이트를 읽는 개발자용 도구입니다. Windows에서는 PowerShell과 `npm.cmd`를 사용합니다. 입력 파일을 덮어쓰지 않고, JSON 결과와 검사 증명서를 별도 출력합니다.

{% hint style="info" %}
명령은 저장소 루트에서 실행합니다. `npm.cmd install` 뒤에 실행하면 됩니다. 출력 폴더를 입력 폴더와 분리하면 원본을 보존하기 쉽습니다.
{% endhint %}

## GLB·glTF 검사

```powershell
# 실제 파일을 열고 측정값·finding·파일 지문을 JSON으로 출력
npm.cmd run clunk -- inspect public/samples/clunk-messy-sample.glb --profile pc

# 정책을 통과하지 못하면 프로세스 종료 코드 2
npm.cmd run clunk -- validate public/samples/clunk-messy-sample.glb --profile web
```

기본 정책 프로파일은 `web`, `mobile`, `pc`입니다. `validate`의 `valid`는 파일 규격 판정이며 게임 엔진 import나 플레이어 화면 승인을 의미하지 않습니다.

## 안전한 수정과 검사 증명서

```powershell
# 원본은 그대로 두고 별도 GLB를 씁니다
npm.cmd run clunk -- optimize public/samples/clunk-messy-sample.glb --out output/quad.glb

# 위 명령은 output/quad.glb.passport.json도 함께 씁니다.
# 원본과 출력 파일을 다시 열어 두 파일을 연결한 Passport를 직접 만들 때:
npm.cmd run clunk -- passport public/samples/clunk-messy-sample.glb output/quad.glb
```

`optimize`가 적용하는 v1 허용 목록은 빈 노드 제거(`prune-empty-nodes`), 같은 재질 합치기(`dedupe-materials`), 허용된 메타데이터 정리(`clean-metadata`), 새 파일로 다시 묶기(`repack`)입니다. 일반적인 메시 단순화, 텍스처 재인코딩, Draco/Meshopt 변환, 애니메이션·스킨 변경은 이 명령이 하지 않습니다.

출력 파일은 처음부터 다시 검사합니다. Passport에는 `sourceHash`, `outputHash`, 전후 `resultDigest`, 적용 작업과 전후 점수가 들어갑니다. `productionReady`는 런타임·게임 시점 증거와 별개로 유지됩니다.

## 파일 변경 감시

```powershell
npm.cmd run clunk -- watch public/samples --profile web --manifest output/clunk-watch-manifest.json --ref main
```

`watch`는 파일이 바뀔 때마다 바이트, SHA-256, 점수와 선택한 참조값을 manifest에 다시 씁니다. 장시간 실행을 멈추려면 `Ctrl+C`를 누릅니다.

## Clunk Series 로컬 제작

Clunk Series의 Game Ready mesh pass는 감사한 source material을 사용해 Clunk 내부 코드가 실행합니다. 생성 결과의 provider는 `clunk-series-native-v1`이며 외부 생성 API 호출을 뜻하지 않습니다.

```powershell
npm.cmd run series:mesh -- game-ready public/samples/clunk-messy-sample.glb `
  --out output/game-ready/optimized.glb `
  --target-profile web-three-mobile `
  --run-id series-game-ready-001
```

이 작업도 입력과 출력을 분리하고, output을 fresh reinspection한 뒤 evidence와 provenance sidecar를 기록합니다. meshopt 압축은 전송·저장 최적화이며 polygon 품질 승인이나 player-facing 화면 승인이 아닙니다. 파일이 만들어졌거나 구조 점수가 높다고 `READY` 또는 판매 가능으로 부르지는 않습니다.

## 로컬 MCP에서 같은 계약 사용하기

로컬 MCP를 쓰면 [AI 도구 연결(MCP)](/docs/undefined-2/clients.md)의 stdio 설정으로 다음 도구를 호출할 수 있습니다.

* `clunk_inspect`, `clunk_validate` — 실제 GLB·glTF 검사
* `clunk_optimize` — 허용 목록 수정과 별도 출력
* `clunk_passport` — 원본·출력 재검사와 Passport
* `clunk_asset_author` — 2D·Sprite·Spine·animation·3D authoring 결과를 별도 폴더에 만들고 다시 열기

HTTP MCP는 로컬 경로를 읽지 않습니다. CI나 원격 에이전트에서는 파일을 base64 bundle로 보내는 HTTP 검사 계약을 사용하세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://clunk.gitbook.io/docs/undefined-2/cli-ci.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.