pp-semrush

Semrush — Printing Press CLI

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

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

1. Printing Press インストーラーを使ってインストールします。バイナリの既定の保存先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

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

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

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

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

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

この CLI を使う場面

同じ方法で Semrush のデータを何度も照会する必要がある場合（週次の変動、キーワードギャップ、バックリンクギャップ、Site Audit のリグレッションなど）、または、すでに取得したデータにクレジットを再度消費せずに Semrush を操作できるエージェントをオーケストレーションする場合に、この CLI を使います。単発のアドホックな検索（公式の Semrush UI の方が速い）や、Trends API のワークフロー（意図的に対象外）には適していません。

独自の機能

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

積み重なるローカル状態

• drift — 今週のドメインとキーワードのスナップショットを先週のものと比較し、すでに取得したデータにクレジットを再度消費することなく、変化を確認できます。

  エージェントに「今週、このドメインに何が起きましたか」と尋ねられたとき、ローカルストアの情報から API を使わずに回答できる唯一のコマンドです。

  semrush-pp-cli drift apple.com --since 7d --agent
  

• snapshot — 任意のリソースの現在のローカルストアの状態にタグ（例：monday-baseline）を付け、後から任意の2つのタグを比較して、その間に何が変化したかを正確に確認できます。

  同じデータに再度料金を支払わずに、会話をまたいで複数週にわたる状態をエージェントが推論できるようにします。

  semrush-pp-cli snapshot tag monday && semrush-pp-cli snapshot diff monday today --select phrase,position --agent
  

• backlink new — 指定した期間内に初めて確認された参照ドメインとバックリンクだけを表示するので、「今週、新たに自サイトへリンクしたものはありますか」という質問に一行で答えられます。

  最新の状況に関する質問に答えるために、バックリンクレポートを2つとも再取得して比較する手間をエージェントから省きます。

  semrush-pp-cli backlink new apple.com --since 7d --json
  

• tracking drift — Position Tracking のスナップショットにウィンドウ関数を適用し、地域やデバイスごとに、N順位を超えて変動したキーワード、1ページ目から落ちたキーワード、1ページ目に入ったキーワードを確認できます。

  「今月、追跡対象のキーワードにどんな変動がありましたか」という、Position Tracking のメールでは答えられない質問に、1つのコマンドで回答します。

  semrush-pp-cli tracking drift 12345 --since 30d --min-delta 3 --agent
  

• audit regression — プロジェクトの最新2件の Site Audit スナップショットを比較し、新たに発生した問題 ID、解決した問題、重大度ごとの件数の差分を表示します。

  2回のクロールの間に、技術的な SEO の状態が具体的にどのように悪化したかをエージェントが伝えられるようにします。

  semrush-pp-cli audit regression 12345 --agent
  

コストの透明性

• budget — 各 API 呼び出しの公表されている単位コストをローカルに記録し、日別・コマンド別・リソース別に支出を集計します。また、現在の残高の確認結果から、月末時点のプロジェクト支出を予測します。

  リクエスト前にはエージェントに「これは N 単位のコストがかかります」と伝え、1か月後には「単位はここに使われました」と報告できます。どちらの情報も、上流サービスだけでは得られません。

  semrush-pp-cli budget --since 30d --group-by command --agent
  

API ではできないクロスドメイン結合

• keyword gap — 同じデータベース内の2つ以上のドメイン間でオーガニックキーワードの差分を取得します。共通項目と各ドメイン固有の項目を確認できます。

  SEO コンサルタントが手作業で行う、2つの CSV を使った VLOOKUP を置き換えます。

  semrush-pp-cli keyword gap myco.com competitor1.com competitor2.com --database us --kd-max 40 --agent
  

• backlink gap — 競合にはリンクしているものの、自社にはリンクしていない参照ドメインを、権威スコアで絞り込んで見つけます。

  エージェントがアウトリーチワークフローに引き渡せる、リンク構築のターゲットを直接提示します。

  semrush-pp-cli backlink gap myco.com competitor.com --min-ascore 70 --agent
  

