pp-surgegraph

SurgeGraph — Printing Press CLI

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

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/ai/surgegraph/cmd/surgegraph-pp-cli@latest

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

この CLI を使用する場面

AI 検索に関するコンテンツ作業で SurgeGraph を操作する必要がある場合は、この CLI を使用してください。たとえば、AI Visibility の変化を監視する、記事を一括で作成・公開する、ナレッジライブラリへの影響を監査する、プロジェクトの現在の状態を別のエージェントに共有するといった作業に使えます。ウェブアプリで利用できる機能はすべて CLI コマンドとして用意されており、すべての transcendence コマンドは MCP ツールです。ループを開始したエージェントが、ターミナルを離れることなく処理を完了できます。

独自の機能

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

積み重ねていけるローカル状態

• visibility delta — AI Visibility で前週から何が変化したのかを、概要、トレンド、センチメント、トラフィック別に正確に確認できます。ダッシュボードのタブを2つスクリーンショットに撮り、手作業で差分を取る必要はありません。

  ユーザーが AI Visibility の変化について尋ねた場合や、変動レポートを求めている場合に使用します。追加の API 呼び出しを消費せずに回答できます。

  surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --metric overview,trend --agent
  

• visibility prompts losers — 引用数または1位の順位が前の期間より下がった、追跡対象のプロンプトを一覧表示します。毎週月曜日に CMO が求めるレポートを作成できます。ダッシュボードでは作成できません。

  ユーザーが可視性の低下を調査している場合に選択します。生データのスナップショットを2つ比較する代わりに、優先順位が付いた実行可能なリストをエージェントに提供します。

  surgegraph-pp-cli visibility prompts losers --project proj_abc123 --since 720h --agent --select prompt_id,prompt,citation_delta,position_delta
  

• visibility citation-domains rank-shift — 30日間にわたり、プロジェクトの AI 追跡対象プロンプトにおける引用シェアをどのドメインが獲得または失ったかを監視します。競合が回答セットで存在感を増し始めた場合に役立ちます。

  AI 回答における競合のシェア・オブ・ボイスを監視する場合に使用します。

  surgegraph-pp-cli visibility citation-domains rank-shift --project proj_abc123 --window 720h --agent
  

• docs stale — 過去 N 日間に更新されていないライター向けドキュメントと最適化済みドキュメントを、最近の AI ソースからのトラフィック順に一覧表示します。1回のクエリで更新キューを確認できます。

  コンテンツの更新キューの優先順位を決める場合に使用します。

  surgegraph-pp-cli docs stale --project proj_abc123 --older-than 90 --agent --select document_id,title,last_updated,ai_traffic_30d
  

• visibility portfolio — 組織内のすべてのプロジェクトについて、AI Visibility の変化を集計します。単一プロジェクトの UI では確認できない、エージェンシーのポートフォリオビューを提供します。

  ユーザーが複数のプロジェクト（エージェンシー、複数ブランド）を管理しており、経営向けの概要を求めている場合に使用します。

  surgegraph-pp-cli visibility portfolio --window 168h --agent
  

• account burn — 過去30日間の使用状況スナップショットに基づいて、クレジットが枯渇する見込みを算出します。大量の一括公開をキューに入れる前の事前確認に使えます。

  一括操作を開始する前に選択し、必要なクレジットがあることを確認します。

  surgegraph-pp-cli account burn --window 720h --agent
  

単一の API 呼び出しでは返せないエンティティ横断の結合

• knowledge impact — プロジェクトのナレッジライブラリを、その根拠付き URL が追跡対象の AI 引用に実際にどれだけ頻繁に現れるかでランク付けします —「このライブラリは維持する価値があるか？」に答えます。

  ユーザーがナレッジライブラリを監査するとき、またはどのライブラリが成果を上げているかを尋ねるときに選択します。

  surgegraph-pp-cli knowledge impact --project proj_abc123 --agent
  

