insforge-cli

InsForge CLI

バックエンドが必要な場合、または InsForge CLI で InsForge のバックエンドやクラウドインフラストラクチャを管理する場合は、常にこのスキルを使用してください。フロントエンド、バックエンド、またはエッジ関数から InsForge を呼び出すアプリケーションコードには、代わりに insforge app-integration スキルを使用してください。

基本ルール

• CLI は常に npx -y @insforge/cli <command> で実行してください。npx の -y は必ず付けてください。付けない場合、パッケージのインストール前に npx が「Ok to proceed?」と確認し、TTY に接続されたエージェントシェルで処理が永久に停止します。グローバルの insforge バイナリをインストールしたり、呼び出したりしないでください。
• プロジェクトがすでにリンクされている場合は、現在リンクされているプロジェクトを使用してください。ログイン、プロジェクトの作成、リンク、プロジェクトの検出、組織一覧の取得、またはクラウドプロジェクトのコマンドは、接続のセットアップが実際に必要な場合にのみ実行してください。
• バックエンドが必要で、まだプロジェクトがリンクされていない場合は、アプリケーションコードを書く前に、まず接続のセットアップを行ってください。（1）ログインする（whoami で確認します。サンドボックスでは、以下の 2 段階デバイスログインを使用します）。（2）新しいプロジェクトを create するか、既存のプロジェクトを link します。（3）その後、CLI から取得した実際のプロジェクト URL とキーを使って開発します。your-project.region.insforge.app のようなプレースホルダーの認証情報でスキャフォールディングを行わないでください。まず実際の値を取得してください。
• InsForge API キーは、フルアクセスの管理者キーとして扱ってください。サーバー側だけで保持し、フロントエンドや公開用の環境変数には含めないでください。
• 生のバックエンド HTTP 呼び出しよりも、CLI コマンドと文書化されたプロジェクト設定を優先してください。config apply で未サポートまたはスキップされたフィールドが報告された場合は、CLI を迂回して直接 API を呼び出すのではなく、その結果を伝えてください。
• 構造化された出力や非対話形式での値の収集が必要な場合は、--json を使用してください。ユーザーがアクションを承認している場合は、確認プロンプトに --yes を使用してください。
• リンク済みプロジェクトで重要なタスクを開始する際は、npx -y @insforge/cli memory list を実行してください（低コストで、AI 呼び出しはありません）。設計やデバッグを始める前に、タスクに関連するタイトルの内容を呼び出してください。決定事項や遭遇した注意点は、その場で memory remember を使って記録してください。references/memory.md を参照してください。
• InsForge に起因する問題に遭遇した場合、つまり本来動作するはずなのに動作しない場合、必要な機能がサポートされていない場合、説明（ドキュメント／スキル）と実際の動作が食い違う場合、または不要な手間が生じている場合は、npx -y @insforge/cli feedback で報告してください（Feedback を参照）。その後、回避策を使ってユーザーのタスクを続行してください。ユーザー自身のアプリケーションコードの問題については、決してフィードバックを送信しないでください。

グローバルオプション

フラグ	用途
--json	構造化された JSON 出力を行い、テキストや選択肢などの値収集プロンプトをスキップします。必須の値が不足している場合はエラーになります。Y/N 確認も求められる破壊的なコマンドでは、-y と組み合わせてください。
-y, --yes	削除や上書きなどの Y/N 確認プロンプトを自動承認します。値収集プロンプトはスキップしません。値収集プロンプトをスキップするには、--json を使用してください。npx 自体の -y とは別のため、両方を指定します。例：npx -y @insforge/cli link --project-id <id> -y。

終了コード

コード	意味
0	成功
1	HTTP 400 以上の関数呼び出しを含む一般的なエラー
2	認証されていません
3	プロジェクトがリンクされていません
4	リソースが見つかりません
5	アクセスが拒否されました

環境変数

変数	用途
INSFORGE_ACCESS_TOKEN	保存済みのアクセストークンを上書きします
INSFORGE_PROJECT_ID	リンク済みのプロジェクト ID を上書きします
INSFORGE_EMAIL	非対話型ログイン用のメールアドレス
INSFORGE_PASSWORD	非対話型ログイン用のパスワード

接続のセットアップ

タスクでプロジェクトへのアクセスが必要で、接続状態が不明な場合は、npx -y @insforge/cli current から始めます。認証済みのユーザーを確認する必要がある場合、または current で CLI が認証されていないと報告された場合は、npx -y @insforge/cli whoami を使用します。

