# 패키지 CLI 레퍼런스 — AI Game Dev 앱 & CLI · AI Game Developer Wiki

패키지 작성자를 위한 gamedev pkg 명령: init, validate, pack, link, unlink, dev, logs, publish, publisher와 각 옵션 및 출력.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/app/package-cli).

`gamedev` CLI에는 패키지 작성자에게 필요한 모든 도구가 들어 있습니다. 새 패키지를 작성하고, 편집하는 동안 실제 프로젝트에 연결해 실행하고, 앱과 레지스트리가 검사할 방식 그대로 검사하고, 사용자가 설치할 바로 그 아카이브를 빌드하고, 게시합니다. `init`, `validate`, `pack`, `logs`는 로그아웃 상태에서 실행됩니다. `link`, `unlink`, `dev`는 프로젝트의 패키지를 변경하므로 다른 모든 패키지 변경과 마찬가지로 로그인이 필요합니다. `publish`는 로그인 또는 퍼블리셔 토큰이, `publisher`는 로그인이 필요합니다. 패키지를 사용하는 명령(`add`, `remove`, `update`, `settings` …)은 [CLI 페이지](https://ai-game.dev/ko/docs/wiki/app/cli#pkg)에 있습니다.

```text
gamedev pkg init [dir] [--engine] [--id <publisher.name>]
gamedev pkg validate [dir] [--json]
gamedev pkg pack [dir] [--out <dir>] [--allow-proposed] [--json]
gamedev pkg link <folder> [--user|--project|--local]
gamedev pkg unlink <id> [--user|--project|--local]
gamedev pkg dev <folder> [--user|--project|--local]
gamedev pkg logs <publisher.name> [-f|--follow] [--lines N]
gamedev pkg publish [dir] [--notes <file>] [--token <agd_pub_…>] [--oidc-audience <aud>] [--no-wait] [--json]
gamedev pkg publisher claim|list|token …
```

모든 작성 명령은 `--help`로 사용법을 출력합니다.

## 패키지 만들기: `pkg init`

새 폴더나 빈 폴더에 새 패키지를 작성합니다(`.git` 폴더가 있어도 됩니다):

```bash
gamedev pkg init level-tools --id acme.level-tools
```

```text
Created acme.level-tools (a package) in /home/you/src/level-tools
  aigd-package.json  src/extension.ts  dist/extension.js (prebuilt)  src/types/aigd.d.ts (package API 0.4.0)
```

| 파일 | 설명 |
| --- | --- |
| `aigd-package.json` | 매니페스트이며, 자동 완성을 위한 `$schema`가 포함됩니다 |
| `src/extension.ts` | 여러분의 코드: `activate(ctx)`와 `deactivate()` |
| `dist/extension.js` | 미리 빌드되어 있어 첫 빌드 전에도 패키지가 실행되며, `main`이 이 파일을 가리킵니다 |
| `src/types/aigd.d.ts`, `src/types/aigd-package.schema.json` | 패키지 API 타입과 매니페스트 스키마 |
| `package.json`, `tsconfig.json` | `npm run build`(`src/` → `dist/`)와 `npm run dev`(watch) |
| `README.md`, `.gitignore` | 자유롭게 편집하세요 |

`--id`를 지정하지 않으면 퍼블리셔는 `you`, 이름은 폴더 이름이 됩니다. 공유하기 전에 자신의 퍼블리셔를 넣으세요. `--engine`을 지정하면 대신 [게임 엔진 패키지](https://ai-game.dev/ko/docs/wiki/app/game-engine-packages)를 작성합니다.

## 프로젝트에서 실행하기: `pkg link`, `unlink`, `dev`

`link`는 게시된 버전 대신 프로젝트가 여러분의 폴더를 가리키게 하며, 기본적으로 로컬 레벨에 적용됩니다. 폴더는 제자리에서 사용되고, 패키지가 배포하는 파일이 바뀌면 열려 있는 모든 앱과 CLI에서 다시 로드되며, 자동 업데이트되지 않습니다. `unlink`는 다시 다른 레벨이 선언한 버전으로 돌아가며, 다운로드 없이 캐시에서 가져옵니다.

`pkg dev`는 빌드 단계가 있는 패키지를 위한 `pkg link`입니다. 패키지 자체의 dev 스크립트를 실행하거나, 없으면 패키지가 배포하지 않는 파일(소스)이 바뀔 때마다 빌드 스크립트를 다시 실행하고, 첫 빌드가 성공하면 폴더를 링크하며, Ctrl+C를 누르면 자신이 시작한 모든 프로세스를 중지합니다. 링크는 unlink할 때까지 유지됩니다.

```text
Running its dev script (tsc -p tsconfig.json --watch --preserveWatchOutput). Ctrl+C stops it.
Waiting for its first build (dist/extension.js) before linking …
First build in 900 ms.
Linked acme.level-tools → ~/src/level-tools (local level, not committed).
```

매니페스트가 다른 id를 가리키는 폴더는 거부되며(`id-mismatch`), 이동된 폴더는 되돌리는 방법과 함께 보고됩니다.

## 로그 읽기: `pkg logs`

앱의 백그라운드 서비스에서 한 패키지의 로그 줄을 시간 순서대로 출력합니다. 여러분의 코드가 기록하는 모든 것(`ctx.log`, `console.*`)과 호스트가 해당 패키지에 대해 남기는 줄(활성화, 스택이 포함된 실패)이 포함됩니다. `-f`는 계속 따라가며, `--lines N`은 처음에 표시할 줄 수(100)를 바꿉니다.

```text
2026-11-16T10:12:03.114Z 41872 [10:12:03.114] INFO  [core:pkg-host] pkg=acme.level-tools state=active ms=4
2026-11-16T10:12:03.118Z 41872 [10:12:03.118] INFO  [pkg:acme.level-tools] activated
2026-11-16T10:12:09.502Z 41872 [10:12:09.502] ERROR [pkg:acme.level-tools] save failed: Error: EACCES …
```

## 검사하기: `pkg validate`

앱과 레지스트리가 실행하는 검사를 각각의 파일 및 필드와 함께 실행합니다:

- 앱이 읽는 그대로의 매니페스트: 스키마, 패키지가 소유한 id, `when` 절, 설정, 메뉴, 게임 엔진 규칙
- 레지스트리 규칙: 퍼블리셔, semver `version`, `engines.aigd`. 제안된 API는 여기서는 경고입니다(`pack`과 `publish`는 이를 거부합니다).
- 배포되는 파일 중 매니페스트가 지정한 파일(`main`, `icon`, 엔진의 아이콘, 스타터 미리보기 및 스킬)
- 앱이 설치하는 아카이브: 최대 20,000개 파일 및 압축 해제 시 512 MiB, tar 헤더에 맞는 경로, 심볼릭 링크 없음(경고와 함께 건너뜀). 레지스트리 자체의 제한은 더 엄격합니다: 5,000개 파일, 파일당 64 MiB, 압축 해제 시 200 MiB, 압축 시 50 MiB([레지스트리 규칙 및 검사](https://ai-game.dev/ko/docs/wiki/app/package-registry#limits) 참조).

```text
acme.level-tools 0.1.0 (/home/you/src/level-tools)
  error    aigd-package.json contributes.commands[1].command: "level.export" must be "acme.level-tools.<id>"
  error    aigd-package.json main: "dist/extension.js" does not exist (build it first: npm run build)
5 files ship, 4.2 KB.
Not valid: 2 errors.
```

유효하면 종료 코드 0(경고 허용), 오류가 있으면 1입니다. `--json`은 CI를 위해 결과를 출력합니다.

## 아카이브 빌드하기: `pkg pack`

검증한 다음, 같은 폴더에 대해 레지스트리가 빌드하는 것과 동일한 아카이브를 작성합니다. 결정적이므로(항목 정렬, 고정된 시간과 소유자) 같은 파일은 어느 컴퓨터에서든 동일한 바이트와 동일한 무결성 해시를 만듭니다.

```text
Packed acme.level-tools 0.1.0 → /home/you/src/level-tools/acme.level-tools-0.1.0.aigd.tgz
  files      5 (4.2 KB unpacked)
  size       2025 bytes
  integrity  sha512-ZrbOleD47onMM7hMss123CDMOEp5sAlDig7ISGpjhE6JT3btOAtFoWE2+DzSSoVQcfqzRj4seI1T2xajawpsIQ==
  treeHash   sha256-BTeAbus6JQO+VKxsSOjfGN9A0v+nkfdmtRiJ/KvNpug=
```

**배포되는 것:** 폴더의 모든 항목에서 최상위 `src/`, `test/`, `tests/`, `coverage/`, `.turbo/`, `.agent-scratch/`, `.fixtures/`, `tsconfig*.json`, `vitest.config.*`, `*.tsbuildinfo`, `.aigd-install.json`, `*.tgz`와, 깊이에 관계없이 `node_modules/`, `.git/`, `.DS_Store`를 제외한 나머지. 앱은 패키지에 대해 `npm install`을 실행하지 않습니다: 라이브러리는 `dist/`에 번들하세요. `--allow-proposed`는 제안된 API를 사용하는 패키지를 GitHub, npm 또는 폴더 소스에 한해 팩합니다.

## 게시하기: `pkg publish`

패킹하고(`pkg pack`의 검사와 바이트 그대로) 커뮤니티 레지스트리에 업로드한 다음, 자동 검사를 기다렸다가 보고서를 출력합니다:

```text
Packed acme.level-tools 0.1.0: 5 files, 2025 bytes, sha512-ZrbO…
Uploaded acme.level-tools 0.1.0 to ai-game.dev: uploaded
Waiting for the registry's checks (archive, manifest, rules, secrets, prompt injection, native code, virus scan)…
  state: checking
  state: published
Published acme.level-tools 0.1.0.
```

| 옵션 | 효과 |
| --- | --- |
| `--notes <file>` | 이 버전의 릴리스 노트를 담은 Markdown 파일(최대 20KB). 지정하지 않으면 `CHANGELOG.md`의 해당 버전 섹션을 사용합니다. |
| `--token <agd_pub_…>` | 퍼블리셔 토큰(또는 `AI_GAME_DEV_PUBLISHER_TOKEN` 환경 변수) |
| `--oidc-audience <aud>` | Trusted Publishing의 OIDC audience를 재정의합니다(또는 `AIGD_OIDC_AUDIENCE`). CLI는 레지스트리에서 이를 도출하며, 프로덕션에서는 `ai-game.dev`입니다. |
| `--no-wait` | 업로드 후 바로 반환합니다. |
| `--json` | 스크립트에서 쓸 수 있도록 결과를 JSON으로 출력합니다. |

`publish`는 다음 순서로 자격 증명을 선택합니다. 퍼블리셔 토큰이 주어지면 그것을, 그다음으로 GitHub Actions 또는 GitLab CI의 OIDC 토큰(Trusted Publishing, 0.32.0보다 새로운 CLI; CI 안에서 설정이 없으면 폴백이 아니라 오류입니다)을, 그다음으로 로그인된 세션을 사용합니다. 이미 업로드된 버전에 대해 `publish`를 다시 실행하면 두 번 업로드하지 않고 해당 버전의 검사 결과를 읽습니다. 거부된 버전은 실패한 각 검사와 그 이유를 출력하며 종료 코드 1로 끝납니다. 채널과 토큰 없이 CI에서 퍼블리싱하는 방법은 [패키지 퍼블리싱](https://ai-game.dev/ko/docs/wiki/app/publishing-packages)과 [Trusted Publishing](https://ai-game.dev/ko/docs/wiki/app/trusted-publishing)을 참고하세요.

## 퍼블리셔 관리: `pkg publisher`

```bash
gamedev login                                          # once, in the browser
gamedev pkg publisher claim acme --name "Acme Tools"   # claim a publisher id
gamedev pkg publisher list                             # your publishers and your role
gamedev pkg publisher token create acme --label github-actions --days 90
gamedev pkg publisher token list acme
gamedev pkg publisher token revoke acme <token id>
```

토큰은 한 번만 표시되며 최대 365일 동안 유효하고, 업로드, 버전 상태 조회, yank만 수행할 수 있습니다.

## 관련 페이지

- 빠른 시작은 [패키지 만들기](https://ai-game.dev/ko/docs/wiki/app/creating-packages)를 참고하세요.
- `validate`와 `publish`가 거부하는 항목은 [레지스트리 규칙과 검사](https://ai-game.dev/ko/docs/wiki/app/package-registry)를 참고하세요.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/app/package-cli

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/app/package-cli
