pp-supabase

Supabase — Printing Press CLI

前提条件：CLI のインストール

このスキルは supabase-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。

   npx -y @mvanhorn/printing-press-library install supabase --cli-only
   

2. 確認します：supabase-pp-cli --version
3. $GOPATH/bin（または $HOME/go/bin）が $PATH に含まれていることを確認します。

この CLI にパブリックライブラリのカテゴリが追加される前に npx でのインストールが失敗する場合は、Node をインストールするか、公開後にカテゴリ固有の Go による代替手段を使用してください。

インストール後に --version が「command not found」と報告する場合、インストール手順でバイナリが $PATH に追加されていません。確認が成功するまで、スキルのコマンドを実行しないでください。

この CLI を使用する場面

エージェントが組織を横断して Management API のエンティティを一括調査する場合、ローカル SQLite キャッシュからプロジェクト横断クエリを実行する場合（secrets where-name、functions inventory、branches drift、projects estate）、メールアドレスで Auth ユーザーを検索する場合（auth-admin lookup）、Storage バケットの使用状況を集計する場合（storage usage）、または型付きクエリの計画に使用するプロジェクトごとの PostgREST スキーマを取得する場合（pgrst schema）に、この CLI を使用してください。

ローカル Docker とマイグレーションのワークフロー（supabase start、supabase db push、supabase gen types）には、公式 Supabase CLI を使用してください。PostgREST の行の CRUD、Storage オブジェクトのライフサイクル（アップロード／ダウンロード／署名）、Auth Admin のユーザー変更、Edge Function ランタイムの呼び出しには supabase-js を使用してください。これらは、この CLI の初回リリースにおける既知のギャップとして記載されています（README の ## Known Gaps を参照）。

独自の機能

これらの機能は、この API 用のほかのツールでは利用できません。

プロジェクト横断の集計

• secrets where-name — 組織を横断して、指定した名前のシークレットを保持するすべてのプロジェクトと、それぞれの最終同期日時を検索します。

  エージェントがプロジェクト横断のセキュリティ状況について回答する必要がある場合に使用します（「STRIPE_KEY を持っているクライアントはどれか」「この名前のシークレットはどこかに漏えいしているか」など）。supabase-community MCP では、プロジェクトごとに反復処理しないと回答できません。

  supabase-pp-cli secrets where-name STRIPE_KEY --json
  

• functions inventory — スラッグ、バージョン、ステータス、最終デプロイ日時を含む、プロジェクトごと・組織ごとのすべてのエッジ関数の集計を表示します。

  デプロイのレビュー（「stripe-webhook をデプロイしたプロジェクトはどれか」など）や、古い関数の監査（「90 日間再デプロイされていない関数はどれか」など）に使用します。

  supabase-pp-cli functions inventory --org acme --json
  

• branches drift — マージも削除もされていない、N 日より古いプレビュー ブランチを親プロジェクトごとにまとめて一覧表示します。

  データベースリソースを消費するプレビュー ブランチの増加を防ぐため、週次のクリーンアップに使用します。

  supabase-pp-cli branches drift --older-than 7d --json
  

• projects estate — 関数数、ブランチ数、API キー数、シークレット名の数、最終同期日時を、プロジェクトごとに 1 行で集計します。

  月曜朝のプロジェクト全体のレビューに使用します。ダッシュボードの 12 個のタブを 1 画面にまとめられます。

  supabase-pp-cli projects estate --json
  

• auth-admin recent — 同期済みのプロジェクトを順に処理し、プロジェクトごとに Auth Admin を呼び出して、指定期間内に作成されたユーザーを 1 つのテーブルに集計します。

  組織のポートフォリオ全体にわたる週次のユーザー増加レビューに使用します。

  supabase-pp-cli auth-admin recent --since 7d --json
  

サービス固有のパターン

• auth-admin lookup — ドキュメントに記載された Auth Admin のユーザーページを順にたどり、正規化後に完全一致するメールアドレスのみを返します。必要に応じて、user_id を使ってユーザー名を持つ PostgREST コンテキストテーブルと結合できます。

  一致がない場合や重複している場合、不正なページや繰り返されたページがある場合、全ページの取得が完了しない場合、プロバイダーエラーが発生した場合は、検索は安全側に失敗します。無関係なユーザーレコードが表示されることはありません。

  supabase-pp-cli auth-admin lookup [email protected] --context-table profiles --context-key user_id --json
  