• domain regions — 複数の国別データベースで Domain Overview を一度に実行し、後で地域間の変化を調べられるよう、データベースキーとともにすべての行を保存します。

  「このドメインは主要な5市場でどのような成果を上げているか」という質問に、5回ではなく1回の呼び出しでエージェントが答えられます。

  semrush-pp-cli domain regions apple.com --databases us,uk,de,fr,it --agent
  

競合にはない SEO コンテンツのパターン

• audit triage — 加重した問題の重大度（エラー×3、警告×1、通知×0.1）で Site Audit のページをランク付けし、影響の大きいページから修正できるようにします。

  Site Audit の出力を、エージェントが次のステップに引き渡せる優先順位付きのアクションリストに変換します。

  semrush-pp-cli audit triage 12345 --top 20 --agent
  

• serp-features — 追跡対象のキーワードについて、どの SERP 機能（強調スニペット、People Also Ask、動画、画像パック）がいつ表示され、いつ消えたかを時系列で確認できます。

  コンテンツ戦略エージェントに、機会（例：強調スニペット枠の空き）がいつ発生したか、または終了したかを伝えます。

  semrush-pp-cli serp-features 'best running shoes' --since 30d --agent
  

• cannibalization — 同じドメインが複数の URL でランクインしているフレーズ（既知の SEO 上の問題）を、それぞれの URL と掲載順位とともに一覧表示します。

  価値の高い SEO 上の問題を1つのコマンドで明らかにします。多くのコンサルタントは、この調査に料金を請求します。

  semrush-pp-cli cannibalization apple.com --database us --agent
  

コマンドリファレンス

account — アカウント関連のユーティリティ（API ユニット残高）

• semrush-pp-cli account — 残りの API ユニット残高を取得します（無料の確認。ユニットを消費しません）。

audit — Site Audit：有効化、実行、スナップショットの一覧表示、問題やページの詳細確認

• semrush-pp-cli audit campaign-info — Site Audit キャンペーンの設定と現在のステータスを取得します。
• semrush-pp-cli audit edit — Site Audit キャンペーンの設定（ページ上限、ユーザーエージェント、対象範囲など）を編集します。
• semrush-pp-cli audit enable — プロジェクトで Site Audit を有効にします。プロジェクトごとに1回だけ実行します。無料（設定呼び出し）。
• semrush-pp-cli audit history — Site Audit のスナップショット履歴（問題数とスコアの時系列）。
• semrush-pp-cli audit issue — スナップショット内の1つの問題について、詳細なレポートを取得します（影響を受けるページ、ステータス）。
• semrush-pp-cli audit issue-catalog — すべての Site Audit 問題コードのテキスト説明を取得します。無料。
• semrush-pp-cli audit page — クロール済みの1つのページについて、詳細情報をすべて取得します（検出された問題、ステータス、指標）。
• semrush-pp-cli audit page-by-url — スナップショット内で、指定した URL の page_id を検索します。
• semrush-pp-cli audit run — 新しい Site Audit クロールを開始します。開始は無料ですが、ページクレジット枠を消費します。
• semrush-pp-cli audit snapshot-info — スナップショットの集計件数を取得します（エラー／警告／通知、チェック総数）。
• semrush-pp-cli audit snapshots — プロジェクトの Site Audit スナップショットを一覧表示します。無料（API ユニットを消費しません）。

backlink — バックリンク：概要、一覧、参照ドメイン／IP、アンカー、競合、履歴