認証されていない場合は、npx -y @insforge/cli login を実行します（ブラウザーが開きます）。ブラウザーのないヘッドレス／エージェント／CI 環境では、ユーザー API キーを使って非対話型で認証します：npx -y @insforge/cli login --user-api-key "$INSFORGE_USER_API_KEY"（ユーザーはダッシュボードの Profile → API Keys からキーを作成します）。ユーザーはブラウザーを利用できるものの、CLI のローカルコールバックにアクセスできないサンドボックス（例：ChatGPT アプリ）では、デバイスログインを 2 段階で行います：timeout 15 npx -y @insforge/cli login --device --json 2>&1 || true を実行して確認リンクとコードを取得し、それらをユーザーに伝えた後、npx -y @insforge/cli login --device --json を再実行して同じコードで再開し、ユーザーが Authorize をクリックしたら完了します。詳しくは references/login.md を参照してください。サンドボックスで api.insforge.dev が許可されたネットワークドメインではないと報告された場合は、ワークスペースの許可されたネットワークドメインに追加するようユーザーに依頼してから、再試行します。プロジェクトがリンクされていない場合は、既存のプロジェクトには npx -y @insforge/cli link を、新しいバックエンドをユーザーが求めている場合は npx -y @insforge/cli create を使用します。CI、ローカルテストプロジェクト、自動化、またはユーザーが明示的に指定したプロジェクトのコンテキストなど、すでにリンク済みまたは設定済みのワークフローでは、そのプロジェクトのコンテキストをそのまま使用します。クラウドプロジェクトが常にデフォルトです。ユーザーが自身のマシン上の Docker で実行するバックエンドを明示的に求めた場合に限り、references/local.md を参照します。ログインや create が面倒な場合の代替手段として使用してはいけません。

コマンドの振り分け