• research drift — topic_research の階層マップを、すでに出荷済みの writer_documents と差分比較します — カバー済み vs ギャップを、対応優先度順にランク付けします。

  トピックリサーチからコンテンツスプリントを計画するときに使用します。どのサブトピックにまだ記事が必要かをエージェントに正確に伝えます。

  surgegraph-pp-cli research drift --research-id res_xyz789 --project proj_abc123 --agent --select topic,parent,covered
  

• research domain diff — 競合他社の domain_research トピックツリーを、自社の topic_research と集合差分比較します — 相手がカバーしていて自社がカバーしていないものを即座に把握できます。

  特定の競合他社に対してトピックカバレッジを比較するときに選択します。

  surgegraph-pp-cli research domain diff --project proj_abc123 --mine res_xyz789 --theirs dom_res_aaa --agent
  

• visibility traffic-citations — トラフィック上位の各ページについて、AI 引用がそのページに解決された追跡対象プロンプトを一覧表示します —「なぜこのページは AI トラフィックを得ているのか？」に答えます。

  トラフィックパターンを説明するとき、またはすでに AI クリックを集めているものに基づいて新しいコンテンツを計画するときに使用します。

  surgegraph-pp-cli visibility traffic-citations --project proj_abc123 --agent --select page_url,ai_visits,citations
  

プロダクトをまたぐ複合ワークフロー

• research gaps publish — トピックギャップの出力を受け取り、50 ドキュメント単位のバッチでドキュメントを一括作成し、それらを WordPress 連携にキューイングします — コンテンツ運用の儀式を 1 つの冪等なコマンドにまとめます。

  ユーザーがトピックリサーチのすべてのギャップに対して記事を出荷したいときに選択します。複数タブの手作業ワークフローを 1 回の呼び出しに集約します。

  surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run --agent
  

エージェントネイティブな配線

• context bundle — 1 つのプロジェクトについて、プロンプト、引用、ドキュメント、トピックマップを網羅する、エージェントのコンテキストウィンドウ向けに整形された JSON ブロブを出力します — エージェントのループが必要とするハンドオフペイロードです。

  別のエージェントのワーキングメモリに、SurgeGraph プロジェクトについて知っているすべてを 1 回のラウンドトリップで注入するために使用します。

  surgegraph-pp-cli context bundle --project proj_abc123 --include prompts,citations,docs,topics
  

• search — ローカルキャッシュ全体を対象とした全文検索: AI Visibility のプロンプト、引用、ライタードキュメント、最適化済みドキュメント、トピックマップノード — 1 つのクエリで複数エンティティのヒットを得られます。

  エージェントが、プロンプト、引用、下書きなどあらゆるシグナルをローカルキャッシュ全体から特定する必要があるときに選択します。

  surgegraph-pp-cli search "AI search optimization" --kind prompts,citations,docs,topics --agent --select kind,id,title,snippet
  

• sync diff — ローカルストアからリソースごとの同期カーソルと総行数を出力します — 再同期が必要かどうかを知る必要があるエージェントループ向けの検査プリミティブです。

  sync の後に実行してカーソルの鮮度を検査したり、エージェントループ内で読み取り前にローカルストアを再同期する必要があるかどうかを判断したりします。

  surgegraph-pp-cli sync diff --agent
  

コマンドリファレンス

create-ai-visibility-prompt — create ai visibility prompt を管理します

• surgegraph-pp-cli create-ai-visibility-prompt — AI Visibility トラッキング用の新しいプロンプトを作成します。プロンプトは AI アンサーエンジン全体で追跡され、ブランドを監視します...

create-api-key — create api key を管理します

• surgegraph-pp-cli create-api-key — 組織用の LLM プロバイダー API キーを作成します。キーは保存前にプロバイダーに対して検証されます。...

create-bulk-documents — create bulk documents を管理します