• semrush-pp-cli backlink anchors — アンカーテキスト。1 行あたり 40 ユニット。ターゲットを指す被リンクで使用されているアンカーテキストです。
• semrush-pp-cli backlink authority-score — オーソリティスコアのプロファイル。リクエストあたり 40 ユニット。ターゲットの Semrush オーソリティスコア（AS）のスナップショットです。
• semrush-pp-cli backlink categories — カテゴリ。1 行あたり 40 ユニット。参照元ドメインの分野カテゴリです。
• semrush-pp-cli backlink categories-profile — カテゴリプロファイル。リクエストあたり 40 ユニット。信頼度評価を含む、ターゲットの分野カテゴリです。
• semrush-pp-cli backlink compare-batch — 一括比較。ドメインあたりリクエストごとに 40 ユニット。最大 200 ドメインの被リンク統計を並べて比較します。
• semrush-pp-cli backlink compare-refdomains — 参照元ドメインによる比較。1 行あたり 40 ユニット。複数のターゲットにリンクしている参照元ドメインを示します（マトリックス）。
• semrush-pp-cli backlink competitors — 被リンクの競合。1 行あたり 40 ユニット。ターゲットと類似した被リンクプロファイルを持つドメインです。
• semrush-pp-cli backlink geo — 国別の参照元ドメイン。1 行あたり 40 ユニット。参照元ドメインの国別分布です。
• semrush-pp-cli backlink history — 履歴データ（被リンク）。1 行あたり 40 ユニット。被リンク数／参照元ドメイン数と AS の時系列データです。
• semrush-pp-cli backlink indexed-pages — インデックス済みページ。1 行あたり 40 ユニット。被リンクを受けているターゲット上のページです。
• semrush-pp-cli backlink list — 被リンク。1 行あたり 40 ユニット。ターゲットを指す個々の被リンクです。
• semrush-pp-cli backlink overview — 被リンクの概要。リクエストあたり 40 ユニット。被リンク数、参照元ドメイン数、参照元 IP 数、フォロー率、AS を表示します。
• semrush-pp-cli backlink referring-domains — 参照元ドメイン。1 行あたり 40 ユニット。ターゲットにリンクしている重複除去済みのドメインです。
• semrush-pp-cli backlink referring-ips — 参照元 IP。1 行あたり 40 ユニット。参照元ドメインをホストする重複除去済みの IP アドレスです。
• semrush-pp-cli backlink tld — TLD の分布。1 行あたり 40 ユニット。TLD 別の参照元ドメインの分布です。

domain — ドメイン分析：概要、オーガニック／有料キーワード、競合、ページ、広告履歴

• semrush-pp-cli domain ad-copies — ドメイン広告コピー。1 行あたり 20 ユニット。あるドメインが配信したユニークな広告クリエイティブ（タイトル + 説明文）。
• semrush-pp-cli domain ad-history — ドメイン広告履歴。1 行あたり 100 ユニット。あるドメインが有料キーワード向けに配信した広告コピーの 12 か月分のアーカイブ。
• semrush-pp-cli domain compare — ドメイン対ドメイン。1 行あたり 80 ユニット。2～5 個のドメイン間のキーワード重複を並べて比較します。
• semrush-pp-cli domain competitors-organic — オーガニック検索の競合。1 行あたり 40 ユニット。ターゲットとオーガニックキーワードを共有するドメイン。
• semrush-pp-cli domain competitors-paid — 有料検索の競合。1 行あたり 40 ユニット。ターゲットの Google 広告キーワードセットと重複するドメイン。
• semrush-pp-cli domain competitors-pla — PLA 競合。1 行あたり 40 ユニット。ターゲットの Google ショッピング PLA キーワードセットと重複するドメイン。
• semrush-pp-cli domain organic-keywords — ドメインのオーガニック検索キーワード。1 行あたり 30 ユニット。あるドメインが Google のオーガニック検索上位 100 位以内にランクインしているキーワード。
• semrush-pp-cli domain organic-pages — ドメインのオーガニックページ。1 行あたり 30 ユニット。トラフィック別に見た、あるドメインの主要なオーガニックランディングページ。
• semrush-pp-cli domain overview — ドメイン概要（1 データベース）。1 行あたり 10 ユニット。1 つの地域データベースにおける現在または過去のランキング。
• semrush-pp-cli domain overview-all — ドメイン概要（全データベース）。1 行あたり 10 ユニット。すべての地域データベースをカバーする約 140 行。
• semrush-pp-cli domain overview-history — ドメイン概要（履歴）。1 行あたり 10 ユニット。1 つのデータベースの月次履歴ランキング（2012～2016 年まで遡及）。
• semrush-pp-cli domain paid-keywords — ドメインの有料検索キーワード。1 行あたり 30 ユニット。あるドメインが Google 広告で購入しているキーワード。
• semrush-pp-cli domain pla-copies — ドメイン PLA コピー。1 行あたり 20 ユニット。ユニークな PLA 広告クリエイティブ（タイトル、価格、ショップ）。
• semrush-pp-cli domain pla-keywords — ドメイン PLA 検索キーワード。1 行あたり 30 ユニット。あるドメインの Google ショッピング PLA キーワード。
• semrush-pp-cli domain subdomains — ドメインのオーガニックサブドメイン。1 行あたり 30 ユニット。オーガニックトラフィック順に並べた、あるドメインのサブドメイン。