• pgrst schema — Management API からプロジェクトごとの PostgREST OpenAPI を取得し、型付きクエリの計画に使用するテーブル、列、型、検出されたインデックスを一覧表示します。

  型付きクエリを作成する前に使用すると、試行錯誤せずにテーブルの列型と制約を把握できます。

  supabase-pp-cli pgrst schema --table profiles --json
  

• storage usage — 各バケットのオブジェクトを一覧表示し、ファイル数、合計バイト数、最大オブジェクトを集計します。

  「ストレージ上限までどのくらいか」「最も大きいバケットはどれか」といった質問にエージェントが回答する必要がある場合に使用します。

  supabase-pp-cli storage usage --bucket avatars --json
  

コマンドリファレンス

branches — ブランチを管理します

• supabase-pp-cli branches delete-a-branch — 指定したデータベースブランチを削除します。デフォルトでは、すぐに削除されます。force=false を指定すると、削除をスケジュールできます...
• supabase-pp-cli branches get-a-branch-config — 指定したデータベースブランチの設定を取得します
• supabase-pp-cli branches update-a-branch-config — 指定したデータベースブランチの設定を更新します

oauth — OAuth 関連のエンドポイント

• supabase-pp-cli oauth authorize-project-claim — 指定したプロバイダーの OAuth 認証フローを開始します。認証が成功すると、ユーザーは...
• supabase-pp-cli oauth authorize-user — [ベータ] OAuth を通じてユーザーを認証します
• supabase-pp-cli oauth exchange-token — [ベータ] 認証コードをユーザーのアクセストークンとリフレッシュトークンに交換します
• supabase-pp-cli oauth revoke-token — [ベータ] OAuth アプリの認証と対応するトークンを取り消します

organizations — 組織関連のエンドポイント

• supabase-pp-cli organizations create-an — 組織を作成します
• supabase-pp-cli organizations get-an — 組織に関する情報を取得します
• supabase-pp-cli organizations list-all — 現在所属している組織の一覧を返します。

projects — プロジェクト関連のエンドポイント

• supabase-pp-cli projects create-a — プロジェクトを作成します
• supabase-pp-cli projects delete-a — 指定したプロジェクトを削除します
• supabase-pp-cli projects get — 認証済みユーザーが所有する特定のプロジェクトを取得します
• supabase-pp-cli projects get-available-regions — [ベータ] 新しいプロジェクトで利用できるリージョンの一覧を取得します
• supabase-pp-cli projects list-all — これまでに作成したすべてのプロジェクトの一覧を返します。
• supabase-pp-cli projects update-a — 指定したプロジェクトを更新します

snippets — スニペットを管理します

• supabase-pp-cli snippets get-a — 特定の SQL スニペットを取得します
• supabase-pp-cli snippets list-all — ログイン中のユーザーの SQL スニペットを一覧表示します

supabase-profile — Supabase プロフィールを管理します

• supabase-pp-cli supabase-profile — ユーザーのプロフィールを取得します

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせてください。

supabase-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 つの候補が見つかったことを示し、終了コード 2 は確実な候補が見つからなかったことを示します。その場合は --help に切り替えるか、より具体的な問い合わせを使用してください。

レシピ

プロジェクト横断のシークレット監査

supabase-pp-cli sync && supabase-pp-cli secrets where-name STRIPE_KEY --json

ローカルストアを同期してから、すべての組織にまたがって、STRIPE_KEY という名前のシークレットを保持するすべてのプロジェクトを一覧表示します。月曜朝のセキュリティチェックを、1 回のシェル呼び出しで実行できます。

サポートチケットのトリアージ

supabase-pp-cli auth-admin lookup [email protected] --context-table profiles --context-key user_id --agent --select user.id,user.email,user.last_sign_in_at,context.tier

ドキュメントに記載されたページネーションを使って Auth Admin をたどり、大文字と小文字を区別しない完全一致のメールアドレスを 1 件だけ確認してから、そのユーザーの profiles 行を結合します。--select を使うと、完全一致で返されるデータを、サポートワークフローに必要なフィールドに絞り込めます。

古くなったプレビューブランチ

supabase-pp-cli branches drift --older-than 14d --json

マージも削除もされていない、作成から 14 日を超えたプレビューブランチを、親プロジェクトごとにまとめて表示します。火曜日のクリーンアップ対象リストとして利用できます。

ストレージ上限の確認

supabase-pp-cli storage usage --json | jq '.[] | select(.total_bytes > 100000000)'

100MB を超えるすべてのバケットを一覧表示し、jq に渡してバイト数のしきい値で絞り込みます。

