pp-contact-goat

Contact Goat - Printing Press CLI

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

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/contact-goat/cmd/contact-goat-pp-cli@latest

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

この CLI を使用する場面

次のような要望があれば、この CLI を利用してください。

• 企業の人脈を把握する（すでに知っている人物を、人間関係の強さ順に表示する）
• 目標とする人物へのウォームイントロ経路を探す（複数のソースにまたがる共通のつながり）
• 見込み客を探す（複数の検索を同時に実行し、ソースをまたいで重複を除去する）
• 統合された人物情報を取得する（LinkedIn プロフィール + Happenstance の調査 + 必要に応じた Deepline による情報補完）
• 時間の経過に伴うネットワークの差分を確認する（過去 N 日間にネットワークへ加わった新しい情報）
• 無料のソースから順に有料ソースへ進むウォーターフォール方式で情報を補完する

ワークフローが LinkedIn Sales Navigator 内で完結している場合や、Happenstance または Deepline の情報を付加せず、LinkedIn の生データをスクレイピングするだけでよい場合は、この CLI は使わないでください（その場合は LinkedIn MCP を直接使用してください）。

2 つの認証方式

Happenstance には並行して使用できる 2 つの認証方式があり、CLI は両方を使用します。

方式	認証	コスト	デフォルト？
Cookie を使うウェブアプリ	Chrome のセッション Cookie	毎月の無料利用枠	はい（自動的に優先）
公開 REST API	HAPPENSTANCE_API_KEY（Bearer）	検索 2 クレジット、調査 1 クレジット	フォールバックのみ

自動ルーターは、割り当て量を使い切るまでは Cookie を優先し、その後は Bearer に切り替えます。その際、stderr に「cost spent（消費コスト）」を明示するログ行が出力されます。Bearer を明示的に使用するには、coverage、hp people、prospect、warm-intro で --source api を指定してください（たとえば、より詳細な調査スキーマや、グループを絞り込んだ検索を利用する場合）。Cookie 方式を強制するには --source hp を指定してください。

api hpn * サブコマンドは常に Bearer 方式を使い、必ずクレジットを消費します。キーの発行とローテーションは https://happenstance.ai/settings/api-keys で行ってください。

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help の場合 -> contact-goat-pp-cli --help を実行
2. install で始まり mcp で終わる場合 -> MCP のインストール（以下を参照）
3. install で始まる場合 -> CLI のインストール（以下を参照）
4. 上記以外の場合 -> 直接使用（リクエストに最適なコマンドを割り当てて実行）

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

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

   go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/contact-goat/cmd/contact-goat-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add -e DEEPLINE_API_KEY=value -e HAPPENSTANCE_API_KEY=value contact-goat-pp-mcp -- contact-goat-pp-mcp
   

   実行する前に、必要な API キーの実際の値をユーザーに確認してください。
3. 確認します：claude mcp list

MCP サーバーは 16 個のツールを公開します。このリリースで追加された Bearer API 用ツールは次の 4 つです。

• api_search - Happenstance 公開 API の検索を実行します（2 クレジットを消費）
• api_research - 詳細な調査資料を作成します（完了時に 1 クレジットを消費）
• api_groups_list - 呼び出しユーザーの Happenstance グループを一覧表示します（無料）
• api_usage - 現在のクレジット残高と利用履歴を表示します（無料）

その他の 12 個のツールは、Cookie 方式（検索、友人、フィード、通知、人物情報など）と LinkedIn／Deepline 連携を対象としています。

直接使用する

1. インストール済みか確認します：which contact-goat-pp-cli。見つからない場合は、上記の CLI インストールを案内します。
2. コマンドを確認します：contact-goat-pp-cli --help。contact-goat-pp-cli <command> --help または contact-goat-pp-cli api hpn <subcommand> --help でサブコマンドのヘルプを確認します。
3. ユーザーのクエリに最適なコマンドを選びます（下記の注目コマンドを参照）。
4. 構造化され、トークン効率の高い出力を得るには、--agent フラグを付けて実行します：

   contact-goat-pp-cli <command> [args] --agent
   

5. --agent フラグを指定すると、--json --compact --no-input --no-color --yes が設定されます。

ソースの振り分け（cookie と bearer）は自動で行われます。自動ルーターは無料の cookie 用インターフェースを優先し、cookie の割り当てを使い切った場合にのみ、有料の bearer 用インターフェースにフォールバックします。その際、stderr に「cost spent」の通知を記録します。明示的に bearer を使用するには --source api を指定します（より充実したスキーマとグループ単位の検索が利用できます）。cookie を強制的に使用するには --source hp を指定します。

エンリッチメント前の確認（エンリッチメントコマンドを実行する前にお読みください）

以下のコマンドは Deepline クレジットを消費し、DEEPLINE_API_KEY または BYOK の設定が必要です：

• waterfall（--byok を指定し、BYOK プロバイダーが設定されている場合を除く）
• dossier --enrich-email
• deepline find-email / enrich-person / email-find / phone-find
• deepline search-people / search-companies / enrich-company

これらを実行する前に、まず doctor を実行して認証を確認してください：

contact-goat-pp-cli doctor --agent | grep -i deepline

deepline_env には、キーの解決元が表示されます：

• set (env) — 現在のシェルで DEEPLINE_API_KEY がエクスポートされています
• set (flag) — コマンドラインで --deepline-key が渡されています
• set (file:~/.local/deepline/<host>/.env) — 公式 Deepline CLI に保存されたキーから自動検出されています（ユーザーは deepline auth register または deepline auth status で認証済みです。シェルでエクスポートする必要はありません）
• not set — 上記のいずれにも該当しません。ユーザーにキー、または BYOK の Hunter/Apollo キーを求めてください