keyword — キーワードリサーチレポート（ボリューム、難易度、関連、SERP、広告履歴）

• semrush-pp-cli keyword ads-history — キーワード広告履歴。1 行あたり 100 ユニット。そのキーワードに入札した広告主の 12 か月分のアーカイブ。
• semrush-pp-cli keyword batch — バッチキーワード概要。1 行あたり 10 ユニット。1 回の呼び出しで最大 100 個のキーワード。
• semrush-pp-cli keyword broad-match — ブロードマッチキーワード。1 行あたり 20 ユニット。シード語句のフレーズマッチバリアント。
• semrush-pp-cli keyword difficulty — キーワード難易度。1 行あたり 50 ユニット。1 つ以上のキーワードの KDI（0～100）。
• semrush-pp-cli keyword organic-serp — キーワードのオーガニック検索結果（SERP）。1 行あたり 10 ユニット。あるフレーズのオーガニック検索上位の URL。
• semrush-pp-cli keyword overview — キーワード概要（1 データベース）。1 行あたり 10 ユニット。単一データベースのボリューム、CPC、競合性、検索結果数。
• semrush-pp-cli keyword overview-all — キーワード概要（全データベース）。1 行あたり 10 ユニット。すべての地域データベースをカバーする約 140 行。
• semrush-pp-cli keyword paid-serp — キーワードの有料検索結果（SERP）。1 行あたり 20 ユニット。そのフレーズに入札している広告主。
• semrush-pp-cli keyword questions — フレーズの質問。1 行あたり 40 ユニット。シードフレーズを含む質問形式のキーワード。
• semrush-pp-cli keyword related — 関連キーワード。1 行あたり 40 ユニット。シードフレーズに意味的に関連するキーワード。

project — Semrush プロジェクトの管理（ポジショントラッキング、サイト監査、リスティングのコンテナ）

• semrush-pp-cli project create — 名前とルートドメインを指定して新しい Semrush プロジェクト（コンテナ）を作成します。
• semrush-pp-cli project delete — プロジェクトを削除します。CLI では確認のために --yes が必要です。指定しない場合はドライランになります。
• semrush-pp-cli project get — ID で単一のプロジェクトを取得します。無料（API ユニット消費なし）。
• semrush-pp-cli project list — アカウント上のすべてのプロジェクトを一覧表示します。無料（API ユニット消費なし）。
• semrush-pp-cli project update — 既存プロジェクトの名前/URL を更新します。

subdomain — サブドメイン分析: 概要、オーガニック/有料キーワード、ページ

• semrush-pp-cli subdomain organic-keywords — サブドメインのオーガニック検索キーワード。1 行あたり 30 ユニット。
• semrush-pp-cli subdomain organic-pages — サブドメインのオーガニックページ。1 行あたり 30 ユニット。
• semrush-pp-cli subdomain overview — サブドメインの概要（1 つのデータベース）。1 行あたり 10 ユニット。
• semrush-pp-cli subdomain overview-all — サブドメインの概要（すべてのデータベース）。1 行あたり 10 ユニット。
• semrush-pp-cli subdomain overview-history — サブドメインの概要（履歴）。1 行あたり 10 ユニット。月次の履歴ランキング。
• semrush-pp-cli subdomain paid-keywords — サブドメインの有料検索キーワード。1 行あたり 30 ユニット。

subfolder — サブフォルダーの分析: 概要、オーガニック/有料キーワード、ページ

