pp-instagram

Instagram — Printing Press CLI

前提条件：CLI をインストールする

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

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

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

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

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go から直接インストールしてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/instagram/cmd/instagram-pp-cli@latest

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

複数の自社 Business／Creator アカウントを運用するマネージャー向けに構築された、Instagram Graph API 用のローカルファーストな分析 CLI です。アカウント、メディア、インサイト、競合のスナップショットをクエリ可能な SQLite ストアに同期し、公式ツールにはないビューを提供します。ブランドの横並びランキング（compare）、フォロワー数の経時的な伸び（growth）、最適な投稿時間、形式別の内訳、競合との差分などを確認できます。エージェント向けの出力、オフライン検索、型付き終了コードをすべての操作で利用できます。

この CLI を使用する場面

エージェントまたはオペレーターが、複数の自社 Instagram Business／Creator アカウントを横断した分析を必要とする場合に、この CLI を使用してください。ブランドの比較、フォロワーの伸びやエンゲージメントの推移の追跡、投稿のランキング、コンテンツ形式の分析、競合とのベンチマークに対応します。複数のアカウントにまたがる質問や、Graph API の短い期間では答えられない履歴が必要な場合に適しています。

使用しない場面

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

• 所有していない任意の公開プロフィールのスクレイピングや分析には使用しないでください。サポート対象は、自分の Pages にリンクされたアカウントと、公開 business_discovery スナップショットのみです。
• 主なコンテンツスケジューラーとして使用しないでください。--dry-run を指定した公開機能はありますが、この CLI は分析を主な用途としています。
• Facebook Page や Meta Ads の分析には使用しないでください。対象は Instagram のオーガニック領域のみです。
• リアルタイム／ストリーミング指標には使用しないでください。Graph のインサイトは日次または集計値であり、ライブデータではありません。

独自の機能

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

アカウント横断のポートフォリオ分析

• compare — 期間を指定して、リーチ、インタラクション、エンゲージメント率を基準に、すべてのブランドアカウントを横並びでランク付けします。

  エージェントが「自分のブランドのうち、どれが好調か」を個別のアカウントインサイト呼び出しを何度も行わず、ランキング表で確認する必要がある場合に使用します。

  instagram-pp-cli compare --since 30d --agent
  

• growth — ブランドごとのフォロワー数の経時的な伸びを、週ごとに追跡します。

  プロフィールのフィールドですでに確認できる時点のフォロワー数ではなく、トレンド（成長しているかどうか）について質問された場合に使用します。

  instagram-pp-cli growth --since 8w --agent
  

• rivals — ライバルとなる公開アカウントのフォロワー数とエンゲージメントの伸びを、同期ごとに追跡し、自社ブランドと比較します。

  単一の business_discovery 呼び出しでは答えられない、競合のトレンドに関する質問に使用します。

  instagram-pp-cli rivals --since 30d --agent
  

ローカル履歴から導出される分析

• best-time — 過去の投稿で最も高いエンゲージメントを獲得した曜日と時間帯を表示します。

  一般論ではなく、そのアカウント自身のデータに基づいて投稿スケジュールを提案する場合に使用します。

  instagram-pp-cli best-time --account acme --agent
  

• top-posts — 期間を指定して、リーチ、インタラクション、保存数、シェア数を基準に、ブランド全体の個々の投稿をランク付けします。

  メディアを手作業でページ送りして並べ替える代わりに、パフォーマンスの高いコンテンツをすばやく見つける場合に使用します。

  instagram-pp-cli top-posts --since 30d --metric reach --agent
  

• formats — リーチ、エンゲージメント、Reels の視聴時間を基準に、Reels、Feed、Story、Carousel を比較します。

  投稿ごとにインサイトを呼び出さず、集計結果から「このブランドにはどのコンテンツ形式が効果的か」を確認する場合に使用します。

  instagram-pp-cli formats --account bistro --agent
  

• hashtag-perf — 追跡中のハッシュタグを、それぞれの上位メディアのリーチとエンゲージメントを基準にランク付けします。

  ハッシュタグの ROI を比較する場合に使用します。新しいタグを見つけるには、組み込みのハッシュタグ検索を使用してください。

  instagram-pp-cli hashtag-perf --agent
  

コマンドリファレンス

account-insights — アカウントレベルのインサイト（リーチ、閲覧数、インタラクション、デモグラフィック）

• instagram-pp-cli account-insights demographics — 年齢、性別、都市、国別に分類した、フォロワーの累計デモグラフィック
• instagram-pp-cli account-insights list — 指定期間のアカウントインサイト（reach、accounts_engaged、total_interactions、views）

accounts — ブランドアカウントのプロフィール（ページにリンクされたInstagramビジネス／クリエイターアカウント）

• instagram-pp-cli accounts get — ブランドアカウントのプロフィールを取得します（フォロワー、フォロー、メディア数、自己紹介）
• instagram-pp-cli accounts pages — 管理しているFacebookページと、リンクされたInstagramビジネスアカウントのIDを一覧表示します

