Referencia de la CLI de paquetes
Comandos gamedev pkg para autores de paquetes: init, validate, pack, link, unlink, dev, logs, publish y publisher, con sus opciones y salida.
La CLI gamedev reúne todas las herramientas que necesita un autor de paquetes: crea un paquete nuevo, lo ejecuta contra un proyecto real mientras editas, lo comprueba tal como lo harán la app y el registro, construye el archivo exacto que instalan los usuarios y lo publica. init, validate, pack y logs funcionan sin iniciar sesión. link, unlink y dev cambian los paquetes de un proyecto y requieren que hayas iniciado sesión, como cualquier cambio de paquetes; publish necesita una sesión iniciada o un token de publisher, y publisher una sesión iniciada. Los comandos para usar paquetes (add, remove, update, settings…) están en la página de la 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 …Todos los comandos de autoría muestran su uso con --help.
Crear un paquete: pkg init
Escribe un paquete nuevo en una carpeta nueva o vacía (una carpeta .git no supone problema):
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)| Archivo | Qué es |
|---|---|
aigd-package.json | El manifiesto, con $schema para el autocompletado |
src/extension.ts | Tu código: activate(ctx) y deactivate() |
dist/extension.js | Precompilado, para que el paquete funcione antes de tu primera compilación; main apunta aquí |
src/types/aigd.d.ts, src/types/aigd-package.schema.json | Los tipos de la API de paquetes y el esquema del manifiesto |
package.json, tsconfig.json | npm run build (src/ a dist/) y npm run dev (watch) |
README.md, .gitignore | Tuyos para editar |
Sin --id, el publisher es you y el nombre es el de la carpeta: pon tu propio publisher antes de compartirlo. --engine escribe en su lugar un paquete de motor de juego.
Ejecutarlo en un proyecto: pkg link, unlink y dev
link apunta un proyecto a tu carpeta en lugar de a una versión publicada, en el nivel local por defecto. La carpeta se usa en su sitio, se recarga en cada app y CLI abiertos cuando cambia un archivo que incluye, y nunca se actualiza automáticamente. unlink vuelve a lo que declaren los otros niveles, desde la caché, sin descarga.
pkg dev es pkg link para un paquete con paso de compilación: ejecuta el script dev del propio paquete o, si no lo hay, vuelve a ejecutar su script de build cada vez que cambia un archivo que el paquete no incluye (sus fuentes), enlaza la carpeta tras la primera compilación correcta y detiene todos los procesos que inició con Ctrl+C. El enlace permanece hasta que lo desvincules.
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).Se rechaza una carpeta cuyo manifiesto indique otro id (id-mismatch); una carpeta movida se notifica con la forma de volver.
Leer su log: pkg logs
Imprime las líneas de un paquete del servicio en segundo plano de la app, en orden temporal: todo lo que registra tu código (ctx.log, console.*) y las líneas del host sobre él (activación, fallos con su stack). -f sigue mostrando líneas nuevas; --lines N cambia cuántas líneas muestra primero (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 …Comprobarlo: pkg validate
Ejecuta las comprobaciones que ejecutan la app y el registro, cada una con su archivo y su campo:
- el manifiesto tal como lo lee la app: el esquema, los ids que posee el paquete, las cláusulas
when, los ajustes, los menús, las reglas de motores de juego; - las reglas del registro: un publisher, una
versionsemver,engines.aigd; la API propuesta es solo un aviso aquí (packypublishla rechazan); - los archivos que nombra el manifiesto (
main,icon, los iconos de un motor, las vistas previas de starters y las skills) entre los archivos que se incluyen; - el archivo que instala la app: como máximo 20.000 archivos y 512 MiB descomprimidos, rutas que caben en una cabecera tar, sin enlaces simbólicos (se omiten, con un aviso). Los límites del propio registro son más estrictos: 5.000 archivos, 64 MiB por archivo, 200 MiB descomprimidos y 50 MiB comprimidos (consulta Reglas y comprobaciones del registro).
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.Código de salida 0 cuando es válido (se permiten avisos), 1 ante cualquier error. --json imprime el resultado para CI.
Construir el archivo: pkg pack
Valida y después escribe el archivo exacto que el registro construye para la misma carpeta: determinista (entradas ordenadas, horas y propietarios fijos), de modo que los mismos archivos dan los mismos bytes y el mismo hash de integridad en cualquier ordenador.
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=Qué se incluye: todo lo que hay en la carpeta excepto src/, test/, tests/, coverage/, .turbo/, .agent-scratch/, .fixtures/, tsconfig*.json, vitest.config.*, *.tsbuildinfo, .aigd-install.json y *.tgz de nivel superior, y node_modules/, .git/ y .DS_Store a cualquier profundidad. La app nunca ejecuta npm install para un paquete: empaqueta tus librerías en dist/. --allow-proposed empaqueta un paquete que usa API propuesta, solo para una fuente de GitHub, npm o carpeta.
Publicarlo: pkg publish
Empaqueta (con las comprobaciones y los bytes de pkg pack), lo sube al registro de la comunidad y después espera sus comprobaciones automáticas e imprime el informe:
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.| Opción | Efecto |
|---|---|
--notes <file> | Un archivo Markdown (como máximo 20 KB) con las notas de la versión de esta versión; si no se indica, la sección de la versión en CHANGELOG.md |
--token <agd_pub_…> | Un token de publicador (o la variable de entorno AI_GAME_DEV_PUBLISHER_TOKEN) |
--oidc-audience <aud> | Sobrescribe la audiencia OIDC para Trusted Publishing (o AIGD_OIDC_AUDIENCE); la CLI la deriva del registro, ai-game.dev para producción |
--no-wait | Vuelve después de la subida |
--json | El resultado en JSON para scripts |
publish elige su credencial en este orden: un token de publicador cuando se proporciona uno, después el token OIDC del CI en GitHub Actions o GitLab CI (Trusted Publishing, una CLI posterior a la 0.32.0; dentro del CI, una configuración ausente es un error, no una alternativa) y, por último, tu sesión iniciada. Ejecutar publish de nuevo para una versión ya subida lee sus comprobaciones en lugar de subirla dos veces. Una versión rechazada sale con código 1 junto con cada comprobación fallida y su motivo. Los canales y la publicación desde CI sin token están en Publicar paquetes y Trusted Publishing.
Gestionar publicadores: 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>Un token se muestra una sola vez, dura como máximo 365 días y solo puede subir, leer el estado de una versión y hacer yank.
Páginas relacionadas
- Crear paquetes para el inicio rápido.
- Reglas y comprobaciones del registro para saber qué rechazan
validateypublish.