• semrush-pp-cli subfolder organic-keywords — サブフォルダーのオーガニック検索キーワード。1 行あたり 30 ユニット。
• semrush-pp-cli subfolder organic-pages — サブフォルダーのオーガニックページ。1 行あたり 30 ユニット。
• semrush-pp-cli subfolder organic-pages-unique — サブフォルダーのオーガニックページ（ユニーク）。1 行あたり 30 ユニット。サブフォルダー内のユニークな上位オーガニックランディングページ。
• semrush-pp-cli subfolder overview — サブフォルダーの概要（1 つのデータベース）。1 行あたり 10 ユニット。
• semrush-pp-cli subfolder overview-all — サブフォルダーの概要（すべてのデータベース）。1 行あたり 10 ユニット。
• semrush-pp-cli subfolder overview-history — サブフォルダーの概要（履歴）。1 行あたり 10 ユニット。月次の履歴ランキング。
• semrush-pp-cli subfolder paid-keywords — サブフォルダーの有料検索キーワード。1 行あたり 30 ユニット。

tracking — ポジショントラッキング: キャンペーンの作成、キーワード/タグ/競合の管理、オーガニックおよび有料レポート

• semrush-pp-cli tracking campaigns — プロジェクト配下のポジショントラッキングキャンペーンを一覧表示します。campaign_id を探すために使用します。

• semrush-pp-cli tracking competitors-add — 既存のポジショントラッキングキャンペーンに競合を追加します。

• semrush-pp-cli tracking competitors-remove — 既存のポジショントラッキングキャンペーンから競合を削除します。

• semrush-pp-cli tracking create — プロジェクト上にポジショントラッキングキャンペーンを作成します。

• semrush-pp-cli tracking dates — トラッキングキャンペーンで利用可能なスナップショット日付（他の場所で --snapshot フラグによって使用されます）。

• semrush-pp-cli tracking emails-disable — ポジショントラッキングキャンペーンの週次ステータスメールを無効化します。

• semrush-pp-cli tracking emails-enable — ポジショントラッキングキャンペーンの週次ステータスメールを有効化します。

• semrush-pp-cli tracking keywords-add — 既存のポジショントラッキングキャンペーンにキーワードを追加します。

• semrush-pp-cli tracking keywords-remove — 既存のポジショントラッキングキャンペーンからキーワードを削除します。

• semrush-pp-cli tracking location-search — ユニバーサル位置検索（都市/地域/国の位置 ID を返します）。

• semrush-pp-cli tracking organic-competitors — オーガニック競合の検出（追跡対象のキーワードセット全体でランク付けされた自動検出の競合）。

• semrush-pp-cli tracking organic-landings — 追跡キーワードのトラフィック別上位オーガニックランディングページ。

• semrush-pp-cli tracking organic-overview — オーガニック概要レポート（特定期間におけるビジビリティ、推定トラフィック、平均順位）。

• semrush-pp-cli tracking organic-positions — キーワードごとのオーガニック順位レポート。タグフィルターと競合比較をサポートします。

• semrush-pp-cli tracking organic-visibility — 特定期間におけるオーガニックビジビリティ（シェアオブボイス）指数。

• semrush-pp-cli tracking paid-competitors — AdWords 競合の検出（自動検出の有料競合）。

• semrush-pp-cli tracking paid-landings — 追跡キーワードのトラフィック別上位有料（AdWords）ランディングページ。

• semrush-pp-cli tracking paid-overview — AdWords 概要レポート（特定期間における有料ビジビリティ、推定トラフィック）。

• semrush-pp-cli tracking paid-positions — キーワードごとの有料（AdWords）順位レポート。

• semrush-pp-cli tracking paid-visibility — 特定期間における AdWords ビジビリティ（シェアオブボイス）指数。

• semrush-pp-cli tracking tags-add — ポジショントラッキングキャンペーン内の既存キーワードにタグを追加します。

• semrush-pp-cli tracking tags-remove — ポジショントラッキングキャンペーン内の既存キーワードからタグを削除します。 url — URL レベルの分析：概要、オーガニック／有料キーワード

• semrush-pp-cli url organic-keywords — URL のオーガニック検索キーワード。1 行あたり 30 ユニット。この URL がオーガニック検索でランクインしているキーワードです。

• semrush-pp-cli url overview — URL の概要（1 データベース）。1 行あたり 10 ユニット。