business-discovery — あらゆるビジネス／クリエイターアカウントの公開指標（競合調査）

• instagram-pp-cli business-discovery <ig_user_id> — business_discoveryフィールド式を使って、競合の公開データを取得します

comments — メディアへのコメントと返信

• instagram-pp-cli comments list — メディアオブジェクトへのコメントを一覧表示します
• instagram-pp-cli comments replies — コメントへの返信を一覧表示します

hashtags — ハッシュタグ検索と人気／最近のメディア

• instagram-pp-cli hashtags recent-media — ハッシュタグIDに関連する最近の公開メディア
• instagram-pp-cli hashtags search — ハッシュタグ文字列をIDに変換します（アカウントごとに7日間で最大30個の一意なタグ）
• instagram-pp-cli hashtags top-media — ハッシュタグIDに関連する、パフォーマンス上位の公開メディア

media — 投稿、リール、メディアごとのインサイト

• instagram-pp-cli media create — メディアコンテナを作成します（公開手順のステップ1）。分析を優先するCLIです。--dry-runを使用してください。
• instagram-pp-cli media get — IDで単一のメディアオブジェクトを取得します
• instagram-pp-cli media insights — メディアごとのインサイト（リーチ、閲覧数、保存数、シェア数、インタラクション、リールの視聴時間）
• instagram-pp-cli media list — ブランドのメディア（投稿、リール、カルーセル）を新しい順に一覧表示します
• instagram-pp-cli media publish — 作成済みのメディアコンテナを公開します（ステップ2）。
• instagram-pp-cli media publish-limit — コンテンツ公開枠の残数を確認します（過去24時間のローリング集計）

stories — アクティブなストーリーズ（24時間の期間）

• instagram-pp-cli stories <ig_user_id> — ブランドの現在アクティブなストーリーズを一覧表示します（24時間後に期限切れ）

tags — タグ付けされたメディア

• instagram-pp-cli tags <ig_user_id> — ブランドアカウントがタグ付けされた公開メディアを一覧表示します

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

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

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

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

レシピ

今月のエンゲージメントでブランドを順位付けする

instagram-pp-cli compare --since 30d --agent

所有するすべてのアカウントを対象に、順位付きの表を1つ作成します。Meta Business Suiteでは表示されない情報です。

エージェント向けにネストされたメディアインサイトを絞り込む

instagram-pp-cli media list 17841400000000000 --agent --select data.caption,data.media_product_type,data.like_count,data.comments_count

ブランドのIGユーザーID（「brands list」から取得）を渡します。メディアの応答は深くネストされているため、--selectで重要度の高いフィールドに絞り込み、エージェントが数十KBのデータを解析せずに済むようにします。

このブランドがいつ投稿すべきかを調べる

instagram-pp-cli best-time --account bistro --agent

ブランド自身の投稿履歴を曜日と時間ごとに分類し、一般論ではなくおすすめの投稿枠を提示します。

競合の成長を追跡する

instagram-pp-cli rivals --since 30d --agent

蓄積されたbusiness_discoveryのスナップショットを比較し、競合のフォロワー数やエンゲージメントの増減を算出します。

コンテンツ形式を比較する

instagram-pp-cli formats --account cafe --agent

リールの視聴時間を含め、リール、フィード、ストーリーズ、カルーセルを集計して比較します。

認証の設定

認証には、Facebook ログイン経由で利用する、ビジネスタイプのアプリの Meta Graph API アクセストークンを使用します。INSTAGRAM_ACCESS_TOKEN には、有効期間の長いユーザートークン、または（推奨）有効期限のないシステムユーザートークンを設定し、次のスコープを付与してください：instagram_basic、instagram_manage_insights、pages_show_list、pages_read_engagement、business_management。CLI は /me/accounts 経由で各ブランドの IG ユーザー ID を Pages から解決します。また、明示的に公開コマンドを実行しない限り、書き込み処理は行いません。'doctor' を実行して、トークンのスコープ、有効期限、解決されたアカウント ID を確認してください。

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

エージェントモード

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

• パイプ可能 — stdout には JSON、stderr にはエラーが出力されます

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

  instagram-pp-cli account-insights list 17841400000000000 --agent --select data.name,data.period
  

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

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

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

• 明示的な再試行 — 既存の作成が成功として扱われる場合にのみ、--idempotent を使用します

レスポンスエンベロープ

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

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

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

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

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

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

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

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

出力の配信

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

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

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

名前付きプロファイル

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

instagram-pp-cli profile save briefing --json
instagram-pp-cli --profile briefing account-insights list 17841400000000000
instagram-pp-cli profile list --json
instagram-pp-cli profile show briefing
instagram-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します：

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

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

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

   go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/instagram/cmd/instagram-pp-mcp@latest
   

2. Claude Code に登録します：

   claude mcp add instagram-pp-mcp -- instagram-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

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

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