• surgegraph-pp-cli create-bulk-documents — 複数の AI 執筆ドキュメントを 1 つのバッチで一括作成します（最大 50）。各記事にはプロンプトが必要で、その他はすべて...

create-document — create document を管理します

• surgegraph-pp-cli create-document — AI 執筆ドキュメントを作成および生成します。必須なのは「prompt」のみで、その他のフィールドにはすべて適切なデフォルト値があります。...

create-domain-research — create domain research を管理します

• surgegraph-pp-cli create-domain-research — トピックカバレッジ分析のためのドメインリサーチを開始します。ドメインを分析して関連トピックを発見します。結果は...

create-image — create image を管理します

• surgegraph-pp-cli create-image — AI 画像を生成し、Content Vision ギャラリーに保存します。まず get_content_vision_settings を使用して確認してください...

create-knowledge-library — create knowledge library を管理します

• surgegraph-pp-cli create-knowledge-library — プロジェクトに新しいナレッジライブラリを作成します。ナレッジライブラリには、AI のコンテキストとして使用できるドキュメントが保存されます...

create-knowledge-library-document — ナレッジライブラリドキュメントの作成を管理します

• surgegraph-pp-cli create-knowledge-library-document — ナレッジライブラリにテキストドキュメントを作成します。ドキュメントの内容は、AI の執筆コンテキストとして使用できるようインデックス化されます...

create-optimized-document — 最適化ドキュメントの作成を管理します

• surgegraph-pp-cli create-optimized-document — 既存の WordPress 投稿から、コンテンツを最適化したドキュメントを作成します。システムは投稿の内容を取得し...

create-topic-research — トピックリサーチの作成を管理します

• surgegraph-pp-cli create-topic-research — トピックの網羅性分析のためのトピックリサーチを開始します。特定のトピックを分析し、サブトピックや関連...

create-topic-research-expansion — トピックリサーチの拡張を管理します

• surgegraph-pp-cli create-topic-research-expansion — 1 つ以上のマクロトピックの下にマイクロトピックを生成して、既存のトピックリサーチを拡張します。各マクロトピック...

delete-ai-visibility-prompt — AI Visibility プロンプトの削除を管理します

• surgegraph-pp-cli delete-ai-visibility-prompt — プロジェクトから AI Visibility プロンプトを削除します。get_ai_visibility_prompts を使用してプロンプト ID を確認してください。整理に便利です...

delete-api-key — API キーの削除を管理します

• surgegraph-pp-cli delete-api-key — 組織から API キーを削除します。キーを確認するには、get_openai_keys／get_gemini_keys／get_anthropic_keys を使用してください...

delete-document — ドキュメントの削除を管理します

• surgegraph-pp-cli delete-document — ID を指定して SurgeGraph ドキュメントを削除します。ドキュメント ID を確認するには、get_writer_documents または get_optimized_documents を使用してください...

delete-knowledge-library — ナレッジライブラリの削除を管理します

• surgegraph-pp-cli delete-knowledge-library — ナレッジライブラリと、その中のすべてのドキュメントを削除します。ライブラリ ID を確認するには、get_knowledge_libraries を使用してください。これは完全な...

delete-knowledge-library-document — ナレッジライブラリドキュメントの削除を管理します

• surgegraph-pp-cli delete-knowledge-library-document — ナレッジライブラリからドキュメントを削除します。LlamaIndex のインデックス、ベクトル埋め込み、およびドキュメントの行が削除されます...

get-ai-visibility-citation-domain — AI Visibility の引用ドメインの取得を管理します

• surgegraph-pp-cli get-ai-visibility-citation-domain — 特定のドメインの引用を詳しく確認します。そのドメインから引用されたページ単位の URL と、それぞれを引用したエンジンを返します...

get-ai-visibility-citation-own-domain — AI Visibility の自ドメイン引用の取得を管理します