自動検出により、Deepline CLI をインストールして認証済みのユーザーは、キーをシェルに再エクスポートする必要がありません。contact-goat は ~/.local/deepline/code-deepline-com/.env を直接読み取ります（モード 0600、所有者はユーザー）。set (file:...) と表示された場合は、キーの再エクスポートを求めないでください。deepline_discovery_skipped も表示された場合、セキュリティ上の理由（モードが不正、またはプレフィックスがない）でリゾルバーが拒否した候補ファイルがあります。ユーザーが根本的な問題を修正できるよう、それらを提示してください。

ターゲットの種類ごとのプロバイダーチェーン（waterfall）：

ターゲット	プライマリ	フォールバック 1	フォールバック 2
LinkedIn URL	apollo_people_match	hunter_people_find	contactout_enrich_person
Email	apollo_people_match	hunter_people_find	-
Name + --company	dropleads_email_finder	hunter_email_finder	datagma_find_email

注記：

• 名前をターゲットにする場合は、--company <domain> を必ず指定する必要があります（または CONTACT_GOAT_COMPANY env を設定してください）。
• Apollo は利用可能な場合 personal_emails[] を返します。email_status: "unavailable" は「登録されている確認済みの仕事用メールアドレスがない」と扱ってください（個人用メールアドレスは引き続き使用できます）。
• Dropleads は Google Workspace のドメインに対して status: "catch_all" を返します。このメールアドレスはパターンから推測したものであり、メールボックスが確認済みであることを示すものではありません。
• プロバイダーレベルの 403 は「Check DEEPLINE_API_KEY」ではなく「Provider not connected」として表示され、チェーンを中断しません。次のプロバイダーが自動的に試されます。

主なコマンド

コマンド	機能
coverage <company>	LinkedIn と Happenstance 全体で、その企業に知り合いがいるかを関係の強さ順に表示します
coverage --location <city>	その都市に知り合いがいるかを表示します。Bearer のみ対応しています（Cookie のインターフェースでは都市検索を利用できません）。--source api を使用してください。
hp people <query>	Happenstance のグラフで人物を検索します（1次／2次／3次のつながり）。--csv を指定すると、橋渡しとなる人物をセミコロンで連結したフラットな CSV を出力します。
prospect <query>	LinkedIn、Happenstance、（オプトイン時は Deepline）を横断して検索し、重複を除外します
warm-intro <target>	複数のソースから、対象者を紹介してくれそうな共通のつながりを検索します
waterfall <target> [--company X]	無料ソースを優先して情報を補完し、Deepline のプロバイダーチェーンへ順に進みます。DEEPLINE_API_KEY または --byok が必要です。氏名のみの対象には --company が必要です
dossier <target> [--enrich-email]	LinkedIn、Happenstance、（任意で）Deepline の情報を統合した人物プロフィールを作成します。--enrich-email には DEEPLINE_API_KEY が必要です
deepline find-email "<name>" --company <domain>	dropleads_email_finder を使って、1 回の呼び出しで仕事用メールアドレスを検索します
deepline enrich-person <linkedin-url>	apollo_people_match を使って人物の完全なレコードを取得します（personal_emails[] を含みます）
api hpn search <text>	Bearer API で検索します（2 クレジットを消費し、ポーリングを伴う非同期処理です）。--first-degree-only を指定すると1次のつながりのみが対象になります。--min-score N を指定すると、弱いシグナルを除外します（docs/scoring.md を参照）。--all --max-results N を指定すると、自動でページネーションします。
api hpn research <description>	Bearer API で詳細な人物プロフィールを作成します（完了時に1クレジットを消費します）
api hpn usage	現在のクレジット残高、購入履歴、最近の利用イベントを表示します（無料）
doctor	CLI の状態、両方の Happenstance インターフェース、LinkedIn、Deepline を確認します。LinkedIn へのアップロードからの経過時間に基づく happenstance_graph_status（ok / stale / very_stale）を報告します。

各コマンドに --help を付けると、フラグの詳細を確認できます。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションがまとめて有効になります：--json --compact --no-input --no-color --yes。

• パイプで利用可能 — stdout に JSON、stderr にエラーを出力します
• フィルター可能 — --select でフィールドを絞り込めます。ドット区切りのパスにも対応しています（以下を参照）
• プレビュー可能 — --dry-run で、送信せずにリクエストを表示します
• キャッシュ可能 — GET レスポンスは5分間キャッシュされます。--no-cache でキャッシュを回避できます
• 非対話型 — プロンプトは表示されず、すべての入力をフラグで指定します

出力のフィルタリング

--select は、ネストされたレスポンスをたどるドット区切りのパスに対応しています。配列の場合は、各要素をたどります。

contact-goat-pp-cli <command> --agent --select id,name
contact-goat-pp-cli <command> --agent --select items.id,items.owner.name

これを使うと、巨大なペイロードから必要なフィールドだけに絞り込めます。深くネストされた API レスポンスを扱う際に特に便利です。

レスポンスエンベロープ

データレイヤーのコマンドは、出力を {"meta": {...}, "results": <data>} でラップします。データには .results を解析し、ソースが live かローカルかを確認するには .meta.source を解析してください。N results (live) の概要が stderr に出力されるのは、stdout が TTY の場合のみです。パイプやエージェントから利用する場合、stdout には JSON のみが出力されます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（Bearer の残高不足による 402 など、上流での問題）
7	レート制限（Cookie の 429 または Bearer の 429。自動フォールバックが適用される場合があります）