クエリ前の PostgREST スキーマ確認

supabase-pp-cli pgrst schema --table orders --agent --select tables.columns.name,tables.columns.type,tables.columns.nullable

Management API 経由のスキーマエンドポイントから orders テーブルの列型だけを取得することで、エージェントは試行錯誤することなく、型付きの PostgREST クエリを作成できます。

認証の設定

Supabase には、2 つの API ホストで使用する 3 種類の認証情報があります。api.supabase.com の Management API では、Personal Access Token（SUPABASE_ACCESS_TOKEN、ヘッダー Authorization: Bearer <PAT>）を使用します。<ref>.supabase.co のプロジェクト API では、apikey: ヘッダーを使用します。RLS に従う呼び出しには SUPABASE_PUBLISHABLE_KEY（または旧式の SUPABASE_ANON_KEY）を設定し、RLS をバイパスして Auth Admin エンドポイントを利用するサーバー側の呼び出しには SUPABASE_SERVICE_ROLE_KEY（または新しい SUPABASE_SECRET_KEY）を設定します。また、SUPABASE_URL=https://<ref>.supabase.co も設定してください。Edge Functions の注意点：キーは apikey: に指定し、Authorization: Bearer は決して使用しないでください。

supabase-pp-cli doctor を実行して設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout に JSON、stderr にエラーを出力します

• フィルター可能 — --select でフィールドを絞り込めます。ドット区切りのパスはネストされた構造をたどり、配列では各要素を順にたどります。出力の多い API でコンテキストを小さく保つのに不可欠です：

  supabase-pp-cli projects get mock-value --agent --select id,name,status
  

• プレビュー可能 — --dry-run でリクエストを送信せずに表示します

• オフライン対応 — sync/search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示せず、すべての入力をフラグで指定します

• 再試行を明示 — すでに存在する対象の作成を成功として扱う場合に限り --idempotent を使用し、削除対象が存在しない場合に成功として扱う場合に限り --ignore-missing を使用します

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をデータの出所を示すエンベロープでラップします：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を解析し、ライブかローカルかの確認には .meta.source を解析してください。人間が読みやすい N results (live) のサマリーは、stdout がターミナルの場合にのみ stderr に出力されます。パイプ経由の利用者やエージェントには、stdout に純粋な JSON が出力されます。

エージェントからのフィードバック

この CLI について気になる点に気づいたら、あなた（またはエージェント）が記録してください：

supabase-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
supabase-pp-cli feedback --stdin < notes.txt
supabase-pp-cli feedback list --json --limit 10

エントリーは ~/.supabase-pp-cli/feedback.jsonl にローカル保存されます。SUPABASE_FEEDBACK_ENDPOINT が設定され、かつ --send が渡された場合、または SUPABASE_FEEDBACK_AUTO_SEND=true の場合を除き、POST されることはありません。デフォルトの動作はローカル保存のみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なっていく部分です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は stdout に加えて（または stdout の代わりに）指定したシンクに送られるため、エージェントはコマンド結果を手動でパイプせずに振り分けられます。使用できるシンクは 3 種類です：

シンク	動作
stdout	デフォルト。stdout のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、サポートされているスキームを示す構造化エラーとともに拒否されます。Webhook の失敗時にはゼロ以外の値が返され、URL と HTTP ステータスが stderr に記録されます。

名前付きプロファイル

プロファイルは、呼び出しのたびに再利用するフラグ値の保存済みセットです。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

supabase-pp-cli profile save briefing --json
supabase-pp-cli --profile briefing projects get mock-value
supabase-pp-cli profile list --json
supabase-pp-cli profile show briefing
supabase-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は、実行時に情報を取得するエージェントが利用可能なプロファイルを見つけられるよう、available_profiles の下にすべてのプロファイルを一覧表示します。

終了コード

コード	意味
0	成功
2	使用エラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します：

1. 空、help、または --help → supabase-pp-cli --help の出力を表示
2. install で始まる → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照
3. それ以外 → 直接使用（CLI コマンドとして --agent を付けて実行）

MCP サーバーのインストール

この CLI の公開ライブラリエントリまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add supabase-pp-mcp -- supabase-pp-mcp

確認します：claude mcp list

直接使用する

1. インストール済みか確認します：which supabase-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の独自機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します：

   supabase-pp-cli <command> [subcommand] [args] --agent
   

4. 曖昧な場合は、サブコマンドのヘルプを確認します：supabase-pp-cli <command> --help。