pp-meta-ads

Meta Ads — Printing Press CLI

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

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

1. Printing Press インストーラーを使ってインストールします。デフォルトでは、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin にバイナリがインストールされます。

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

2. 確認します：meta-ads-pp-cli --version
3. スキルを実行するエージェント／ランタイムで、報告されたインストールディレクトリが $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を使った直接インストールに切り替えてください（Go 1.26.6 以降が必要です）。インストール先は $GOPATH/bin（デフォルトは $HOME/go/bin）なので、代わりにそのディレクトリを $PATH に追加します。

go install github.com/mvanhorn/printing-press-library/library/marketing/meta-ads/cmd/meta-ads-pp-cli@latest

インストール後に --version が「command not found」と報告する場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認に成功するまで、スキルのコマンドを実行しないでください。

この CLI を使用する場面

Meta の広告アカウント全体で、クリエイティブ疲労の診断、オーディエンスの重複状況の把握、学習フェーズのフォレンジック分析、アトリビューションのずれの検出を行う必要がある場合に、この CLI を使用します。トレンドに関するクエリを即座に実行できるよう、ローカルストアへ毎日同期する運用と組み合わせるのが最適です。読み取り専用設計のため、キャンペーン、予算、オーディエンスの変更には使用しません。

使用しない場面

この CLI は、次の用途には使用しないでください。

• キャンペーン、広告セット、広告、オーディエンス、クリエイティブの作成、一時停止、変更、削除には使用しないでください。読み取り専用です。
• 予算管理や入札戦略の変更には使用しないでください。その用途には Meta Ads Manager または facebook-business-sdk を使用します。
• 書き込みを伴うオーディエンスのアップロードには使用しないでください。顧客ファイルからのカスタムオーディエンスの作成は対象外です。

独自の機能

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

蓄積されるローカル状態

• fatigue — 設定可能な期間にわたって、CPM が上昇し、フリークエンシーが増加し、CTR が低下している広告を検出します。

  どの広告を終了するかの判断に使います。疲労したクリエイティブへの支出は、あらゆるアカウントで最も大きな無駄につながります。

  meta-ads-pp-cli fatigue --campaign 23847265 --window 14d --agent
  

• decay — クリエイティブの初回インプレッション時の CTR と現在の CTR を比較し、配信終了日の予測を表示します。

  単一のクリエイティブを終了するか更新するかの判断に使います。決め手となるのは傾向と予測終了日です。

  meta-ads-pp-cli decay --creative-id 120208734567 --agent
  

• overlap — カスタムオーディエンス間のペアごとの重複率を表示し、カニバリゼーションに関する推奨事項を提示します。

  広告戦略が成熟し、類似オーディエンス間で ROAS が分散していると感じる場合に使います。統合するか除外するかの判断材料を提示します。

  meta-ads-pp-cli overlap --audience 23847001 --audience 23847002 --audience 23847003 --agent
  

• learning — アルゴリズム学習が N 日を超えて停滞している広告セットを、根本原因のヒント（予算が少なすぎる、オーディエンスが狭すぎる、イベントが少なすぎる）とともに表示します。

  複数の広告セットで ROAS が同時に急落した場合に使います。学習が停滞した広告セットは、最適化されないまま予算を消費します。

  meta-ads-pp-cli learning --account act_4327210487520472 --min-days 7 --agent
  

フォレンジッククエリ

• reconcile — Meta が報告するアカウントの支出額と、インサイトの支出額合計を日ごとに比較し、アトリビューションのずれがしきい値を超える日を検出します。

  アトリビューション監査を毎月行う際に使います。Meta とインサイトの数値が一致しない具体的な日を特定します。多くの場合、コンバージョンのアトリビューションが遅延したことが原因です。

  meta-ads-pp-cli reconcile --account act_4327210487520472 --since 30d --threshold 5 --agent
  

• bottleneck — 支出額が最も高く ROAS が最も低い広告セットを、学習状態と有効ステータスを結合した「理由」列とともに順位付けして表示します。

  一時停止する対象を毎週決める際に使います。最も効果の大きい対象が最初に表示されます。

  meta-ads-pp-cli bottleneck --account act_4327210487520472 --limit 10 --agent
  

アカウントの健全性管理

• stale — N 日間インプレッションがゼロのアクティブな広告を表示します。

  アカウントの健全性を四半期ごとに確認する際に使います。インプレッションがゼロのアクティブな広告は、設定ミスか、削除後に残ったゾンビであることがほとんどです。

  meta-ads-pp-cli stale --days 90 --agent
  

• inventory — アカウント内のすべての広告を effective_status ごとに分類し、設定ステータスが 'ACTIVE' でありながら effective_status が 'WITH_ISSUES' または 'DISAPPROVED' の広告を表示します。

  毎朝、最初に使います。DISAPPROVED でありながら ACTIVE の広告は、配信されないまま実際の費用を発生させます。

  meta-ads-pp-cli inventory --account act_4327210487520472 --by effective_status --agent
  

コマンドリファレンス

adcreatives — 広告クリエイティブを管理します

• meta-ads-pp-cli adcreatives <adId> — 広告に関連付けられたクリエイティブを取得します

ads — 広告レベルの読み取り操作

• meta-ads-pp-cli ads <adAccountId> — 広告アカウント内の広告を一覧表示します

adsets — 広告セットレベルの読み取り操作

• meta-ads-pp-cli adsets <adAccountId> — ターゲティングの概要、予算、最適化目標、入札戦略を含む広告セットを返します。

campaigns — キャンペーンレベルの読み取り操作

• meta-ads-pp-cli campaigns <adAccountId> — ステータス、目的、予算のメタデータを含むキャンペーンを返します。

customaudiences — カスタムオーディエンスを管理します