• surgegraph-pp-cli get-ai-visibility-citation-own-domain — プロジェクトの自ドメインの引用データを取得します。ユーザーのどのページが AI エンジンに引用されているかを表示します...

get-ai-visibility-citations — AI Visibility の引用の取得を管理します

• surgegraph-pp-cli get-ai-visibility-citations — AI Visibility トラッキングの引用に関する概要を取得します。自ドメインの引用サマリーや、エンジンごとの...

get-ai-visibility-config — AI Visibility 設定の取得を管理します

• surgegraph-pp-cli get-ai-visibility-config — プロジェクトの AI Visibility トラッキングと回答エンジンの設定を取得します。

get-ai-visibility-emerging-topics — AI Visibility の新たなトピックの取得を管理します

• surgegraph-pp-cli get-ai-visibility-emerging-topics — AI Visibility トラッキングから新たなトピックを取得します。AI 全体で言及頻度が高まっているトピックを返します...

get-ai-visibility-metadata — AI Visibility メタデータの取得を管理します

• surgegraph-pp-cli get-ai-visibility-metadata — AI Visibility プロジェクトのフィルターメタデータを取得します。トラッキング対象の回答エンジン（モデル）や、トラッキング対象の...

get-ai-visibility-opportunities — AI Visibility の最適化機会の取得を管理します

• surgegraph-pp-cli get-ai-visibility-opportunities — プロジェクトの AI Visibility 最適化機会を取得します。優先度およびカテゴリ別の統計と、項目の一覧を返します... get-ai-visibility-overview — AI Visibility 概要を管理

• surgegraph-pp-cli get-ai-visibility-overview — プロジェクト内の特定ブランドの AI Visibility 概要を取得します。エンジンごとのブランド指標を返します...

get-ai-visibility-prompt-detail — AI Visibility プロンプト詳細を管理

• surgegraph-pp-cli get-ai-visibility-prompt-detail — 特定の日付における単一のプロンプトを詳しく調べます。可視性、順位、シェアなど、ブランドのパフォーマンス全体を返します...

get-ai-visibility-prompt-response — AI Visibility プロンプト応答を管理

• surgegraph-pp-cli get-ai-visibility-prompt-response — 特定のプロンプト実行に対する AI の生の応答を取得します。構造化された応答項目と Markdown を返します...

get-ai-visibility-prompts — AI Visibility プロンプトを管理

• surgegraph-pp-cli get-ai-visibility-prompts — プロジェクトで AI Visibility の追跡用に設定されたプロンプトを取得します。ページネーションに対応し、デフォルトでは page 1、pageSize 50 です...

get-ai-visibility-response-structure — AI Visibility 応答構造を管理

• surgegraph-pp-cli get-ai-visibility-response-structure — AI Visibility の追跡における特定ブランドの応答構造分析を取得します。エンジンごとの応答を返します...

get-ai-visibility-sentiment — AI Visibility センチメントを管理

• surgegraph-pp-cli get-ai-visibility-sentiment — AI Visibility の追跡における特定ブランドのセンチメント分析を取得します。エンジンごとのセンチメントを返します...

get-ai-visibility-topic-gaps — AI Visibility トピックギャップを管理

• surgegraph-pp-cli get-ai-visibility-topic-gaps — AI Visibility の追跡におけるトピックギャップを取得します。トピックギャップとは、競合他社が言及されている一方で、自社ブランドが...

get-ai-visibility-topics — AI Visibility トピックを管理

• surgegraph-pp-cli get-ai-visibility-topics — AI Visibility の追跡からトピッククラスターを取得します。キーワード頻度やトレンドを含む、クラスター化されたトピックを返します...

get-ai-visibility-traffic-pages — AI Visibility トラフィックページを管理

• surgegraph-pp-cli get-ai-visibility-traffic-pages — AI トラフィックデータがあるページのページネーション付き一覧を取得します。ページごとの AI／人間の訪問数、CTR、クロールエラー、上位...

