패키지 CLI 레퍼런스
패키지 작성자를 위한 gamedev pkg 명령: init, validate, pack, link, unlink, dev, logs, publish, publisher와 각 옵션 및 출력.
gamedev CLI에는 패키지 작성자에게 필요한 모든 도구가 들어 있습니다. 새 패키지를 작성하고, 편집하는 동안 실제 프로젝트에 연결해 실행하고, 앱과 레지스트리가 검사할 방식 그대로 검사하고, 사용자가 설치할 바로 그 아카이브를 빌드하고, 게시합니다. init, validate, pack, logs는 로그아웃 상태에서 실행됩니다. link, unlink, dev는 프로젝트의 패키지를 변경하므로 다른 모든 패키지 변경과 마찬가지로 로그인이 필요합니다. publish는 로그인 또는 퍼블리셔 토큰이, publisher는 로그인이 필요합니다. 패키지를 사용하는 명령(add, remove, update, settings …)은 CLI 페이지에 있습니다.
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 폴더가 있어도 됩니다):
gamedev pkg init level-tools --id acme.level-toolsCreated 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을 지정하면 대신 게임 엔진 패키지를 작성합니다.
프로젝트에서 실행하기: pkg link, unlink, dev
link는 게시된 버전 대신 프로젝트가 여러분의 폴더를 가리키게 하며, 기본적으로 로컬 레벨에 적용됩니다. 폴더는 제자리에서 사용되고, 패키지가 배포하는 파일이 바뀌면 열려 있는 모든 앱과 CLI에서 다시 로드되며, 자동 업데이트되지 않습니다. unlink는 다시 다른 레벨이 선언한 버전으로 돌아가며, 다운로드 없이 캐시에서 가져옵니다.
pkg dev는 빌드 단계가 있는 패키지를 위한 pkg link입니다. 패키지 자체의 dev 스크립트를 실행하거나, 없으면 패키지가 배포하지 않는 파일(소스)이 바뀔 때마다 빌드 스크립트를 다시 실행하고, 첫 빌드가 성공하면 폴더를 링크하며, Ctrl+C를 누르면 자신이 시작한 모든 프로세스를 중지합니다. 링크는 unlink할 때까지 유지됩니다.
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)를 바꿉니다.
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(레지스트리 규칙 및 검사 참조).
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
검증한 다음, 같은 폴더에 대해 레지스트리가 빌드하는 것과 동일한 아카이브를 작성합니다. 결정적이므로(항목 정렬, 고정된 시간과 소유자) 같은 파일은 어느 컴퓨터에서든 동일한 바이트와 동일한 무결성 해시를 만듭니다.
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의 검사와 바이트 그대로) 커뮤니티 레지스트리에 업로드한 다음, 자동 검사를 기다렸다가 보고서를 출력합니다:
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에서 퍼블리싱하는 방법은 패키지 퍼블리싱과 Trusted Publishing을 참고하세요.
퍼블리셔 관리: pkg publisher
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만 수행할 수 있습니다.
관련 페이지
- 빠른 시작은 패키지 만들기를 참고하세요.
validate와publish가 거부하는 항목은 레지스트리 규칙과 검사를 참고하세요.