• meta-ads-pp-cli customaudiences <adAccountId> — 広告アカウント内のカスタムオーディエンスを一覧表示します

delivery-estimate — 配信見積もりを管理します

• meta-ads-pp-cli delivery-estimate <adAccountId> — リーチ／インプレッションの配信見積もりを取得します

insights — パフォーマンスと配信に関するインサイト（クリエイティブ疲労の監視機能）

• meta-ads-pp-cli insights get-account — 広告アカウント全体の集計インサイトを返します。
• meta-ads-pp-cli insights get-ad — 頻度、CPM、CTRの推移を含む広告レベルのインサイトを返します。
• meta-ads-pp-cli insights get-ad-set — 広告セットレベルのインサイトを取得します
• meta-ads-pp-cli insights get-campaign — キャンペーンレベルのインサイトを取得します

me — 自分の情報を管理します

• meta-ads-pp-cli me — アクセストークンにアクセス権が付与されているすべての広告アカウントを返します。

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

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

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

which は、自然言語での機能に関するクエリを、このCLIの厳選された機能インデックス内で最適なコマンドに対応付けます。終了コード 0 は少なくとも1件の一致があることを示し、終了コード 2 は確度の高い一致がないことを示します。その場合は --help を使うか、クエリをより絞り込んでください。

レシピ

キャンペーン全体のクリエイティブ疲労をトリアージする

meta-ads-pp-cli fatigue --campaign 23847265 --window 14d --agent --select ad_id,ad_name,cpm_slope,frequency_now,ctr_slope,verdict

広告ごとに、CPMの傾き、現在の頻度、CTRの傾き、停止／継続の判定を1行で返します。疲労に関連するフィールドだけを選択して出力を絞り、エージェントのコンテキストを適切な範囲に保ちます。

オーディエンスのカニバリゼーションリスクを見つける

meta-ads-pp-cli overlap --audience 23847001 --audience 23847002 --audience 23847003 --agent

ペアごとの重複率と推奨事項を返します。30%を超える場合は、統合または除外の候補です。

学習フェーズから動かない広告セットを特定する

meta-ads-pp-cli learning --account act_4327210487520472 --min-days 7 --agent

learning_stage_info が7日を超えて LEARNING のままになっている広告セットを見つけます。「why」列には、予算／オーディエンス／イベントのデータ不足の可能性が示されます。

毎日の在庫状況をまず集計する

meta-ads-pp-cli inventory --account act_4327210487520472 --by effective_status --agent

すべての広告を effective_status ごとにグループ化します。DISAPPROVED でありながら設定上は ACTIVE の広告クラスは、日々の確認で最も価値の高い検出項目です。

月次の広告費を照合する

meta-ads-pp-cli reconcile --account act_4327210487520472 --since 30d --threshold 5 --agent

過去30日間について、Metaが報告したアカウントの広告費とインサイトの広告費合計を日ごとに比較します。差異が5%を超える日を警告します。

認証の設定

META_ACCESS_TOKEN 環境変数にMetaアクセストークンを設定して認証します。一時的な利用にはGraph API Explorerで生成したトークン（ユーザーアクセストークン、有効期間1～2時間）を、繰り返し利用する場合はBusiness Managerのシステムユーザー（有効期限なし）を使用します。ads_read スコープのみを許可してください。ads_management や書き込み権限は決して許可しないでください。/me/adaccounts によるトークンの検出で、そのトークンからアクセス可能なすべてのアカウントが一覧表示されるため、アカウントIDの設定は不要です。

meta-ads-pp-cli doctor を実行して設定を確認します。

エージェントモード

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

• パイプ可能 — 標準出力にはJSON、標準エラー出力にはエラーを出力します

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

  meta-ads-pp-cli ads mock-value --agent --select id,name,status
  

• プレビュー可能 — --dry-run でリクエストを送信せずに内容を確認できます

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

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

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票、招待、注文、送信など、データを変更するリクエストにはこのCLIを使用しないでください

応答エンベロープ

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

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

データには .results を、ライブデータかローカルデータかの判別には .meta.source を解析してください。人間が読みやすい N results (live) の概要が stderr に出力されるのは、stdout がターミナルであり、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合のみです。パイプ経由やエージェントからの利用、および形式を明示した実行では、stdout に純粋な JSON が出力されます。

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

この CLI に問題があることに（あなた自身、またはエージェントが）気付いたら、記録してください。

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

エントリーはローカルの ~/.local/share/meta-ads-pp-cli/feedback.jsonl に保存されます。META_ADS_FEEDBACK_ENDPOINT が設定され、かつ --send が指定されるか META_ADS_FEEDBACK_AUTO_SEND=true が設定されている場合を除き、POST されることはありません。デフォルトの動作はローカル保存のみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で記録してください。そこから改善が積み重なっていきます。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクへ送られるため、エージェントはコマンド結果を手動でパイプ処理せずに振り分けられます。次の 3 つのシンクがサポートされています。

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

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

名前付きプロファイル

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

meta-ads-pp-cli profile save briefing --json
meta-ads-pp-cli --profile briefing ads mock-value
meta-ads-pp-cli profile list --json
meta-ads-pp-cli profile show briefing
meta-ads-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は利用可能なすべてのプロファイルを available_profiles の下に一覧表示するため、実行時にプロファイルを調べるエージェントもそれらを検出できます。

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

1. MCP サーバーをインストールします。

   go install github.com/mvanhorn/printing-press-library/library/marketing/meta-ads/cmd/meta-ads-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add meta-ads-pp-mcp -- meta-ads-pp-mcp
   

3. 動作を確認します。claude mcp list

直接利用

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

   meta-ads-pp-cli <command> [subcommand] [args] --agent
   

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