get-ai-visibility-traffic-summary — AI Visibility トラフィック概要を管理

• surgegraph-pp-cli get-ai-visibility-traffic-summary — プロジェクトの AI トラフィック分析概要を取得します。傾向、CTR、インデックス済みページを含む、AI／人間の総訪問数を返します...

get-ai-visibility-trend — AI Visibility トレンドを管理

• surgegraph-pp-cli get-ai-visibility-trend — 特定ブランドの AI Visibility の日次トレンドを取得します。日付範囲は14日を超えることはできません。ツールは...

get-anthropic-keys — Anthropic キーを管理

• surgegraph-pp-cli get-anthropic-keys — 組織の Anthropic API キーをすべて一覧表示します。マスキングされたキー（末尾4文字は表示）、有効状態、ラベルなどを返します...

get-author-brand — 著者ブランドを管理

• surgegraph-pp-cli get-author-brand — プロジェクトのブランドプロフィールを取得します（Author Synthesis）。ブランドアイデンティティの値、必須／禁止...

get-authors — 著者を管理

• surgegraph-pp-cli get-authors — プロジェクトに設定されているすべての著者を一覧表示します（Author Synthesis）。声の調整、経歴などを含む著者プロフィールを返します...

get-brand-mentions — ブランドへの言及を管理

• surgegraph-pp-cli get-brand-mentions — 組織に設定されているすべてのブランドへの言及を一覧表示します。

get-content-vision-gallery — Content Vision ギャラリーを管理

• surgegraph-pp-cli get-content-vision-gallery — プロジェクトの Content Vision ギャラリーから画像を一覧表示します。種類、スタイル、検索クエリによる絞り込みに対応しています...

get-content-vision-settings — Content Vision 設定を管理

• surgegraph-pp-cli get-content-vision-settings — ブランドカラー、注目画像の設定、利用可能な画像の種類など、プロジェクトの Content Vision 設定を取得します...

get-document — ドキュメントを管理

• surgegraph-pp-cli get-document — ID で単一のドキュメントを取得します。コンテンツ、AEO（AI エンジン最適化）の提案、SEO の提案が含まれます。

get-domain-research — ドメイン調査の取得を管理します

• surgegraph-pp-cli get-domain-research — ドメイン調査の完全な結果を取得します。ドメイン、抽出されたトピック、完了状況が含まれます。使用方法...

get-gemini-keys — Gemini キーの取得を管理します

• surgegraph-pp-cli get-gemini-keys — 組織のすべての Gemini API キーを一覧表示します。マスクされたキー（末尾 4 文字を表示）、有効状況、ラベルなどを返します...

get-knowledge-libraries — ナレッジライブラリの取得を管理します

• surgegraph-pp-cli get-knowledge-libraries — プロジェクトのすべてのナレッジライブラリを一覧表示します。ドキュメント数とチャット数を含むライブラリを返します。

get-knowledge-library-documents — ナレッジライブラリのドキュメント取得を管理します

• surgegraph-pp-cli get-knowledge-library-documents — ナレッジライブラリ内のすべてのドキュメント／アセットを一覧表示します。インデックス作成状況を含むドキュメントの詳細を返します。

get-languages — 言語の取得を管理します

• surgegraph-pp-cli get-languages — ドキュメント作成とトピック調査で使用できる言語を一覧表示します。言語コードと言語名を返します。返された...

get-locations — 地域の取得を管理します

• surgegraph-pp-cli get-locations — ドキュメント作成とトピック調査で使用できる地域（国）を一覧表示します。地域コード、地域名などを返します...

get-openai-keys — OpenAI キーの取得を管理します

• surgegraph-pp-cli get-openai-keys — 組織のすべての OpenAI API キーを一覧表示します。マスクされたキー（末尾 4 文字を表示）、有効状況、ラベルなどを返します...

get-optimized-documents — 最適化済みドキュメントの取得を管理します

