iga-pages

IGA Pages スキル

対象は CLI（認証、プロジェクト作成、開発、ビルド、デプロイ、調査、環境変数、インテグレーションに使用する iga ツール）と プロジェクト開発（関数、API ルート、Agent、Blob SDK）の 2 つです。

すべてのフラグの詳細を確認するには、iga <command> -h を実行してください。

重要：CLI のバージョン

@iga-pages/cli のバージョンは >= 1.1.9、Node.js のバージョンは >= 20 である必要があります。iga --version で確認してください。CLI がインストールされていない場合、または古い場合は、ほかの iga コマンドを使用する前に公開パッケージをインストールまたはアップグレードしてください。

npm i -g @iga-pages/cli@latest

重要：フレームワークの互換性

サポート対象の公開フレームワークは、Next.js、Vite、Vue CLI、Create React App、Angular、Hexo、Docusaurus、VitePress、VuePress、Astro、Nuxt です。この一覧にないフレームワーク（Remix など）はサポートされていません。続行する前にユーザーに伝えてください。

純粋な静的アセット（プレーンな HTML／JS／CSS）もデプロイできます。デフォルトでは、プロジェクトのルートが出力ディレクトリとして使用されます。

重要：ログイン認証

リモート操作（init、link、list、deploy、preview、inspect、logs、env、integration）を実行する前に、iga whoami を実行してください。成功した場合は既存のログイン状態を再利用します。認証情報がない、期限切れ、または拒否された場合に限り iga login を実行してください。あらゆる失敗を再ログインの理由とせず、ネットワークやサービスのエラーを調査してください。

実際にログインが必要な場合、その方法は環境によって異なります。

• ローカル IDE（VS Code、TRAE デスクトップなど）→ ブラウザログイン：

  iga login
  

  ユーザーがブラウザ認証を完了するまで待ってください。完了すると、CLI に成功メッセージが表示されます。

• リモートの対話型ターミナル（SSH、Cowork、クラウド開発コンテナーなど）→ デバイスコードログイン：

  iga login --remote
  

  CLI に認証 URL と短いコードが表示され、ユーザーが任意のブラウザで認証を完了する間、ポーリングが行われます。

• 無人の自動化（CI/CD など、認証を完了できる人がいない環境）→ AK/SK ログイン：

  iga login --accessKey <YOUR_AK> --secretKey <YOUR_SK>
  

  Volcengine IAM コンソールから AK/SK を取得してください。

方法を選ぶ際は、ターミナルからローカルブラウザを開けないものの、別の場所で人が認証を完了できる場合は --remote を使用してください。AK/SK は無人の自動化に限り使用してください。それ以外の場合は、デフォルトのブラウザログインを優先してください。--remote と AK/SK は併用できません。

重要：作業ディレクトリ

pages link、dev、build、deploy などのプロジェクト単位のコマンドは、プロジェクトのルート内で実行してください。スキャフォールディングツール（create-next-app、npm create vite、hugo new site など）はサブディレクトリを作成するため、これらのコマンドを実行する前に、必ずそのディレクトリへ cd してください。

npx create-next-app@latest my-app --yes
cd my-app && iga pages deploy --name my-app

重要：利用状況の帰属

このスキルが実行するすべての iga コマンドにタグを付け、利用状況を特定できるようにしてください。 このタグが識別するのはスキルとそのバージョンのみで、ユーザーデータは含まれません。

サブコマンドにかかわらず、すべての iga 呼び出しの先頭に、プロセス単位の VE_SKILL_ID を付けてください。コマンド間でシェルの状態が維持されない場合があるため、各コマンドでインライン設定してください。

VE_SKILL_ID=iga-pages/1.0.13 iga <command>

クイックリファレンス

iga --version                       # must be >= 1.1.9

iga whoami                        # check current login state; run this BEFORE login
iga login                         # local IDE: opens browser; only if whoami fails
iga login --remote                # remote interactive terminal; only if whoami fails
iga login --accessKey <AK> --secretKey <SK>  # unattended automation; only if whoami fails

## create an Agent project from a current template
iga pages init --type agent --list --json
iga pages init <directory> --type agent --template <ID>

## new project
iga pages deploy --name <my-app>   # deploy (auto-creates project on first run)
## project already linked
iga pages deploy

