パッケージ CLI リファレンス
パッケージ作者向けの gamedev pkg コマンド解説: init、validate、pack、link、unlink、dev、logs、publish、publisher とそのオプションおよび出力。
gamedev CLI には、パッケージ作者に必要なツールがすべて揃っています。新しいパッケージを作成し、編集中は実際のプロジェクトに対して実行し、アプリとレジストリが行うのと同じ方法でチェックし、ユーザーがインストールするそのままのアーカイブをビルドして公開します。init、validate、pack、logs はサインアウトのまま実行できます。link、unlink、dev はプロジェクトのパッケージを変更するため、他のすべてのパッケージ変更と同様にサインインが必要です。publish にはサインインまたはパブリッシャートークンが、publisher にはサインインが必要です。パッケージを使用するためのコマンド(add、remove、update、settings …)は CLI ページ にあります。
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 …各オーサリングコマンドは --help で使用方法を表示します。
パッケージを作成する: pkg init
新しいパッケージを新規または空のフォルダに書き込みます(.git フォルダがあっても問題ありません):
gamedev pkg init level-tools --id acme.level-toolsCreated 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)| ファイル | 内容 |
|---|---|
aigd-package.json | マニフェスト。補完用の $schema 付き |
src/extension.ts | あなたのコード: activate(ctx) と deactivate() |
dist/extension.js | ビルド済みなので、初回ビルド前でもパッケージが動作します。main はここを指します |
src/types/aigd.d.ts、src/types/aigd-package.schema.json | パッケージ API の型とマニフェストスキーマ |
package.json、tsconfig.json | npm run build(src/ から dist/ へ)と npm run dev(ウォッチ) |
README.md、.gitignore | 自由に編集できます |
--id を指定しない場合、パブリッシャーは you、名前はフォルダ名になります。共有する前に自分のパブリッシャーを設定してください。--engine を指定すると、代わりにゲームエンジンパッケージを書き込みます。
プロジェクトで実行する: pkg link、unlink、dev
link は、公開されたバージョンの代わりにプロジェクトを自分のフォルダに向けます(デフォルトではローカルレベル)。フォルダはその場で使用され、同梱ファイルが変更されると開いているすべてのアプリと CLI でリロードされ、自動更新されることはありません。unlink は、他のレベルが宣言しているものにキャッシュから戻します。ダウンロードは発生しません。
pkg dev は、ビルドステップを持つパッケージ向けの pkg link です。パッケージ自身の dev スクリプトを実行するか、それがなければ、パッケージが同梱しないファイル(ソース)が変更されるたびにビルドスクリプトを再実行し、最初のビルドが成功した後にフォルダをリンクし、Ctrl+C で起動したすべてのプロセスを停止します。リンクは 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).マニフェストが別の id を名指ししているフォルダは拒否されます(id-mismatch)。移動されたフォルダは、戻す方法とともに報告されます。
ログを読む: pkg logs
アプリのバックグラウンドサービスから、1 つのパッケージの行を時系列で出力します。コードがログに出すすべて(ctx.log、console.*)と、ホストがそのパッケージについて出す行(アクティベーション、スタック付きの失敗)です。-f を付けると追従を続け、--lines N で最初に表示する行数を変更できます(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 …チェックする: pkg validate
アプリとレジストリが実行するチェックを、それぞれのファイルとフィールドとともに実行します:
- アプリが読むマニフェスト: スキーマ、パッケージが所有する id、
when句、設定、メニュー、ゲームエンジンのルール。 - レジストリのルール: パブリッシャー、semver の
version、engines.aigd。ここでは提案中の API は警告になります(packとpublishはそれを拒否します)。 - マニフェストが名指しするファイル(
main、icon、エンジンのアイコン、スタータープレビューとスキル)が同梱ファイルの中に存在するか。 - アプリがインストールするアーカイブ: 最大 20,000 ファイル、展開後 512 MiB、tar ヘッダーに収まるパス、シンボリックリンクなし(スキップされ、警告が出ます)。レジストリ自体の制限はより厳しく、5,000 ファイル、1 ファイルあたり 64 MiB、展開後 200 MiB、圧縮後 50 MiB です(レジストリのルールとチェック を参照)。
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.有効な場合は終了コード 0(警告は許容)、エラーがあれば 1。--json を付けると CI 向けに結果を出力します。
アーカイブをビルドする: pkg pack
検証を行い、同じフォルダに対してレジストリがビルドするのとまったく同じアーカイブを書き出します。決定的(エントリはソートされ、時刻と所有者は固定)なので、同じファイルからはどのコンピューターでも同じバイト列と整合性ハッシュが得られます。
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=同梱されるもの: フォルダ内のすべて。ただし最上位の src/、test/、tests/、coverage/、.turbo/、.agent-scratch/、.fixtures/、tsconfig*.json、vitest.config.*、*.tsbuildinfo、.aigd-install.json、*.tgz、および任意の階層の node_modules/、.git/、.DS_Store を除きます。アプリがパッケージに対して npm install を実行することはありません。ライブラリは dist/ にバンドルしてください。--allow-proposed は、提案中の API を使用するパッケージをパックします(GitHub、npm、フォルダのソースのみ)。
公開する: pkg publish
パックし(pkg pack と同じチェックとバイト列)、コミュニティレジストリにアップロードして、自動チェックを待ち、レポートを出力します:
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.| オプション | 効果 |
|---|---|
--notes <file> | このバージョンのリリースノートを記した Markdown ファイル(最大 20 KB)。省略した場合は CHANGELOG.md の該当バージョンのセクション |
--token <agd_pub_…> | パブリッシャートークン(または AI_GAME_DEV_PUBLISHER_TOKEN 環境変数) |
--oidc-audience <aud> | Trusted Publishing 用の OIDC audience を上書きする(または AIGD_OIDC_AUDIENCE)。CLI はレジストリからこれを導出し、本番環境では ai-game.dev となる |
--no-wait | アップロード後に戻る |
--json | スクリプト向けに結果を JSON で出力する |
publish は次の順序で認証情報を選択します。パブリッシャートークンが指定されていればそれを使い、次に GitHub Actions または GitLab CI の OIDC トークン(Trusted Publishing、0.32.0 より新しい CLI。CI 内ではセットアップの欠落はフォールバックではなくエラーになります)、最後にサインイン済みのセッションです。すでにアップロード済みのバージョンに対して再度 publish を実行すると、二重にアップロードするのではなくそのチェック結果を読み取ります。拒否されたバージョンは、失敗した各チェックとその理由とともに終了コード 1 で終了します。チャネルと、トークンなしで CI から公開する方法については Publishing packages と Trusted Publishing を参照してください。
パブリッシャーの管理: 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>トークンは一度だけ表示され、有効期間は最大 365 日で、アップロード、バージョンステータスの読み取り、yank のみが可能です。
関連ページ
- Creating packages でクイックスタートを確認できます。
- Registry rules and checks で
validateとpublishが何を拒否するかを確認できます。