# パッケージ CLI リファレンス — AI Game DevアプリとCLI · AI Game Developer Wiki

パッケージ作者向けの gamedev pkg コマンド解説: init、validate、pack、link、unlink、dev、logs、publish、publisher とそのオプションおよび出力。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/app/package-cli)。

`gamedev` CLI には、パッケージ作者に必要なツールがすべて揃っています。新しいパッケージを作成し、編集中は実際のプロジェクトに対して実行し、アプリとレジストリが行うのと同じ方法でチェックし、ユーザーがインストールするそのままのアーカイブをビルドして公開します。`init`、`validate`、`pack`、`logs` はサインアウトのまま実行できます。`link`、`unlink`、`dev` はプロジェクトのパッケージを変更するため、他のすべてのパッケージ変更と同様にサインインが必要です。`publish` にはサインインまたはパブリッシャートークンが、`publisher` にはサインインが必要です。パッケージを使用するためのコマンド（`add`、`remove`、`update`、`settings` …）は [CLI ページ](https://ai-game.dev/ja/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 …
```

各オーサリングコマンドは `--help` で使用方法を表示します。

## パッケージを作成する: `pkg init`

新しいパッケージを新規または空のフォルダに書き込みます（`.git` フォルダがあっても問題ありません）:

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

| ファイル | 内容 |
| --- | --- |
| `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` を指定すると、代わりに[ゲームエンジンパッケージ](https://ai-game.dev/ja/docs/wiki/app/game-engine-packages)を書き込みます。

## プロジェクトで実行する: `pkg link`、`unlink`、`dev`

`link` は、公開されたバージョンの代わりにプロジェクトを自分のフォルダに向けます（デフォルトではローカルレベル）。フォルダはその場で使用され、同梱ファイルが変更されると開いているすべてのアプリと CLI でリロードされ、自動更新されることはありません。`unlink` は、他のレベルが宣言しているものにキャッシュから戻します。ダウンロードは発生しません。

`pkg dev` は、ビルドステップを持つパッケージ向けの `pkg link` です。パッケージ自身の dev スクリプトを実行するか、それがなければ、パッケージが同梱しないファイル（ソース）が変更されるたびにビルドスクリプトを再実行し、最初のビルドが成功した後にフォルダをリンクし、Ctrl+C で起動したすべてのプロセスを停止します。リンクは 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).
```

マニフェストが別の id を名指ししているフォルダは拒否されます（`id-mismatch`）。移動されたフォルダは、戻す方法とともに報告されます。

## ログを読む: `pkg logs`

アプリのバックグラウンドサービスから、1 つのパッケージの行を時系列で出力します。コードがログに出すすべて（`ctx.log`、`console.*`）と、ホストがそのパッケージについて出す行（アクティベーション、スタック付きの失敗）です。`-f` を付けると追従を続け、`--lines N` で最初に表示する行数を変更できます（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 …
```

## チェックする: `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 です（[レジストリのルールとチェック](https://ai-game.dev/ja/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.
```

有効な場合は終了コード 0（警告は許容）、エラーがあれば 1。`--json` を付けると CI 向けに結果を出力します。

## アーカイブをビルドする: `pkg pack`

検証を行い、同じフォルダに対してレジストリがビルドするのとまったく同じアーカイブを書き出します。決定的（エントリはソートされ、時刻と所有者は固定）なので、同じファイルからはどのコンピューターでも同じバイト列と整合性ハッシュが得られます。

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

**同梱されるもの:** フォルダ内のすべて。ただし最上位の `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` と同じチェックとバイト列）、コミュニティレジストリにアップロードして、自動チェックを待ち、レポートを出力します:

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

| オプション | 効果 |
| --- | --- |
| `--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](https://ai-game.dev/ja/docs/wiki/app/publishing-packages) と [Trusted Publishing](https://ai-game.dev/ja/docs/wiki/app/trusted-publishing) を参照してください。

## パブリッシャーの管理: `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>
```

トークンは一度だけ表示され、有効期間は最大 365 日で、アップロード、バージョンステータスの読み取り、yank のみが可能です。

## 関連ページ

- [Creating packages](https://ai-game.dev/ja/docs/wiki/app/creating-packages) でクイックスタートを確認できます。
- [Registry rules and checks](https://ai-game.dev/ja/docs/wiki/app/package-registry) で `validate` と `publish` が何を拒否するかを確認できます。

---

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

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