pp-ahrefs

Ahrefs — Printing Press CLI

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

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

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

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

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

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

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

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

この CLI を使用しない場合

リモート状態の作成、更新、削除、公開、コメント、賛成票の投票、招待、注文、メッセージ送信、予約、購入、変更が必要なリクエストには、この CLI を使用しないでください。この CLI が提供するのは、調査、エクスポート、同期、分析のための読み取り専用コマンドです。

コマンドリファレンス

keywords-explorer — Keywords Explorer のエンドポイント。

• ahrefs-pp-cli keywords-explorer matching-terms — 一致するキーワード
• ahrefs-pp-cli keywords-explorer overview — 概要
• ahrefs-pp-cli keywords-explorer related-terms — 関連キーワード
• ahrefs-pp-cli keywords-explorer search-suggestions — 検索候補
• ahrefs-pp-cli keywords-explorer volume-by-country — 国別の検索ボリューム
• ahrefs-pp-cli keywords-explorer volume-history — 時系列。検索ボリュームの履歴

public — Public のエンドポイント。

• ahrefs-pp-cli public crawler-ip-ranges — クローラーの IP 範囲
• ahrefs-pp-cli public crawler-ips — クローラーの IP アドレス

rank-tracker — Rank Tracker のエンドポイント。

• ahrefs-pp-cli rank-tracker competitors-overview — 競合他社の概要
• ahrefs-pp-cli rank-tracker overview — 概要
• ahrefs-pp-cli rank-tracker serp-overview — SERP の概要

serp-overview — Serp Overview のエンドポイント。

• ahrefs-pp-cli serp-overview — SERP の概要

site-audit — Site Audit のエンドポイント。

• ahrefs-pp-cli site-audit issues — プロジェクトの問題
• ahrefs-pp-cli site-audit page-content — ページコンテンツ
• ahrefs-pp-cli site-audit page-explorer — ページエクスプローラー
• ahrefs-pp-cli site-audit projects — プロジェクトの健全性スコア

site-explorer — Site Explorer のエンドポイント。

• ahrefs-pp-cli site-explorer all-backlinks — 被リンク
• ahrefs-pp-cli site-explorer backlinks-stats — 被リンクの統計
• ahrefs-pp-cli site-explorer broken-backlinks — 壊れた被リンク
• ahrefs-pp-cli site-explorer domain-rating — 特定時点のスナップショット。ドメインレーティング
• ahrefs-pp-cli site-explorer domain-rating-history — 時系列。ドメインレーティングの履歴
• ahrefs-pp-cli site-explorer metrics — 特定時点のスナップショット。指標
• ahrefs-pp-cli site-explorer metrics-by-country — 国別の指標
• ahrefs-pp-cli site-explorer organic-competitors — オーガニック検索の競合他社
• ahrefs-pp-cli site-explorer organic-keywords — オーガニック検索キーワード
• ahrefs-pp-cli site-explorer pages-by-traffic — トラフィック別のページ
• ahrefs-pp-cli site-explorer refdomains-history — 時系列。参照ドメインの履歴
• ahrefs-pp-cli site-explorer top-pages — 上位ページ

subscription-info — Subscription Info のエンドポイント。

• ahrefs-pp-cli subscription-info — 上限と使用状況

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

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

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

which は、自然言語で記述された機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は一致する項目が1つ以上あることを意味します。終了コード 2 は確かな一致がないことを意味します。その場合は --help を使うか、より具体的な問い合わせに切り替えてください。

認証の設定

環境変数で API キーを設定します。

export AHREFS_API_KEY="<your-key>"

または、~/.config/ahrefs-pp-cli/config.toml に保存します。

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

エージェントモード

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

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

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

  ahrefs-pp-cli keywords-explorer matching-terms --agent --select id,name,status
  

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

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

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

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

レスポンスのエンベロープ

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

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

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

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

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

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

記録は ~/.ahrefs-pp-cli/feedback.jsonl にローカル保存されます。AHREFS_FEEDBACK_ENDPOINT が設定され、かつ --send が渡された場合、または AHREFS_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」パターンです。

ahrefs-pp-cli profile save briefing --json
ahrefs-pp-cli --profile briefing keywords-explorer matching-terms
ahrefs-pp-cli profile list --json
ahrefs-pp-cli profile show briefing
ahrefs-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

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

2. Claude Code に登録します。

   claude mcp add ahrefs-pp-mcp -- ahrefs-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

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

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