• semrush-pp-cli url overview-all — URL の概要（すべてのデータベース）。1 行あたり 10 ユニット。

• semrush-pp-cli url overview-history — URL の概要（履歴）。1 行あたり 10 ユニット。URL の月次ランキング履歴です。

• semrush-pp-cli url paid-keywords — URL の有料検索キーワード。1 行あたり 30 ユニット。この URL が広告を出しているキーワードです。

データ鮮度の保証

この CLI が鮮度を一定の範囲内で管理するのは、登録済みのストアを使った読み取りコマンドのパスのみです。--data-source auto モードでは、これらのパスは sync_state を確認し、ローカルデータを読み込む前に範囲を限定した更新を実行する場合があります。--data-source local は更新を行いません。--data-source live は API から読み取り、ローカルストアを変更しません。ソース選択を変えずに鮮度チェックをスキップするには、SEMRUSH_NO_AUTO_REFRESH=1 を設定してください。

対象となるパス：

• semrush-pp-cli project
• semrush-pp-cli project get
• semrush-pp-cli project list

JSON 出力で生成されたプロヴェナンスエンベロープを使用する場合、鮮度メタデータは meta.freshness に表示されます。これは対象のコマンドパスにおける現在のキャッシュの鮮度を示すものであり、過去データの完全なバックフィルや API 固有のエンリッチメントを保証するものではありません。

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

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

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

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

レシピ

月曜日のベースラインと金曜日の差分

semrush-pp-cli snapshot tag monday-baseline

追跡対象のドメインとキーワードを同期した後、スナップショットにタグを付けます。金曜日に再同期し、snapshot diff monday-baseline today を実行すると、1 週間の変動を確認できます。

競合他社がランクインしているキーワードの機会を見つける

semrush-pp-cli keyword gap myco.com competitor.com --database us --kd-max 40 --json --select phrase,nq,kd

1 回の差分クエリで、現実的な難易度のキーワードに絞り込みます。競合他社はランクインしているものの、自社はランクインしていないキーワードが対象です。

競合他社をもとにリンク獲得候補のリストを作成する

semrush-pp-cli backlink gap myco.com competitor.com --min-ascore 70 --json --select domain,domain_ascore,backlinks_num

競合他社にはリンクしているものの、自社にはリンクしていない、権威性 70 以上の参照ドメインです。アウトリーチのワークフローにそのまま渡せます。

最新の Site Audit を優先順位付けする

semrush-pp-cli audit triage 12345 --top 20 --agent

Site Audit のスナップショットが作成されたら、エラー ×3 ＋ 警告 ×1 ＋ 通知 ×0.1 で重み付けした、影響度の高い上位 20 ページを取得します。

今月のクレジット使用先を確認する

semrush-pp-cli budget --since 30d --group-by command --agent

ローカルの credit_log をコマンドごとに集計し、使用量の多い項目を表示します。これを参考に、実行を制限したり、キャッシュを利用したりできます。

認証の設定

Subscription Info → API Units ページから SEMRUSH_API_KEY を設定してください。この CLI は公式ドキュメントと同じ v3 のクエリパラメーター認証を使用し、doctor チェックには無料の残高エンドポイントを使用するため、キーの動作確認にクレジットを消費することはありません。

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

エージェントモード

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

• パイプ対応 — stdout に JSON を出力し、エラーは stderr に出力します

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

  semrush-pp-cli backlink list mock-value --type example-value --agent --select id,name,status
  

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

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

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

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

応答エンベロープ

ローカルストアまたは 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 について気になる点に気づいた場合は、（あなた自身またはエージェントが）記録してください。

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

エントリはローカルの ~/.local/share/semrush-pp-cli/feedback.jsonl に保存されます。SEMRUSH_FEEDBACK_ENDPOINT が設定され、かつ --send が渡された場合、または SEMRUSH_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」パターンです。

semrush-pp-cli profile save briefing --json
semrush-pp-cli --profile briefing backlink list mock-value --type example-value
semrush-pp-cli profile list --json
semrush-pp-cli profile show briefing
semrush-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

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

2. Claude Code に登録します。

   claude mcp add semrush-pp-mcp -- semrush-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

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

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