# Package CLI reference

gamedev pkg commands for package authors: init, validate, pack, link, unlink, dev, logs, publish and publisher, with their options and output.

_Last updated: 2026-11-19_

The `gamedev` CLI carries every tool a package author needs: it writes a new package, runs it against a real project while you edit, checks it the way the app and the registry will, builds the exact archive users install, and publishes it. `init`, `validate`, `pack` and `logs` run signed out. `link`, `unlink` and `dev` change a project's packages and need you signed in, like every package change; `publish` needs a sign-in or a publisher token, `publisher` a sign-in. The commands for using packages (`add`, `remove`, `update`, `settings` …) are on the [CLI page](https://ai-game.dev/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 …
```

Every authoring command prints its usage with `--help`.

## Create a package: `pkg init`

Writes a new package into a new or empty folder (a `.git` folder is fine):

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

| File | What it is |
| --- | --- |
| `aigd-package.json` | The manifest, with `$schema` for completion |
| `src/extension.ts` | Your code: `activate(ctx)` and `deactivate()` |
| `dist/extension.js` | Prebuilt, so the package runs before your first build; `main` points here |
| `src/types/aigd.d.ts`, `src/types/aigd-package.schema.json` | The package API types and the manifest schema |
| `package.json`, `tsconfig.json` | `npm run build` (`src/` to `dist/`) and `npm run dev` (watch) |
| `README.md`, `.gitignore` | Yours to edit |

Without `--id`, the publisher is `you` and the name is the folder's name: put your own publisher in before you share it. `--engine` writes a [game engine package](https://ai-game.dev/docs/wiki/app/game-engine-packages) instead.

## Run it in a project: `pkg link`, `unlink` and `dev`

`link` points a project at your folder instead of a published version, at the local level by default. The folder is used in place, reloads in every open app and CLI when a file it ships changes, and is never auto-updated. `unlink` goes back to whatever the other levels declare, from the cache, with no download.

`pkg dev` is `pkg link` for a package with a build step: it runs the package's own dev script, or, without one, re-runs its build script whenever a file the package does not ship changes (its sources), links the folder after the first successful build, and stops every process it started on Ctrl+C. The link stays until you 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).
```

A folder whose manifest names another id is refused (`id-mismatch`); a moved folder is reported with the way back.

## Read its log: `pkg logs`

Prints the lines of one package from the app's background service, in time order: everything your code logs (`ctx.log`, `console.*`) and the host's lines about it (activation, failures with their stack). `-f` keeps following; `--lines N` changes how many lines it shows first (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 …
```

## Check it: `pkg validate`

Runs the checks the app and the registry run, each with its file and field:

- the manifest as the app reads it: the schema, ids owned by the package, `when` clauses, settings, menus, game engine rules;
- the registry's rules: a publisher, a semver `version`, `engines.aigd`; proposed API is a warning here (`pack` and `publish` refuse it);
- the files the manifest names (`main`, `icon`, an engine's icons, starter previews and skills) among the files that ship;
- the archive the app installs: at most 20,000 files and 512 MiB unpacked, paths that fit a tar header, no symlinks (skipped, with a warning). The registry's own limits are tighter: 5,000 files, 64 MiB per file, 200 MiB unpacked and 50 MiB compressed (see [Registry rules and checks](https://ai-game.dev/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 when valid (warnings allowed), 1 on any error. `--json` prints the result for CI.

## Build the archive: `pkg pack`

Validates, then writes the exact archive the registry builds for the same folder: deterministic (sorted entries, fixed times and owners), so the same files give the same bytes and the same integrity hash on every computer.

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

**What ships:** everything in the folder except the top-level `src/`, `test/`, `tests/`, `coverage/`, `.turbo/`, `.agent-scratch/`, `.fixtures/`, `tsconfig*.json`, `vitest.config.*`, `*.tsbuildinfo`, `.aigd-install.json` and `*.tgz`, and `node_modules/`, `.git/` and `.DS_Store` at any depth. The app never runs `npm install` for a package: bundle your libraries into `dist/`. `--allow-proposed` packs a package that uses proposed API, for a GitHub, npm or folder source only.

## Publish it: `pkg publish`

Packs (with `pkg pack`'s checks and bytes), uploads to the community registry, then waits for its automatic checks and prints the report:

```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 | Effect |
| --- | --- |
| `--notes <file>` | A Markdown file (at most 20 KB) with this version's release notes; without it, the version's section of `CHANGELOG.md` |
| `--token <agd_pub_…>` | A publisher token (or the `AI_GAME_DEV_PUBLISHER_TOKEN` environment variable) |
| `--oidc-audience <aud>` | Override the OIDC audience for Trusted Publishing (or `AIGD_OIDC_AUDIENCE`); the CLI derives it from the registry, `ai-game.dev` for production |
| `--no-wait` | Return after the upload |
| `--json` | The result as JSON for scripts |

`publish` picks its credential in this order: a publisher token when one is given, then the CI's OIDC token in GitHub Actions or GitLab CI (Trusted Publishing, a CLI newer than 0.32.0; inside CI a missing setup is an error, not a fall-back), then your signed-in session. Running `publish` again for a version already uploaded reads its checks instead of uploading it twice. A rejected version exits 1 with each failed check and its reason. Channels and publishing from CI without a token are on [Publishing packages](https://ai-game.dev/docs/wiki/app/publishing-packages) and [Trusted Publishing](https://ai-game.dev/docs/wiki/app/trusted-publishing).

## Manage publishers: `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>
```

A token is shown once, lives at most 365 days, and can only upload, read a version's status and yank.

## Related pages

- [Creating packages](https://ai-game.dev/docs/wiki/app/creating-packages) for the quick start.
- [Registry rules and checks](https://ai-game.dev/docs/wiki/app/package-registry) for what `validate` and `publish` refuse.

---

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