• surgegraph-pp-cli get-optimized-documents — Content Optimizer で最適化された記事を一覧表示します。検索とページネーションに対応しています。

get-organization-cms-integrations — 組織の CMS インテグレーション取得を管理します

• surgegraph-pp-cli get-organization-cms-integrations — 組織に接続されているすべての CMS インテグレーションを一覧表示します。各インテグレーションがリンクされているプロジェクトも含まれます...

get-project-cms-integration — プロジェクトの CMS インテグレーション取得を管理します

• surgegraph-pp-cli get-project-cms-integration — 特定のプロジェクトに接続されている CMS インテグレーションを取得します。インテグレーションの種類、サイトの詳細、接続情報を返します...

get-projects — プロジェクトの取得を管理します

• surgegraph-pp-cli get-projects — 組織のすべてのプロジェクトを一覧表示します。検索とページネーションに対応しています。

get-team — チームの取得を管理します

• surgegraph-pp-cli get-team — 組織のすべてのチームメンバーと保留中の招待を一覧表示します。ロールなどのメンバーの詳細を返します...

get-topic-map — トピックマップの取得を管理します

• surgegraph-pp-cli get-topic-map — プロジェクトのトピックカバレッジマップを取得します。ピラートピック、サブトピック、カバレッジを含むトピック階層全体を返します...

get-topic-research — トピック調査の取得を管理します

• surgegraph-pp-cli get-topic-research — トピック調査の完全な結果を取得します。シードトピック、地域／言語、階層化されたマクロからミクロへのトピックが含まれます...

get-usage — 使用状況の取得を管理します

• surgegraph-pp-cli get-usage — 組織のクォータ使用状況、機能制限、クレジット残高を取得します。永続クォータ（チームシート数など）を表示します...

get-wordpress-authors — WordPress 著者の取得を管理します

• surgegraph-pp-cli get-wordpress-authors — 接続済みの WordPress サイトの著者を一覧表示します。各著者の ID、名前、スラッグ、プロフィール、avatarUrl を返します。ページネーションに対応しています —...

get-wordpress-categories — WordPress カテゴリーの取得を管理します

• surgegraph-pp-cli get-wordpress-categories — 接続済みの WordPress サイトのすべてのカテゴリーを一覧表示します。各カテゴリーの ID、名前、スラッグを返します — ID を使用...

get-wordpress-integrations — WordPress インテグレーションの取得を管理します

• surgegraph-pp-cli get-wordpress-integrations — 組織に接続されているすべての WordPress インテグレーションを一覧表示します。サイトの詳細、マスクされた API キーなどを表示します...

get-writer-documents — ライタードキュメントの取得を管理します

• surgegraph-pp-cli get-writer-documents — コンテンツハブの記事を一覧表示します。フィルターとページネーションに対応しています。

get-writer-models — ライターモデルを管理します

• surgegraph-pp-cli get-writer-models — ドキュメント作成に使用できる AI モデルを一覧表示します。モデル ID、プロバイダー、クレジットコスト、および対応状況を返します...

list-domain-researches — ドメイン調査を一覧表示します

• surgegraph-pp-cli list-domain-researches — プロジェクトのすべてのドメイン調査を一覧表示します。各エントリーの ID、ドメイン、抽出されたトピック数などを返します...

list-topic-researches — トピック調査を一覧表示します

• surgegraph-pp-cli list-topic-researches — プロジェクトのすべてのトピック調査を一覧表示します。各エントリーの ID、シードトピック、トピックの合計数などを返します...

publish-document-to-cms — ドキュメントを CMS に公開します

• surgegraph-pp-cli publish-document-to-cms — SurgeGraph ドキュメントを、プロジェクトに接続された CMS（現在は WordPress）に公開します。新しい投稿を作成します...

update-ai-visibility-prompt — AI Visibility プロンプトを更新します

