# Referência da CLI de pacotes — App e CLI do AI Game Dev · AI Game Developer Wiki

Comandos gamedev pkg para autores de pacotes: init, validate, pack, link, unlink, dev, logs, publish e publisher, com suas opções e saída.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/app/package-cli).

A CLI `gamedev` reúne todas as ferramentas de que um autor de pacotes precisa: ela cria um novo pacote, o executa em um projeto real enquanto você edita, o verifica do mesmo modo que o app e o registro farão, monta o arquivo exato que os usuários instalam e o publica. `init`, `validate`, `pack` e `logs` funcionam sem login. `link`, `unlink` e `dev` alteram os pacotes de um projeto e exigem login, como toda alteração de pacote; `publish` exige login ou um token de publisher, e `publisher` exige login. Os comandos para usar pacotes (`add`, `remove`, `update`, `settings` …) estão na [página da CLI](https://ai-game.dev/pt-br/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 …
```

Todo comando de autoria imprime seu uso com `--help`.

## Criar um pacote: `pkg init`

Grava um novo pacote em uma pasta nova ou vazia (uma pasta `.git` é aceitável):

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

| Arquivo | O que é |
| --- | --- |
| `aigd-package.json` | O manifesto, com `$schema` para autocompletar |
| `src/extension.ts` | Seu código: `activate(ctx)` e `deactivate()` |
| `dist/extension.js` | Pré-compilado, para o pacote rodar antes da sua primeira build; `main` aponta para aqui |
| `src/types/aigd.d.ts`, `src/types/aigd-package.schema.json` | Os tipos da API de pacotes e o schema do manifesto |
| `package.json`, `tsconfig.json` | `npm run build` (`src/` para `dist/`) e `npm run dev` (watch) |
| `README.md`, `.gitignore` | Para você editar |

Sem `--id`, o publisher é `you` e o nome é o nome da pasta: coloque seu próprio publisher antes de compartilhar. `--engine` cria um [pacote de game engine](https://ai-game.dev/pt-br/docs/wiki/app/game-engine-packages) em vez disso.

## Executá-lo em um projeto: `pkg link`, `unlink` e `dev`

`link` aponta um projeto para a sua pasta em vez de uma versão publicada, no nível local por padrão. A pasta é usada no próprio local, recarrega em todo app e CLI abertos quando um arquivo que ela distribui muda, e nunca é atualizada automaticamente. `unlink` volta para o que os outros níveis declararem, a partir do cache, sem download.

`pkg dev` é o `pkg link` para um pacote com etapa de build: ele executa o próprio script dev do pacote ou, sem ele, reexecuta seu script de build sempre que um arquivo que o pacote não distribui (suas fontes) muda, vincula a pasta após a primeira build bem-sucedida e encerra todos os processos que iniciou com Ctrl+C. O link permanece até você usar 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).
```

Uma pasta cujo manifesto indica outro id é recusada (`id-mismatch`); uma pasta movida é reportada junto com o caminho de volta.

## Ler o log: `pkg logs`

Imprime as linhas de um pacote a partir do serviço em segundo plano do app, em ordem cronológica: tudo o que seu código registra (`ctx.log`, `console.*`) e as linhas do host sobre ele (ativação, falhas com seu stack). `-f` continua acompanhando; `--lines N` altera quantas linhas são mostradas inicialmente (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 …
```

## Verificá-lo: `pkg validate`

Executa as verificações que o app e o registro fazem, cada uma com seu arquivo e campo:

- o manifesto como o app o lê: o schema, ids de propriedade do pacote, cláusulas `when`, configurações, menus, regras de game engine;
- as regras do registro: um publisher, uma `version` semver, `engines.aigd`; API proposta é apenas um aviso aqui (`pack` e `publish` a recusam);
- os arquivos que o manifesto indica (`main`, `icon`, os ícones de uma engine, previews e skills de starter) entre os arquivos distribuídos;
- o arquivo que o app instala: no máximo 20.000 arquivos e 512 MiB descompactado, caminhos que cabem em um cabeçalho tar, sem symlinks (ignorados, com um aviso). Os limites do próprio registro são mais rígidos: 5.000 arquivos, 64 MiB por arquivo, 200 MiB descompactado e 50 MiB compactado (veja [Regras e verificações do registro](https://ai-game.dev/pt-br/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 saída 0 quando válido (avisos permitidos), 1 em qualquer erro. `--json` imprime o resultado para CI.

## Montar o arquivo: `pkg pack`

Valida e então grava o arquivo exato que o registro monta para a mesma pasta: determinístico (entradas ordenadas, datas e proprietários fixos), de modo que os mesmos arquivos geram os mesmos bytes e o mesmo hash de integridade em qualquer computador.

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

**O que é distribuído:** tudo na pasta, exceto, no nível superior, `src/`, `test/`, `tests/`, `coverage/`, `.turbo/`, `.agent-scratch/`, `.fixtures/`, `tsconfig*.json`, `vitest.config.*`, `*.tsbuildinfo`, `.aigd-install.json` e `*.tgz`, e, em qualquer profundidade, `node_modules/`, `.git/` e `.DS_Store`. O app nunca executa `npm install` para um pacote: empacote suas bibliotecas em `dist/`. `--allow-proposed` empacota um pacote que usa API proposta, apenas para uma origem GitHub, npm ou pasta.

## Publicá-lo: `pkg publish`

Empacota (com as verificações e os bytes do `pkg pack`), envia ao registro da comunidade, depois aguarda suas verificações automáticas e imprime o relatório:

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

| Opção | Efeito |
| --- | --- |
| `--notes <file>` | Um arquivo Markdown (no máximo 20 KB) com as notas de versão desta versão; sem ele, a seção da versão em `CHANGELOG.md` |
| `--token <agd_pub_…>` | Um token de publicador (ou a variável de ambiente `AI_GAME_DEV_PUBLISHER_TOKEN`) |
| `--oidc-audience <aud>` | Substitui o audience OIDC do Trusted Publishing (ou `AIGD_OIDC_AUDIENCE`); a CLI o deriva do registro, `ai-game.dev` em produção |
| `--no-wait` | Retorna após o upload |
| `--json` | O resultado em JSON para scripts |

`publish` escolhe sua credencial nesta ordem: um token de publicador quando fornecido, depois o token OIDC do CI no GitHub Actions ou GitLab CI (Trusted Publishing, uma CLI mais recente que 0.32.0; dentro do CI, uma configuração ausente é um erro, não um fall-back), e então sua sessão autenticada. Executar `publish` novamente para uma versão já enviada lê suas verificações em vez de enviá-la duas vezes. Uma versão rejeitada sai com código 1 com cada verificação com falha e seu motivo. Canais e publicação a partir do CI sem token estão em [Publicando pacotes](https://ai-game.dev/pt-br/docs/wiki/app/publishing-packages) e [Trusted Publishing](https://ai-game.dev/pt-br/docs/wiki/app/trusted-publishing).

## Gerenciar 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>
```

Um token é exibido uma única vez, dura no máximo 365 dias e só pode enviar, ler o status de uma versão e yank.

## Páginas relacionadas

- [Criando pacotes](https://ai-game.dev/pt-br/docs/wiki/app/creating-packages) para o início rápido.
- [Regras e verificações do registro](https://ai-game.dev/pt-br/docs/wiki/app/package-registry) para o que `validate` e `publish` recusam.

---

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

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