必要な情報	CLI 領域	参照先
ログイン、ログアウト、現在のユーザー	login、logout、whoami	references/login.md
プロジェクトの作成／リンク／一覧／現在のプロジェクト	create、link、list、current、metadata	references/create.md
ユーザー自身のマシン上で Docker を使ってバックエンドを実行 — 明示的に依頼された場合のみ	local	references/local.md
プロジェクトのライフサイクル：ステータス、名前変更、削除、復元、バージョン更新、インスタンスのサイズ変更、移管	projects	このファイル
サブスクリプション／プラン、クレジット、使用状況、支払い履歴、請求サイクル、プランのアップグレード、請求ポータル	billing、usage	このファイル
組織とメンバー（作成、更新、招待、ロール、退出、削除）	orgs	このファイル
プロジェクトのバックアップ（一覧、最新、作成、名前変更、削除、復元 — クラウドおよびセルフホスト可能）	backups	このファイル
Advisor のスキャンと検出結果の抑制（誤検知、許容したリスク）	advisor、diagnose advisor	このファイル
スキーマ、SQL、RLS、トリガー、インデックス、インポート、エクスポート	db	references/database/*
認証リダイレクト、パスワードポリシー、SMTP、ストレージサイズ、リアルタイム／スケジュールの保持期間、サブドメイン設定	config	references/config.md
ストレージバケットとオブジェクト	storage	このファイル
リアルタイムバックエンドのセットアップ	db マイグレーション	references/realtime.md
エッジ関数	functions	references/functions-deploy.md
AI／OpenRouter キーのセットアップと Model Gateway の使用概要	ai setup、ai overview	このファイル
エージェントのメモリ：セッションをまたいだプロジェクトの事実、決定事項、好み、参照情報	memory	references/memory.md
Stripe／Razorpay キー、カタログ同期、Webhook	payments	references/payments/overview.md
フロントエンドのデプロイ	deployments	references/deployments/deploy.md
カスタムドメイン、Cloudflare Registrar、DNS 同期、SSL 検証	domains	references/deployments/domains.md
バックエンドコンテナ／サービス	compute	references/compute-deploy.md
シークレット／環境変数	secrets、deployment／compute の環境変数コマンド	このファイル
スケジュール済みジョブ	schedules	references/schedules.md
バックエンドブランチ	branch	references/branch/overview.md、references/branch/merge.md、references/branch/reset.md
ログとヘルスチェック	logs、diagnose	references/diagnostics.md
組み込みのドキュメント検索	docs	このファイル
PostHog のセットアップ	posthog setup	references/posthog.md
Apify ウェブスクレイパー（接続、認証ブリッジ、スクレイピング、ランディング、スケジュール）	webscraper apify	references/webscraper/apify.md
InsForge 側のバグ、ドキュメントの不一致、設計上の問題を報告	feedback	このファイル

データベースのワークフロー

タスクに複雑なデータベース作業が含まれる場合は、マイグレーションを作成する前にデータベース関連のリファレンスを参照してください。

• references/database/migrations.md - マイグレーションファイルの作成と適用のワークフロー。
• references/database/query.md - 生 SQL の実行と対象を絞った調査。
• references/database/access-control.md - RLS、権限付与、再帰を安全に処理するヘルパー関数、ACL、保護対象フィールド、公開用プロジェクション。
• references/database/integrity.md - 制約、トリガー、派生状態、ライフサイクルガード、追記専用の履歴、サーバー管理フィールド。
• references/database/vector.md - pgvector 拡張、ベクトルスキーマ、距離演算子、インデックス、ベクトル検索の SQL/RPC パターン。
• references/database/export.md / references/database/import.md - スキーマまたはデータのインポート／エクスポートタスク。

基本パターン：

• スキーマ、権限付与、インデックス、トリガー、関数、RLS ポリシーの変更には、npx -y @insforge/cli db migrations new <name> とマイグレーション SQL ファイルを優先してください。
• npx -y @insforge/cli db migrations up --all でマイグレーションを適用してください。
• 新しいスキーマを作成する場合は、可能であれば関連する DDL を 1 つのマイグレーションにまとめてください。
• 既存の状態が不明な場合やコマンドが失敗した場合は、対象を絞って調査してください。
• 対象を絞った調査や、マイグレーションが適切でない場合の小規模な修正用の行／データ SQL には、npx -y @insforge/cli db query <sql> を使用してください。
• バックエンド経由でデータベース関数を呼び出すには、npx -y @insforge/cli db rpc <fn> [--data <json>] を使用してください。

公開スキーマの範囲：

• 汎用的なアプリケーションデータベースの作業では、アプリ所有のオブジェクトを public スキーマ内に作成、変更してください。
• public 内のアプリケーションオブジェクトに対する作成、変更、削除、権限付与、権限取り消し、インデックス、トリガー、関数、ビュー、ポリシーの変更を行ってください。
• 特定の機能モジュールに取り組んでおり、そのドキュメントで操作が明示的に許可されている場合を除き、カスタムスキーマや、auth、storage、realtime、payments、graphql、extensions、pg_catalog、information_schema、system などの InsForge 管理／システムスキーマを作成または書き込みしないでください。
• public テーブルまたは public RLS ポリシーから auth.users(id) や auth.uid() などの組み込みオブジェクトを参照することは許可されています。これらの組み込みオブジェクトは変更しないでください。
• ユーザーの依頼でデータ移行、修復、またはテストのセットアップが明示的に求められている場合を除き、ユーザーを作成したり、業務データの行をシードしたり、アプリケーションの CRUD ワークフローを実行したりしないでください。

RLS とアクセス制御：

• ユーザーの所有権チェックには、auth.uid() または同等の認証済み ID 式を使用してください。
• SQL 権限と RLS ポリシーの両方を追加してください。ポリシーは GRANT の代わりにはなりません。
• ランタイムロールには、RLS が行アクセスを判断できるよう、public テーブルに対する広範なデフォルト DML 権限が付与されています。テーブルで操作または列へのアクセスをより限定する必要がある場合は、広範な権限を明示的に REVOKE してから、許可する操作または列だけを付与してください。
• ユーザーが所有すべきでない行を作成できないように、INSERT と UPDATE のポリシーには WITH CHECK を含めてください。
• 直接的なポリシー結合が他の RLS ポリシーを介して再帰する可能性がある場合は、テーブル間の RLS チェックにヘルパー関数を優先してください。
• RLS ポリシーから呼び出され、RLS が有効なテーブルを検索するヘルパー関数には、SECURITY DEFINER を指定してください。
• RLS ヘルパー関数は public に配置し、public.team_members や auth.uid() などの参照をスキーマ修飾してください。
• ACL、保護対象の所有者／テナント／ロールフィールド、フィールドレベルの更新マスク、サニタイズされた公開ビュー、または再帰に注意が必要なポリシーについては、マイグレーションを作成する前に references/database/access-control.md を読んでください。

整合性：

• カウンター、残高、最新ポインター、追記専用の履歴、状態遷移、ライフサイクルガード、保護された削除、クォータガード、リース、またはトリガー管理列については、マイグレーションを作成する前に references/database/integrity.md を読んでください。

ベクトル：

• pgvector、ベクトル検索関数、スコアの意味、ANN インデックス、ハイブリッドランキング、RAG チャンク取得、マルチベクトル検索、または埋め込みのバージョン選択については、マイグレーションを作成する前に references/database/vector.md を読んでください。

プロジェクトと設定

プロジェクトのコマンド：

• npx -y @insforge/cli create - 新しいプロジェクトを作成します。対話なしのエージェント実行では、必須フラグとともに --json を使用します。references/create.md を参照してください。
• npx -y @insforge/cli link - 現在のディレクトリを既存のプロジェクトにリンクします。
• npx -y @insforge/cli link --api-base-url <url> --api-key <admin key> - URL と管理者 API キーを指定して、セルフホスト可能（OSS）なバックエンドに直接リンクします。プラットフォームへのログインは不要です。
• npx -y @insforge/cli current - 現在リンクされているプロジェクトを表示します。
• npx -y @insforge/cli metadata --json - 検出が必要な場合に、バックエンドのメタデータを確認します。

プロジェクトのライフサイクル（--project <id> が指定されていない場合は、リンク済みのプロジェクトを操作します）：

• npx -y @insforge/cli projects get [--project <id>] - プロジェクトの現在のステータス、処理中の operation_status、リージョン、インスタンスタイプ、バージョンを表示します。非同期操作（復元、バージョン更新、インスタンスのサイズ変更）の後に、operation_status がクリアされるまでポーリングするために使用します。
• npx -y @insforge/cli projects update [--name <name>] [--domain <domain>] [--project <id>] - プロジェクトの名前を変更するか、カスタムドメインを設定します。ディスクサイズの変更は InsForge サポートに依頼してください。
• npx -y @insforge/cli projects restore [--project <id>] - 一時停止中のプロジェクトをオンラインに戻します。復元できるのは一時停止中のプロジェクトのみです。
• npx -y @insforge/cli projects update-version [--wait] [--project <id>] - バックエンドを最新の InsForge バージョンに更新します（自動的に解決され、すでに最新の場合は何も行いません）。短時間の再起動が発生します。キューに追加された時点で戻るのではなく、完了するまで待機するには --wait を追加します。
• npx -y @insforge/cli projects upgrade-instance <type> [--project <id>] - インスタンスクラスを変更します。有効な値：nano、micro、small、medium、large、xl（上限は xl）。プロジェクトが再起動し、料金が変わります。
• npx -y @insforge/cli projects delete --project <id> - プロジェクトとそのすべてのリソースを完全に削除します。--project は必須です（リンク済みのプロジェクトがデフォルトで使用されることはありません）。取り消しできません。実行前に、ユーザーに正確なプロジェクト ID を確認してください。これは人間の確認を伴うガード付き操作なので、確認を自動的に回避しないでください。
• npx -y @insforge/cli projects transfer <targetOrgId> --project <id> - プロジェクトを別の組織に移動します（請求とアクセス権も移動します）。--project は必須です（リンク済みのプロジェクトがデフォルトで使用されることはありません）。人間の確認を伴うガード付き操作です。実行前に、移動元のプロジェクトと移動先の組織を確認してください。

設定：

• サポートされている insforge.toml の設定項目には、npx -y @insforge/cli config export、config plan、config apply を使用します。
• TOML は設定値のみに使用します。SQL は db migrations に、関数コードは functions deploy に、フロントエンドコードは deployments deploy に、コンピューティングコード／イメージは compute deploy に配置します。
• config apply が skipped[] を返した場合は、スキップされた項目と必要なバックエンドのアップグレードを報告してください。生の HTTP リクエストで再試行しないでください。

組織とメンバー

組織スコープのコマンドでは、次の順序で組織が解決されます：--org-id フラグ、INSFORGE_ORG_ID、リンクされたプロジェクトの組織、設定済みのデフォルト組織、プロンプト（または組織が1つだけの場合は自動選択）。特定の組織に対して操作するには、--org-id <id> を指定します。

• npx -y @insforge/cli orgs list - 所属している組織を一覧表示します。
• npx -y @insforge/cli orgs create <name> [--type personal|team|company] - 組織を作成します（デフォルトの種類は team です）。
• npx -y @insforge/cli orgs update [--name <name>] [--type <type>] [--org-id <id>] - 組織名または組織の種類を変更します。
• npx -y @insforge/cli orgs members list [--org-id <id>] - メンバーと保留中の招待を一覧表示します。
• npx -y @insforge/cli orgs members invite <email> [--role administrator|developer] [--org-id <id>] - メンバーを招待します（デフォルトのロールは developer です）。
• npx -y @insforge/cli orgs members role <memberId> <role> [--org-id <id>] - メンバーのロール（administrator または developer）を変更します。
• npx -y @insforge/cli orgs members remove <memberId> [--org-id <id>] - メンバーを削除します。先に実行する意思を確認してください。
• npx -y @insforge/cli orgs leave --org-id <id> - 組織から退出します。--org-id は必須です（リンクされた組織はデフォルトとして使用されません）。その組織のすべてのプロジェクトへのアクセスを失い、再び参加するには再招待が必要です。最後の管理者である場合、バックエンドは退出を拒否します。先に管理者ロールを譲渡してください。ガード付きで、人間の確認を伴う操作です。先に実行する意思を確認してください。
• npx -y @insforge/cli orgs delete --org-id <id> - 組織を完全に削除します。--org-id は必須です（リンクされた組織はデフォルトとして使用されません）。オーナーのみ実行できます。削除は連鎖的に行われます。組織内のすべてのプロジェクト（データベース、ストレージ、すべてのリソース）が完全に削除され、サブスクリプションもキャンセルされます。CLI は影響を受けるプロジェクトを一覧表示し、現在リンクされているプロジェクトがその中に含まれる場合は警告します。取り消しできません。先にユーザーに正確な組織 ID を確認し、確認を自動的に回避しないでください。

請求と使用状況

組織のプランや使用状況を確認し、サブスクリプションを管理します。組織の解決方法は「組織」セクションと同じです。

• npx -y @insforge/cli billing status [--org-id <id>] - 現在のサブスクリプション／プランと期間を表示します。
• npx -y @insforge/cli billing credits [--org-id <id>] - クレジット残高と最近のクレジット取引を表示します。
• npx -y @insforge/cli billing history [--org-id <id>] - 過去の支払い／請求書を一覧表示します。
• npx -y @insforge/cli billing cycles [--org-id <id>] - 現在と過去の請求サイクルの期間を表示します。
• npx -y @insforge/cli usage [--org-id <id>] - 現在の請求期間の使用状況を表示します（概要とプロジェクトごとの内訳：データベース、ストレージ、エグレスなど）。
• npx -y @insforge/cli billing upgrade <plan> [--org-id <id>] - プランを変更するための Stripe チェックアウトを開始します（free | starter | pro | team | enterprise）。ホスト型のチェックアウト URL をブラウザーで開き、同時に表示します。--json を指定すると、JSON オブジェクト（{ checkoutUrl, sessionId }）を表示し、ブラウザーは開きません。ヘッドレス環境／CI ではこちらを使用してください。ユーザーがチェックアウトを完了するまで料金は発生しません。バックエンドでプランと管理者権限が検証されます。
• npx -y @insforge/cli billing manage [--org-id <id>] - Stripe カスタマーポータルを開き、サブスクリプション、支払い方法、またはキャンセルを管理します。ポータル URL をブラウザーで開き、同時に表示します。--json を指定すると、JSON オブジェクト（{ portalUrl }）を表示し、ブラウザーは開きません。ヘッドレス環境／CI ではこちらを使用してください。

バックアップ

--project <id> を指定しない場合、リンク済みのプロジェクトに対して操作します。クラウドプロジェクトとセルフホストプロジェクト（link --api-base-url <url> --api-key <key> でリンク済み）の両方で動作します。CLI は適切なバックエンドに自動的にルーティングします。明示的に --project <id> を指定した場合は、常にクラウドプロジェクトが対象になります。

• npx -y @insforge/cli backups list [--project <id>] - バックアップを一覧表示します。
• npx -y @insforge/cli backups latest [--project <id>] - 最新のバックアップを表示します。クラウドの場合は、最新のダンプファイルと署名付きダウンロード URL が表示されます。セルフホストの場合は、最も新しいバックアップレコードが表示されます（ダウンロード URL はありません）。
• npx -y @insforge/cli backups create [--name <name>] [--wait] [--project <id>] - バックアップを作成します。--name は省略可能です。指定する場合は、1～64 文字である必要があります。--wait を指定すると、キューに入った時点で戻らず、完了するまで待機します。
• npx -y @insforge/cli backups rename <backupId> <name> [--project <id>] - バックアップの名前を変更します（名前をクリアするには "" を指定します）。
• npx -y @insforge/cli backups delete <backupId> [--project <id>] - バックアップを削除します。先に実行する意思を確認してください。
• npx -y @insforge/cli backups restore <backupId> [--project <id>] - バックアップからプロジェクトを復元します。先に実行する意思を確認してください。クラウドの場合：プロジェクトの現在のデータベースとストレージを上書きします。バックアップ以降に書き込まれたデータはすべて失われます。セルフホストの場合：データベースのみを pg_restore --clean で復元します。バックアップ対象のテーブル内のデータは巻き戻されますが、バックアップ後に作成されたテーブルは削除されず、ストレージにも変更はありません。

ストレージ

• npx -y @insforge/cli storage buckets - バケットを一覧表示します。
• npx -y @insforge/cli storage create-bucket <name> [--private] - バケットを作成します。
• npx -y @insforge/cli storage delete-bucket <name> - バケットとすべてのオブジェクトを削除します。破壊的な操作を実行する意思を事前に確認してください。
• npx -y @insforge/cli storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort] - オブジェクトを確認します。
• npx -y @insforge/cli storage upload <file> --bucket <name> [--key <objectKey>] - オブジェクトをアップロードします。
• npx -y @insforge/cli storage download <objectKey> --bucket <name> [--output <path>] - オブジェクトをダウンロードします。
• npx -y @insforge/cli storage s3-keys list - S3 互換のアクセスキーを一覧表示します（シークレット値は表示されません）。
• npx -y @insforge/cli storage s3-keys create [--description <text>] - S3 アクセスキーを作成します。シークレットアクセスキーは作成時に一度だけ表示されるため、すぐに記録してください。
• npx -y @insforge/cli storage s3-keys delete <id> - S3 アクセスキーを削除します。このキーを使用しているツールは動作しなくなります。先に実行する意思を確認してください。

Postgres ポリシーを通じて実装されるストレージのアクセス制御動作については、ストレージ専用の製品ドキュメントまたは機能ガイダンスを参照してください。参照先のストレージドキュメントに明記されていない限り、ストレージの内部構造を汎用のパブリックスキーマデータベーステーブルとして扱わないでください。

リアルタイム

チャネルパターン、アプリテーブルのパブリッシュトリガー、チャネル／メッセージの RLS はマイグレーションを通じて作成します。references/realtime.md を参照してください。

エッジ関数

• npx -y @insforge/cli functions list - デプロイ済みの関数を一覧表示します。
• npx -y @insforge/cli functions code <slug> - 関数のソースを表示します。
• npx -y @insforge/cli functions deploy <slug> --file <path> - デプロイまたは更新します。references/functions-deploy.md を参照してください。
• npx -y @insforge/cli functions invoke <slug> [--data <json>] [--method GET|POST] - 関数を呼び出します。
• npx -y @insforge/cli functions delete <slug> - 関数を削除します。破壊的な操作を実行する意思を事前に確認してください。

AI ゲートウェイ

• npx -y @insforge/cli ai setup は、リンク済みプロジェクトの有効な OpenRouter キーを取得し、ローカルのサーバーサイド環境変数ファイルに OPENROUTER_API_KEY を書き込みます。
• npx -y @insforge/cli ai overview は、Model Gateway キーの使用状況（合計支出、上限、残りのクレジット、日次／週次／月次の支出、可観測性が利用可能な場合はモデルごとのアクティビティ）を表示します。金額は USD クレジットです。「AI クレジットの残量／使用量」を確認する際に使用してください。
• OPENROUTER_API_KEY はサーバー側のみに保持してください。NEXT_PUBLIC_*、VITE_*、PUBLIC_*、REACT_APP_* として公開しないでください。

メモリ

すべてのプロジェクトには、セッションをまたいで保持される永続的な事実、決定、好み、参照情報を記録するエージェントメモリが組み込まれています。後回しにせず、習慣として活用してください。

• npx -y @insforge/cli memory list - AI を呼び出さずにタイトルの一覧を取得します。重要なタスクを始めるときに実行し、タスクに関連するタイトルがあれば内容を呼び出してください。
• npx -y @insforge/cli memory recall "<query>" [--scope] [--limit] [--threshold] - 意味検索とキーワード検索でメモリを呼び出します。
• npx -y @insforge/cli memory remember "<content>" [--kind] [--title] [--scope] [--source] - 1つの独立したメモリを保存します。決定や注意点はセッションの終了時ではなく、発生した時点で記録してください。--kind に指定できるのは fact、decision、preference、reference のみです。注意点は fact として保存してください（選択内容を記録する場合は decision）。
• npx -y @insforge/cli memory remember --file <path> - 文字起こしやメモのファイルから、長期的に保持すべきメモリを抽出します。

保存は冪等です。すでに記録されている事実を再度記録しても何も起こらず、既存の事実と矛盾する内容を記録すると、重複して保存されるのではなく既存のメモリが更新されます。事実が変わった場合は、新しい事実を remember してください。保存する内容、種類、例については references/memory.md を参照してください。

決済

Stripe／Razorpay のバックエンド設定とカタログ同期には payments を使用してください。references/payments/overview.md を参照してください。

• 決済プロバイダーごとにコマンドを指定してください。payments stripe ... または payments razorpay ... を使用します。
• payments <provider> config set でプロバイダーのキーを設定します。キーまたはアカウントが変更されると、プロバイダーの状態は自動的に同期されます。
• payments <provider> status でキー、アカウント、同期、Webhook の状態を確認します。
• ミラーリングされたプロバイダーデータを手動で更新または再試行するには、payments <provider> sync を実行します。
• Stripe は Products／Prices を使用し、Webhook 登録の管理に対応しています。Razorpay は Items／Plans／Orders を使用し、Razorpay Dashboard での手動による Webhook 設定が必要です。
• 開発中はテストモードを優先してください。ライブモードを使用するのは、ユーザーが明示的に承認した後に限ります。
• バックエンドで決済が利用できないと報告された場合は、ユーザーまたは管理者に決済の有効化、あるいはプランのアップグレードを依頼してください。プロバイダーのキーを汎用シークレットとして保存したり、決済のシークレットキーをアプリコードに埋め込んだりして回避しないでください。
• プロバイダー固有の設定を行う前に、references/payments/stripe.md または references/payments/razorpay.md を読み込んでください。

ランタイムのチェックアウト、サブスクリプション、カスタマーポータルのフロー、アプリコードについては、insforge のアプリ統合スキルを参照してください。

デプロイ

フロントエンドのデプロイ：

• アプリにビルド手順がある場合は、まずローカルでビルドしてください。
• デプロイ前に、フロントエンドのランタイム環境変数に、正しいフレームワークのプレフィックスが設定されていることを確認してください。
• フロントエンドのソースディレクトリには npx -y @insforge/cli deployments deploy <dir> を使用してください。デプロイのリファレンスで明示的に指定されていない限り、生成された出力ディレクトリはデプロイしないでください。
• references/deployments/deploy.md を参照してください。

カスタムドメイン：

• カスタムドメイン、Cloudflare Registrar、DNS 同期、SSL 検証には npx -y @insforge/cli domains ... を使用してください。
• references/deployments/domains.md を参照してください。

バックエンドのコンピューティングサービス：

• npx -y @insforge/cli compute ... を使用してください。ユーザー自身の flyctl アカウントを使って InsForge のコンピューティングサービスを直接管理しないでください。
• Dockerfile を含むディレクトリにはソースモードを、ビルド済みイメージには --image <url> を指定するイメージモードを使用してください。
• サイズの大きなインライン JSON を使う代わりに、シークレットには --env-file または繰り返し指定できる env-set／update コマンドを使用してください。
• references/compute-deploy.md を参照してください。

シークレット

• npx -y @insforge/cli secrets list [--all] - 値を表示せずにシークレットキーを一覧表示します。
• npx -y @insforge/cli secrets get <key> - 必要な場合にのみシークレットの値を取得します。
• npx -y @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>] - シークレットを作成します。
• npx -y @insforge/cli secrets update <key> [--value] [--active] [--reserved] [--expires] - シークレットを更新します。
• npx -y @insforge/cli secrets delete <key> - シークレットを論理削除します。先に実行する意図を確認してください。
• npx -y @insforge/cli secrets rotate <api-key|anon-key> [--grace-hours <n>] - プロジェクトの API キーまたは anon キーをローテーションします。新しいキーは一度だけ表示されるため、必ず保存してください。猶予期間中は古いキーも引き続き使用できます（--grace-hours を省略した場合はサーバーのデフォルト値が適用されます）。期限が切れる前に、すべての利用箇所を更新してください。

スケジュール

• npx -y @insforge/cli schedules list/get/create/update/delete/logs。
• 実時間に基づくスケジュールには、標準的な 5 フィールドの cron を使用します。
• 1 分未満の実行間隔には、30 seconds などの pg_cron 間隔構文を使用します。秒を含む 6 フィールドの cron はサポートされていません。
• ヘッダーでは、${{secrets.KEY_NAME}} を使って InsForge のシークレットを参照できます。
• cron の形式、シークレットヘッダーの参照、例、よくある間違い、おすすめの設定ワークフローについては、references/schedules.md を参照してください。

ブランチ

リスクの高いスキーマ、RLS、認証、または関数の変更を本番環境に適用する前に、バックエンドブランチを使ってテストしてください。references/branch/overview.md を参照してください。

よく使うコマンド：

• npx -y @insforge/cli branch create <name> [--mode full|schema-only] [--no-switch]
• npx -y @insforge/cli branch list
• npx -y @insforge/cli branch switch <name> または --parent
• npx -y @insforge/cli branch merge <name> [--dry-run] [--save-sql <path>]
• npx -y @insforge/cli branch reset <name>
• npx -y @insforge/cli branch delete <name>

ブランチ機能を使用するには、対応するバックエンドバージョンが必要です。利用できない場合は、回避策を作り出すのではなく、バックエンドのバージョン制限を報告してください。

診断とログ

• npx -y @insforge/cli diagnose - ヘルスレポート全体を表示します。
• npx -y @insforge/cli diagnose --ai "<issue description>" - InsForge デバッグエージェントに、具体的なバックエンドの問題を診断してもらいます。
• npx -y @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] - EC2 メトリクスを表示します。
• npx -y @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] - アドバイザーの問題を表示します。Rule 列の値は、advisor suppress に指定する ID です。
• npx -y @insforge/cli diagnose db [--check <checks>] - データベースのヘルスチェックを実行します。
• npx -y @insforge/cli diagnose logs [--source <name>] [--limit <n>] - エラーログを集約して表示します。
• npx -y @insforge/cli logs <source> [--limit <n>] - 指定したソースのバックエンドログを表示します。

一般的なログソースには、function.logs、function-deploy.logs、postgres.logs、postgrest.logs、insforge.logs があります。よくあるデバッグの状況とソースの選択については、references/diagnostics.md を参照してください。

Advisor

バックエンドの Advisor は、プロジェクトをスキャンしてセキュリティ、パフォーマンス、健全性に関する検出結果を確認します。結果は diagnose advisor で確認し、スキャンと誤検知は advisor で管理します。

• npx -y @insforge/cli advisor scan - スケジュールを待たずに、今すぐスキャンを実行します。検出結果を修正した直後に再確認する場合に使用します。スキャンは非同期で実行されます（通常は1分もかかりません）。scan.status が completed になり、scan.scanId が advisor scan から返された ID と一致するまで diagnose advisor --json をポーリングし、その後に結果を確認してください。
• npx -y @insforge/cli advisor suppressions - 抑制された検出結果の一覧を表示します。
• npx -y @insforge/cli advisor suppress <ruleId> [--object <affectedObject>] --reason <reason> [--note <note>] - 理由を記録して検出結果を無視します。--object（検出結果の「Affected Object」の値をそのまま指定）を付けると、その該当箇所のみが抑制されます。付けない場合は、ルール全体が抑制されます。--reason には false_positive | accepted_risk | wont_fix | other のいずれかを指定します。other の場合は --note が必須です。抑制は次回のスキャンから適用されます（適用を確認するには advisor scan を実行してください）。抑制するのは、ユーザーが判断した検出結果に限ってください。レポートをきれいに見せるために抑制してはいけません。
• npx -y @insforge/cli advisor unsuppress <suppressionId> - 抑制を解除し、次回のスキャンで検出結果が再表示されるようにします。

フィードバック

InsForge ツールキットのどの部分（バックエンドプラットフォーム、SDK、CLI、エージェントスキル、ドキュメント）に問題が発生した場合も、InsForge チームに報告してから、回避策を使って作業を続けてください。報告するのは InsForge 側の問題のみです。ユーザー自身のアプリコードの問題は報告しないでください。

npx -y @insforge/cli feedback --json \
  --type bug \
  --component backend \
  --title "db policies create returns 500 on uppercase table names" \
  --detail "Creating an RLS policy on table \"Users\" returns 500; lowercase names work. Repro: create table with quoted uppercase name, then run policies create." \
  --area db \
  --command "insforge db policies create --table Users ..." \
  --error "<verbatim error output>" \
  --severity major

必須フラグ：

• --type：発生した問題の種類です。状況に応じて次のように指定してください。
  • 「これは動作しません」（ドキュメント／仕様上は動作するはず）→ bug
  • 「X を行うよう指示されましたが、実際には別の方法が必要でした」→ 同じく bug。この場合は --doc（指示が記載されている場所）、--expected（指示で説明されていた内容）、--workaround（代わりにうまくいった方法）も指定してください。指示が古くなっているのか、製品に不具合が生じたのかは判断できません。この 3 つのフィールドがあれば、チームが原因を切り分けられます。
  • 「実現したいことがサポートされていません」→ feature-request
  • 「動作はしますが、わかりにくい、または使いにくいです」（役に立たないエラー、余計な手順が必要など）→ friction
  • その他 → other
• --component：ツールキット内の該当箇所です。backend（プラットフォーム／ホスト型サービス） | sdk | cli | skills（エージェントスキルの内容） | docs | other から選択します。
• --title と --detail（または --file <path>）。

任意のフラグ：

• --language：--component sdk の場合は必須です。該当する SDK を指定します。例：js、python、flutter、swift、kotlin、rest-api。複数の SDK にまたがる場合は multiple を指定してください。言語別のドキュメントページについて報告する場合は、--component docs と併用することもできます。その他のコンポーネントでは省略してください。
• --area：製品領域です。db | auth | storage | functions | deployments | billing | ai | realtime | payments から選択します。--component とは独立しています。たとえば、Python SDK でストレージのアップロードに問題がある場合は、--component sdk --language python --area storage と指定します。
• --workaround：問題を回避するために使った方法です。見つかった場合は必ず指定してください。問題がどの程度作業を妨げているかをチームに伝えられ、多くの場合、ドキュメントの修正にも役立ちます。
• --command（問題が発生した CLI／SDK の呼び出し）、--error（出力をそのまま記載します。機密情報は自動的に削除され、長い出力は切り詰められます）、--expected（ドキュメント／スキルで指示された内容、または想定していた内容）、不一致の報告に使う --doc "<page or skill section>"、および --severity blocker|major|minor（デフォルトは minor）。

--detail は簡潔にし、InsForge に関する内容に絞ってください。何が起きたか、何を期待していたか、最小限の再現手順を記載します。ユーザーのアプリデータは貼り付けないでください。CLI は一般的なパターン（メールアドレス、既知の認証情報／キー形式、シークレットの代入、パブリック IPv4 アドレス、ホームディレクトリのユーザー名）をローカルで削除し、長いフィールドを切り詰めます。ただし、削除処理はパターンに基づくものであり、安全策であって、何でも記載してよいという意味ではありません。ログインは不要です。ログアウト状態でも OSS 環境でも利用できます。クラウドプロジェクトがリンクされている場合は、プロジェクト／組織のコンテキストが自動的に付加されます。成功するとフィードバック ID が返されます（重複した報告は既存の報告に統合され、その ID が返されます）。

ドキュメント

• npx -y @insforge/cli docs - ドキュメントのトピックを一覧表示します。
• npx -y @insforge/cli docs instructions - セットアップガイドです。
• npx -y @insforge/cli docs <feature> <language> - db、storage、functions、auth、ai、realtime のいずれかの機能について、typescript、swift、kotlin、rest-api のいずれかの言語のドキュメントを表示します。

InsForge または @insforge/sdk を使ったアプリケーションコードでは、insforge アプリ統合スキルを使い、docs は公式の機能リファレンスとしてのみ利用してください。

PostHog

• npx -y @insforge/cli posthog setup を実行すると、ダッシュボードに PostHog の接続があることを確認し、公式の PostHog ウィザードコマンドに加えて、接続済みプロジェクトの公開 phc_ API キーとホストを表示します。
• ⚠️ posthog setup を実行しただけでは、アプリへの計測は行われません。ウィザードの手順を実行するまでは、環境変数も SDK もイベントも設定されません。ウィザードは対話形式で、ブラウザーを開く場合があります。実際のターミナルで実行するようユーザーに依頼するか、表示された phc_ キーとホストを使用して手動で計測を設定してください（PostHog の公開クライアントキーであり、フロントエンドの環境変数に設定しても安全です）。
• クラウドのみが対象です。セルフホストのバックエンドではインテグレーションを利用できません。別の PostHog アカウントの phc_ キーをアプリの環境変数に設定しないでください。Analytics ページは、posthog setup でのみ設定されるサーバー側の接続情報を読み込みます。表示されたキーを使用してください。

Apify ウェブスクレイパー

• npx -y @insforge/cli webscraper apify connect — 初回のみ実行する OAuth 接続です。更新可能なトークンを InsForge に保存します。
• npx -y @insforge/cli webscraper apify login — 認証ブリッジです。InsForge が管理するトークンを取得し、apify login --token を実行して、Apify の公式エージェントスキルをインストールします。apify login 単体（ブラウザー OAuth）は実行しないでください。Apify で 401 や「ログインしていません」というエラーが発生した場合は、login を再実行してください。
• スクレイピングから取り込み、スケジュール設定までのワークフローと、サイズに基づく取り込み方法については、references/webscraper/apify.md を参照してください。

非対話型 CI/CD

自動化された環境では、環境変数と JSON モードを使用してください。

INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD npx -y @insforge/cli login --email -y
npx -y @insforge/cli link --project-id $PROJECT_ID --org-id $ORG_ID -y
npx -y @insforge/cli db query "SELECT 1 AS ok" --json

プロジェクト設定ファイル

create または link の実行後、.insforge/project.json には、リンク済みプロジェクトの ID、アプリキー、リージョン、API キー、バックエンド URL が含まれます。

• .insforge/project.json をコミットしたり、公開したりしないでください。
• 手動で編集しないでください。プロジェクトの切り替えには、npx -y @insforge/cli link またはブランチコマンドを使用してください。