iga pages link                     # create/associate a Pages project (does NOT deploy)
iga pages link --format=json       # list choices as JSON without changing state
iga pages link --yes --format=json # auto-link/create and return the result as JSON
iga pages dev                      # local dev server (REQUIRED when api/ exists — serves framework + /api/* together)
iga pages build                    # build for production

## environment variables (project-level, linked project required)
iga pages env list                 # list KEY names (values never shown)
iga pages env list --format=json   # as JSON
iga pages env add <NAME>           # add (--value <v> --yes for CI)
iga pages env update <NAME>        # update existing
iga pages env remove <NAME>        # remove (--yes to skip confirm)
iga pages env pull                 # write all project env to .env.local

## integrations (Supabase; linked project required)
iga pages integration list                  # bindings on this project
iga pages integration list --format=json    # as JSON
iga pages integration link supabase         # connect Volcengine Supabase
iga pages integration link supabase --format=json   # as JSON; returns next missing flag until all provided
iga pages integration unlink                # remove a binding
iga pages integration unlink --format=json --yes    # as JSON (requires --yes)

• Agent プロジェクトでは、ほかのフルスタックプロジェクトと同じ pages dev、pages build、pages deploy のワークフローを使用します。Agent 専用のデプロイコマンドはありません。
• 新規プロジェクトでは、Git デプロイ用の認証済み GitHub リモートがある場合、デプロイにはそれを使用し、それ以外の場合はアップロードデプロイにフォールバックします。すでにリンク済みのプロジェクトでは、設定済みのプロバイダーが維持されます。Git インテグレーションでサポートされるのは GitHub のみです。
• デプロイの出力に ?iga_token=...&iga_time=... を含むプレビュー URL がある場合は、クエリを含む完全な URL を共有してください。省略するとアクセスに問題が生じる場合があります。

プロジェクト開発

• フレームワークの検出、サポートされるバージョン、必要な Astro/Nuxt 統合については、references/frameworks.md を参照してください。
• API ルートと Pages Functions については、references/functions.md を参照してください。
• Agent Store、フレームワークのセッション、Sandbox のライフサイクル、モデル向けツールについては、references/agent-sdk.md を参照してください。
• プロジェクトごとの永続オブジェクトストレージとブラウザーからのアップロードチケットについては、references/blob-sdk.md を参照してください。

環境変数と統合

• プロジェクトレベルの環境変数（env list/add/update/remove/pull）については、references/env.md を参照してください。
• Supabase の接続（integration list/link/unlink）、デプロイのオーケストレーション順序（link → integration → deploy）、および byted-supabase スキルに引き継ぐタイミングについては、references/integration.md を参照してください。

状況確認とログ

• デプロイのステータス、ビルドログ、過去のランタイムログについては、references/logs.md を参照してください。

避けるべきパターン

CLI

• プロジェクトディレクトリ以外で iga コマンドを実行する → 先に必ずスキャフォールドされたサブディレクトリに cd してください
• 認証済みセッションなしでデプロイする → 先に iga whoami を実行し、失敗した場合に限り iga login を実行してください
• .iga/ をコミットする → ソース管理の対象外にしてください。link/deploy は通常 .iga/ を .gitignore に追加しますが、この更新はベストエフォートです
• api/ がある場合に npm run dev / vite / next dev / npm start でローカル開発を開始する → サーバーレス関数が提供されるように iga pages dev を使用してください
• package.json の "scripts.dev" を iga pages dev に設定する → iga pages dev 自体が package.json の dev スクリプトを呼び出すため、無限ループになります。"scripts.dev" にはフレームワーク本来の開発コマンド（例：next dev、vite）を設定してください
• link の前に env / integration コマンドを実行する → これらのコマンドにはリンク済みプロジェクトが必要です。先に iga pages link を実行してください
• env add/update/remove がローカルファイルを変更する、または即時に反映されると考える → リモートプロジェクトの設定を編集し、次回のデプロイ時に適用されます。.env.local を更新するには iga pages env pull を実行してください
• Supabase 管理の変数に対して env update/env remove を試みる → 読み取り専用です。iga pages integration link/unlink で管理してください
• 統合を利用できる場合に、Supabase のキーを手動で env add に貼り付ける → iga pages integration link supabase を使用すると、接続変数が自動的に同期されます
• ブラウザーコードや任意の Node.js プロセスで @iga-pages/agent または @iga-pages/blob をインポートする → IGA Pages Functions またはフルスタックフレームワークのサーバーハンドラーでのみ使用してください