insforge-cli

バックエンドが要るとき、または InsForge の裏側の設定や基盤を CLI で触るときに効きます。InsForge の公式のスキルで、扱うのはプロジェクト、SQL と移行、行レベルのアクセス制御（RLS）、関数、保存、バックアップ、配置、秘密の値、定期実行、ログ、ブランチ、課金などです。

アプリのコードから SDK で使う側は、同じリポジトリの insforge の受け持ちだと冒頭で分けています。

頼みごとから CLI の分野への振り分けの表

27 行

必ず守る決まり

8 項目

同梱ファイル（2026-10-23 時点）

30 件

SKILL.md の大きさ（2026-10-23 時点）

41,448 バイト

まず接続を整えてから書く

まだプロジェクトが結び付いていないときは、アプリのコードを書く前に接続を整えるよう決めています。your-project.region.insforge.app のような仮の値で組み立てることは禁じられています。

1. ログインを確かめるwhoami。ブラウザが CLI に戻れない環境では 2 段の端末ログイン
2. プロジェクトを結ぶ既存なら link、新しく頼まれたら create
3. 本物の値で組むCLI から受け取った URL と鍵で作る

CLI は必ず npx -y @insforge/cli <command> で動かします。-y を外すと npx が導入の確認で止まり、エージェントのシェルでは永久に待つため、と理由も書かれています。

頼みごとごとの分野

振り分けの表は 27 行で、ログイン、プロジェクト、手元の Docker、課金、組織、バックアップ、診断、データベース、設定、保存、リアルタイム、関数、AI、記憶、決済、画面の配置、独自ドメイン、コンテナ、秘密の値、定期実行、ブランチ、ログ、文書、PostHog、Apify、不具合の報告などにまたがります。細部は分野ごとの手引き（同梱の 29 件）に置いています。

• データベースdb migrations new と移行の SQL で変え、db migrations up --all で当てる。中を見るのは db query
• アクセス制御auth.uid() で持ち主を確かめ、権限の GRANT と RLS の方針の両方を置く
• 配置画面は deployments deploy、裏側のコンテナは compute、関数は functions deploy
• ブランチ危ない変更を本番の前に試す。merge は必ず --dry-run から
• 記憶memory list で過去の決定を引き、決めたことと踏んだ穴を memory remember で残す

データベースの決まり

アプリの表は public のスキーマに作り、auth・storage・payments など InsForge が管理するスキーマには書き込みません。auth.users(id) や auth.uid() を参照するのは構いません。

RLS では、方針は GRANT の代わりにならないので両方を置き、挿入と更新の方針には WITH CHECK を付けます。利用者の作成や業務のデータの投入は、移行・修復・試験の準備を頼まれたときだけです。

アプリのコードを書くとき

フロントエンドやサーバー、エッジ関数から InsForge を呼ぶコードは insforge の受け持ちです。決済の画面や定期課金、顧客のポータルの流れも、アプリのコードの側だと本文は分けています。

InsForge 以外のバックエンド

同じ種類のサービスでも、Supabase を使うなら supabase のように、そのサービスの公式のスキルのほうが合います。

手元の Docker を、ログインの代わりに使いたいとき

既定はクラウドのプロジェクトです。手元の Docker で立てるのは利用者が明示したときだけで、ログインや create が面倒だからという理由の代わりには使わない、と書かれています。

取り消せない操作は、利用者の確かめを外さない

重い操作を並べます。どれも本文が「先に意図を確かめる」と書いているものです。

手元に立てた（self-hosted の）プロジェクトの復元は、データベースだけを pg_restore --clean で戻し、後から作った表は消さず、保存には触れません。

費用が動く操作

インスタンスの大きさを変える projects upgrade-instance は、プロジェクトを再起動し、請求も変わります（nano から xl まで）。ブランチは無料ではなく、1 本ごとに EC2 のインスタンスを 1 台使う、と手引きに書かれています。

料金の段を変える billing upgrade は Stripe の支払いの画面を開くだけで、利用者が支払いを終えるまで請求は起きません。AI の使用量は ai overview で、米ドルのクレジットの残りと使った額を確かめられます。

鍵は全権を持つ

InsForge の API の鍵は全権の管理者の鍵として扱い、サーバーの側だけに置き、フロントエンドや公開の環境変数に入れない決まりです。.insforge/project.json には API の鍵や接続先が入るので、コミットせず、手で書き換えません。

S3 互換の鍵（storage s3-keys create）と、入れ替えた API の鍵（secrets rotate）は、作った 1 回しか表示されません。入れ替えでは古い鍵が猶予の時間だけ使えるので、その間にすべての利用先を直します。

決済は試験モードから

決済は作っている間は試験モードを使い、本番のモードは利用者の明示の承認があってからです。決済が使えないと出たら、決済の鍵を一般の秘密の値として預けたり、アプリのコードに埋め込んだりして回避せず、管理者に有効化を頼みます。

ブランチの切り替えで .env は変わらない

branch switch は .insforge/project.json を書き換えますが、開発用のサーバーの .env は変えません。変更が見えない原因のいちばん多いものだと手引きは書き、URL と匿名用の鍵を読み直すよう求めています。

新しいブランチには、関数・画面・コンテナの中身が入っていないので、使う分を配置し直します。取り込みは必ず --dry-run で SQL を読んでからにし、親とブランチの両方が同じものを変えていれば止まります。

InsForge へ送る報告

InsForge の側の不具合や、文書と実際の食い違いに当たったら、feedback のコマンドで報告してから回避策で作業を続けるよう決めています。利用者のアプリのコードの問題は報告しません。

CLI は電子メールや鍵などの決まった形を手元で伏せますが、本文は「安全網であって許可ではない」とし、アプリのデータを貼らないよう書いています。ログインなしでも送れ、結び付いたクラウドのプロジェクトがあれば、その情報が自動で添えられます。

本文に書かれている操作

本文はほぼすべてが npx -y @insforge/cli のコマンドで、npm から CLI を取ってきて動かします。ほかに、端末ログインで timeout を使う例、CI でメールとパスワードを環境変数で渡すログインの例があります。

ブラウザの無い環境でログインできますか

できます。管理画面の Profile から API Keys で作った利用者の鍵を login --user-api-key に渡します。利用者のブラウザはあるが CLI の受け口に戻れない環境では、端末ログインを 2 段で行い、表示されたリンクとコードを利用者に伝えて承認を待ちます。

コマンドが失敗したとき、原因はどう見分けますか

終了コードが決まっています。1 は一般のエラー、2 は未ログイン、3 はプロジェクトが結ばれていない、4 は資源が無い、5 は権限が無い、です。裏側の状態は diagnose の健康診断や、logs の出どころごとの記録で調べます。

設定ファイルで変えられないものが出たら

config apply が skipped[] を返したら、飛ばされた項目と必要な裏側の更新を報告します。生の HTTP の呼び出しで CLI を回り込んでやり直すことは禁じられています。

診断の指摘を消してもいいですか

advisor suppress で、理由（誤検知・受け入れた危険など）を残して指摘を伏せられます。ただし伏せてよいのは利用者が判断した指摘だけで、報告をきれいに見せるために伏せるなと書かれています。