Package CLI reference

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

Updated November 19, 2026 View as Markdown

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.

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

gamedev pkg init level-tools --id acme.level-tools
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)
FileWhat it is
aigd-package.jsonThe manifest, with $schema for completion
src/extension.tsYour code: activate(ctx) and deactivate()
dist/extension.jsPrebuilt, so the package runs before your first build; main points here
src/types/aigd.d.ts, src/types/aigd-package.schema.jsonThe package API types and the manifest schema
package.json, tsconfig.jsonnpm run build (src/ to dist/) and npm run dev (watch)
README.md, .gitignoreYours 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 instead.

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.

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

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

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:

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.
OptionEffect
--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-waitReturn after the upload
--jsonThe 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 and Trusted Publishing.

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

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