# CLI-Referenz für Pakete — AI Game Dev App & CLI · AI Game Developer Wiki

gamedev pkg-Befehle für Paketautoren: init, validate, pack, link, unlink, dev, logs, publish und publisher mit ihren Optionen und Ausgaben.

Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/app/package-cli).

Die `gamedev`-CLI enthält jedes Werkzeug, das ein Paketautor braucht: Sie schreibt ein neues Paket, führt es während der Bearbeitung gegen ein echtes Projekt aus, prüft es so, wie es die App und die Registry tun werden, baut genau das Archiv, das Nutzer installieren, und veröffentlicht es. `init`, `validate`, `pack` und `logs` laufen ohne Anmeldung. `link`, `unlink` und `dev` ändern die Pakete eines Projekts und erfordern eine Anmeldung, wie jede Paketänderung; `publish` braucht eine Anmeldung oder ein Publisher-Token, `publisher` eine Anmeldung. Die Befehle zur Verwendung von Paketen (`add`, `remove`, `update`, `settings` …) stehen auf der [CLI-Seite](https://ai-game.dev/de/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 …
```

Jeder Authoring-Befehl gibt seine Verwendung mit `--help` aus.

## Ein Paket erstellen: `pkg init`

Schreibt ein neues Paket in einen neuen oder leeren Ordner (ein `.git`-Ordner ist in Ordnung):

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

| Datei | Was es ist |
| --- | --- |
| `aigd-package.json` | Das Manifest, mit `$schema` für die Autovervollständigung |
| `src/extension.ts` | Dein Code: `activate(ctx)` und `deactivate()` |
| `dist/extension.js` | Vorgebaut, damit das Paket schon vor deinem ersten Build läuft; `main` zeigt hierher |
| `src/types/aigd.d.ts`, `src/types/aigd-package.schema.json` | Die Typen der Paket-API und das Manifest-Schema |
| `package.json`, `tsconfig.json` | `npm run build` (`src/` nach `dist/`) und `npm run dev` (Watch) |
| `README.md`, `.gitignore` | Kannst du bearbeiten |

Ohne `--id` ist der Publisher `you` und der Name ist der Name des Ordners: setze deinen eigenen Publisher ein, bevor du das Paket teilst. `--engine` schreibt stattdessen ein [Game-Engine-Paket](https://ai-game.dev/de/docs/wiki/app/game-engine-packages).

## In einem Projekt ausführen: `pkg link`, `unlink` und `dev`

`link` verweist ein Projekt auf deinen Ordner statt auf eine veröffentlichte Version, standardmäßig auf der lokalen Ebene. Der Ordner wird direkt verwendet, lädt in jeder geöffneten App und CLI neu, sobald sich eine Datei ändert, die er ausliefert, und wird nie automatisch aktualisiert. `unlink` kehrt zu dem zurück, was die anderen Ebenen deklarieren, aus dem Cache, ohne Download.

`pkg dev` ist `pkg link` für ein Paket mit Build-Schritt: Es führt das eigene dev-Skript des Pakets aus oder, wenn es keines gibt, führt sein Build-Skript neu aus, sobald sich eine Datei ändert, die das Paket nicht ausliefert (seine Quellen), verknüpft den Ordner nach dem ersten erfolgreichen Build und beendet mit Ctrl+C jeden Prozess, den es gestartet hat. Die Verknüpfung bleibt, bis du sie mit unlink auflöst.

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

Ein Ordner, dessen Manifest eine andere id nennt, wird abgelehnt (`id-mismatch`); bei einem verschobenen Ordner wird der Weg zurück gemeldet.

## Sein Log lesen: `pkg logs`

Gibt die Zeilen eines Pakets aus dem Hintergrunddienst der App in zeitlicher Reihenfolge aus: alles, was dein Code loggt (`ctx.log`, `console.*`), und die Zeilen des Hosts dazu (Aktivierung, Fehler mit ihrem Stack). `-f` folgt weiter; `--lines N` ändert, wie viele Zeilen zuerst angezeigt werden (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 …
```

## Es prüfen: `pkg validate`

Führt die Prüfungen aus, die die App und die Registry ausführen, jeweils mit Datei und Feld:

- das Manifest, wie die App es liest: das Schema, ids im Besitz des Pakets, `when`-Klauseln, Einstellungen, Menüs, Game-Engine-Regeln;
- die Regeln der Registry: ein Publisher, eine Semver-`version`, `engines.aigd`; vorgeschlagene API ist hier eine Warnung (`pack` und `publish` lehnen sie ab);
- die Dateien, die das Manifest nennt (`main`, `icon`, die Icons einer Engine, Starter-Vorschauen und Skills), unter den Dateien, die ausgeliefert werden;
- das Archiv, das die App installiert: höchstens 20.000 Dateien und 512 MiB entpackt, Pfade, die in einen tar-Header passen, keine Symlinks (übersprungen, mit einer Warnung). Die Limits der Registry selbst sind enger: 5.000 Dateien, 64 MiB pro Datei, 200 MiB entpackt und 50 MiB komprimiert (siehe [Regeln und Prüfungen der Registry](https://ai-game.dev/de/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.
```

Exit-Code 0, wenn gültig (Warnungen erlaubt), 1 bei jedem Fehler. `--json` gibt das Ergebnis für CI aus.

## Das Archiv bauen: `pkg pack`

Validiert und schreibt dann genau das Archiv, das die Registry für denselben Ordner baut: deterministisch (sortierte Einträge, feste Zeiten und Eigentümer), sodass dieselben Dateien auf jedem Computer dieselben Bytes und denselben Integritäts-Hash ergeben.

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

**Was ausgeliefert wird:** alles im Ordner außer dem obersten `src/`, `test/`, `tests/`, `coverage/`, `.turbo/`, `.agent-scratch/`, `.fixtures/`, `tsconfig*.json`, `vitest.config.*`, `*.tsbuildinfo`, `.aigd-install.json` und `*.tgz`, sowie `node_modules/`, `.git/` und `.DS_Store` in jeder Tiefe. Die App führt nie `npm install` für ein Paket aus: bündle deine Bibliotheken in `dist/`. `--allow-proposed` packt ein Paket, das vorgeschlagene API verwendet, nur für eine GitHub-, npm- oder Ordnerquelle.

## Es veröffentlichen: `pkg publish`

Packt (mit den Prüfungen und Bytes von `pkg pack`), lädt in die Community-Registry hoch und wartet dann auf deren automatische Prüfungen und gibt den Bericht aus:

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

| Option | Wirkung |
| --- | --- |
| `--notes <file>` | Eine Markdown-Datei (höchstens 20 KB) mit den Release Notes dieser Version; ohne sie der Abschnitt dieser Version in `CHANGELOG.md` |
| `--token <agd_pub_…>` | Ein Publisher-Token (oder die Umgebungsvariable `AI_GAME_DEV_PUBLISHER_TOKEN`) |
| `--oidc-audience <aud>` | Überschreibt die OIDC-Audience für Trusted Publishing (oder `AIGD_OIDC_AUDIENCE`); die CLI leitet sie aus der Registry ab, `ai-game.dev` in der Produktion |
| `--no-wait` | Kehrt nach dem Upload zurück |
| `--json` | Das Ergebnis als JSON für Skripte |

`publish` wählt seine Anmeldedaten in dieser Reihenfolge: ein Publisher-Token, wenn eines angegeben ist, dann das OIDC-Token der CI in GitHub Actions oder GitLab CI (Trusted Publishing, eine CLI neuer als 0.32.0; innerhalb der CI ist ein fehlendes Setup ein Fehler, kein Fallback), dann deine angemeldete Sitzung. Wird `publish` erneut für eine bereits hochgeladene Version ausgeführt, liest es deren Prüfungen, statt sie zweimal hochzuladen. Eine abgelehnte Version endet mit Exit-Code 1 samt jeder fehlgeschlagenen Prüfung und ihrem Grund. Channels und das Veröffentlichen aus der CI ohne Token werden auf [Pakete veröffentlichen](https://ai-game.dev/de/docs/wiki/app/publishing-packages) und [Trusted Publishing](https://ai-game.dev/de/docs/wiki/app/trusted-publishing) behandelt.

## Publisher verwalten: `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>
```

Ein Token wird nur einmal angezeigt, ist höchstens 365 Tage gültig und kann ausschließlich hochladen, den Status einer Version lesen und yank ausführen.

## Verwandte Seiten

- [Pakete erstellen](https://ai-game.dev/de/docs/wiki/app/creating-packages) für den Schnellstart.
- [Registry-Regeln und Prüfungen](https://ai-game.dev/de/docs/wiki/app/package-registry) dafür, was `validate` und `publish` ablehnen.

---

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

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