• surgegraph-pp-cli update-ai-visibility-prompt — 既存の AI Visibility プロンプトを更新します。プロンプトのテキスト、トピック、タグを変更できます。トピックとタグは解決されます...

update-api-key — API キーを更新します

• surgegraph-pp-cli update-api-key — 既存の API キーを更新します。キーの値、有効状態、ラベル、プロジェクトの割り当てを変更できます。指定すると...

update-document — ドキュメントを更新します

• surgegraph-pp-cli update-document — 既存の SurgeGraph ドキュメントの基本フィールド（タイトル、コンテンツ（HTML 本文）、メタディスクリプション、スキーマなど）を更新します...

update-project-cms-integration — プロジェクトの CMS 連携を更新します

• surgegraph-pp-cli update-project-cms-integration — プロジェクトの CMS 連携を接続または変更します（現在は WordPress のみ）。get_wordpress_integrations を使用して...

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

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

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

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

レシピ

月曜日の AI Visibility レビュー

surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --agent --select brand,metric,delta_pct

週ごとの変動を取得し、月曜日の CMO 向け更新情報にそのまま渡します。

深くネストされた引用レスポンスを簡潔にする

surgegraph-pp-cli get-ai-visibility-citations --project-id proj_abc123 --agent --select data.domains.domain,data.domains.citationCount

引用レスポンスは深くネストされているため、ドット区切りのパスを使った --select で、エージェントのコンテキスト予算内にペイロードを収められます。

ローカルキャッシュ内から、あるトピックに関するあらゆるシグナルを検索する

surgegraph-pp-cli search "AI search optimization" --kind prompt,citation,doc,topic --agent --select kind,id,title,snippet

4 つすべてのエンティティを対象に、1 回のリクエストで FTS5 検索します。結果は統合され、ランク付けできます。インデックスを作成するため、先に sync を実行してください。

ギャップのあるすべてのトピックを WordPress に公開する

surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run

get_topic_map → create_bulk_documents → publish_document_to_cms を連続して実行します。再試行しても冪等です。

ローカルキャッシュの結果を 1 種類の引用に絞り込む

surgegraph-pp-cli search "answer engine" --kind citation --agent

--kind を使って FTS のヒットを 1 種類のエンティティに絞り込みます。--limit と組み合わせると、出力を適切な範囲に抑えられます。

認証の設定

SurgeGraph は https://mcp.surgegraph.io に対して、Authorization Code + PKCE + Dynamic Client Registration を使用する OAuth 2.1 を採用しています。surgegraph-pp-cli auth login を一度実行すると、CLI がクライアントを登録し、ブラウザーでのフローを案内して、以降の呼び出しに使うベアラートークンとリフレッシュトークンを保存します。auth status では現在の TTL を確認でき、auth logout でトークンを消去できます。

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

エージェントモード

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

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

• フィルタ可能 — --select でフィールドの一部を選択できます。ドット区切りのパスはネストされた構造をたどり、配列では各要素を走査します。出力の多い API でコンテキストを小さく保つために重要です：

  surgegraph-pp-cli create-ai-visibility-prompt --intent example-value --agent --select id,name,status
  

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

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

• 明示的な再試行 — すでに存在するリソースの作成を成功として扱う場合に限り、--idempotent を使用します

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

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

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

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

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

出力の配信

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

シンク	効果
stdout	デフォルト。stdout のみに出力します
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してから名前を変更）
webhook:<url>	出力本文を URL に POST します（--compact の場合、application/json または application/x-ndjson）

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

名前付きプロファイル

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

surgegraph-pp-cli profile save briefing --json
surgegraph-pp-cli --profile briefing create-ai-visibility-prompt --intent example-value
surgegraph-pp-cli profile list --json
surgegraph-pp-cli profile show briefing
surgegraph-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します：

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

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

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

claude mcp add surgegraph-pp-mcp -- surgegraph-pp-mcp

確認：claude mcp list

直接使用

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

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

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