# Referencia de la CLI de paquetes — App y CLI de AI Game Dev · AI Game Developer Wiki

Comandos gamedev pkg para autores de paquetes: init, validate, pack, link, unlink, dev, logs, publish y publisher, con sus opciones y salida.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/app/package-cli).

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](https://ai-game.dev/es/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 …
```

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):

```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)
```

| 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](https://ai-game.dev/es/docs/wiki/app/game-engine-packages).

## 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.

```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).
```

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).

```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 …
```

## 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 `version` semver, `engines.aigd`; la API propuesta es solo un aviso aquí (`pack` y `publish` la 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](https://ai-game.dev/es/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.
```

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.

```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=
```

**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:

```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.
```

| 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](https://ai-game.dev/es/docs/wiki/app/publishing-packages) y [Trusted Publishing](https://ai-game.dev/es/docs/wiki/app/trusted-publishing).

## Gestionar publicadores: `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>
```

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](https://ai-game.dev/es/docs/wiki/app/creating-packages) para el inicio rápido.
- [Reglas y comprobaciones del registro](https://ai-game.dev/es/docs/wiki/app/package-registry) para saber qué rechazan `validate` y `publish`.

---

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

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