pp-contact-goat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contact Goat - Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

contact-goat-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

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

Verify:
```
contact-goat-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能基于

contact-goat-pp-cli

二进制文件运行。调用本技能的任何命令前，必须先确认CLI已安装。若未安装，请按以下步骤操作：

通过Printing Press安装器安装：

bash

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

验证安装：
```
contact-goat-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

若

npx

安装失败（无Node环境、离线等），可直接通过Go安装（要求Go 1.23及以上版本）：

bash

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

中。在验证成功前，请勿执行本技能的任何命令。

When to Use This CLI

何时使用本CLI

Reach for this when the user wants:

coverage of a company (who you already know there, ranked by relationship strength)
a warm-intro path to a target person (mutual connections across sources)
prospecting (fan-out search with cross-source dedupe)
a unified dossier (LinkedIn profile + Happenstance research + optional Deepline enrichment)
network diffs over time (what's new in your graph in the last N days)
waterfall enrichment that walks free sources before paid ones

Skip it when the user has a workflow that lives entirely inside LinkedIn Sales Navigator, or when they only need raw LinkedIn scraping with no Happenstance or Deepline overlay (use the LinkedIn MCP directly in that case).

当用户有以下需求时，可使用本工具：

了解某公司的人脉覆盖情况（你在该公司已有的联系人，按关系亲密度排序）
获取与目标人物的暖介绍路径（跨来源的共同联系人）
潜在客户挖掘（跨来源去重的扩散式搜索）
统一档案（LinkedIn个人资料 + Happenstance调研数据 + 可选Deepline增强数据）
人脉网络差异分析（近N天内人脉图谱的新增内容）
瀑布式数据增强（优先使用免费来源，再切换到付费来源）

若用户的工作流完全在LinkedIn Sales Navigator内，或仅需纯LinkedIn数据抓取而无需Happenstance或Deepline叠加功能，则无需使用本工具（此时可直接使用LinkedIn MCP）。

Two Auth Surfaces

两种认证方式

Happenstance has two parallel auth paths and the CLI uses both:

Surface	Auth	Cost	Default?
Cookie web app	Chrome session cookies	Free monthly allocation	YES (auto-prefer)
Public REST API	HAPPENSTANCE_API_KEY (Bearer)	2 credits/search, 1 credit/research	Fallback only

The auto router prefers cookies until quota is exhausted, then falls back to bearer with an explicit "cost spent" log line on stderr. Use

--source api

coverage

hp people

prospect

, or

warm-intro

to opt into bearer explicitly (e.g. for the richer research schema or scoped group searches). Use

--source hp

to force the cookie surface.

The

api hpn *

subcommands always use the bearer surface and always cost credits. Provision and rotate keys at https://happenstance.ai/settings/api-keys.

Happenstance支持两种并行认证路径，CLI会同时使用：

认证方式	认证手段	成本	默认使用？
Cookie网页应用	Chrome会话Cookie	每月免费配额	是（自动优先）
公开REST API	HAPPENSTANCE_API_KEY（Bearer认证）	每次搜索消耗2点数，每次调研消耗1点数	仅作为 fallback

自动路由会优先使用Cookie认证，直到配额耗尽，然后自动切换到Bearer认证，并在stderr输出明确的“成本消耗”日志。在执行

coverage

、

hp people

、

prospect

或

warm-intro

命令时，可添加

--source api

参数明确选择Bearer认证（例如为了获取更丰富的调研数据结构或范围化群组搜索）；添加

--source hp

参数可强制使用Cookie认证。

api hpn *

子命令始终使用Bearer认证，且会消耗点数。可前往https://happenstance.ai/settings/api-keys获取和轮换密钥。

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
```
help
```
, or
```
--help
```
-> run
```
contact-goat-pp-cli --help
```
Starts with
```
install
```
and ends with
```
mcp
```
-> MCP installation (see below)
Starts with
```
install
```
-> CLI installation (see below)
Anything else -> Direct Use (map the request to the best command and run it)

解析

$ARGUMENTS

规则：

为空、
```
help
```
或
```
--help
```
→ 执行
```
contact-goat-pp-cli --help
```
以
```
install
```
开头且以
```
mcp
```
结尾 → 安装MCP服务器（见下文）
以
```
install
```
开头 → 安装CLI（见上文）
其他情况 → 直接使用（将用户请求映射到最佳命令并执行）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

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

bash

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

Ask the user for actual values of required API keys before running.

Verify:
```
claude mcp list
```
.

The MCP server exposes 16 tools. The four bearer-API tools added in this release are:

```
api_search
```
- Run a Happenstance public-API search (costs 2 credits)
```
api_research
```
- Run a deep-research dossier (costs 1 credit on completion)
```
api_groups_list
```
- List Happenstance groups for the caller (free)
```
api_usage
```
- Show live credit balance and usage history (free)

The other 12 tools cover the cookie surface (search, friends, feed, notifications, dossier, etc.) and the LinkedIn / Deepline integrations.

安装MCP服务器：

bash

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

在Claude Code中注册：

bash

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

执行前请向用户索要所需API密钥的实际值。

验证注册：
```
claude mcp list
```
。

MCP服务器提供16个工具。本次版本新增的4个Bearer API工具包括：

```
api_search
```
- 执行Happenstance公开API搜索（消耗2点数）
```
api_research
```
- 生成深度调研档案（完成后消耗1点数）
```
api_groups_list
```
- 列出调用者的Happenstance群组（免费）
```
api_usage
```
- 显示实时点数余额和使用历史（免费）

其余12个工具覆盖Cookie认证方式（搜索、好友、动态、通知、档案等）以及LinkedIn / Deepline集成功能。

Direct Use

直接使用

Check if installed:
```
which contact-goat-pp-cli
```
. If not found, offer CLI installation (above).

Discover commands:

contact-goat-pp-cli --help

. Drill into subcommand help with

contact-goat-pp-cli <command> --help

contact-goat-pp-cli api hpn <subcommand> --help

Match the user query to the best command (see Notable Commands below).
Execute with the
```
--agent
```
flag for structured, token-efficient output:
bash
```
contact-goat-pp-cli <command> [args] --agent
```

The

--agent

flag sets

--json --compact --no-input --no-color --yes

Source routing (cookie vs bearer) is automatic. The auto router prefers the free cookie surface and falls back to the paid bearer surface only when cookie quota is exhausted, logging a "cost spent" notice on stderr. Pass

--source api

to opt into bearer explicitly (richer schema, group-scoped searches), or

--source hp

to force cookies.

检查是否安装：
```
which contact-goat-pp-cli
```
。若未找到，提供CLI安装指引（见上文）。

查看命令列表：

contact-goat-pp-cli --help

。可通过

contact-goat-pp-cli <command> --help

或

contact-goat-pp-cli api hpn <subcommand> --help

查看子命令的详细帮助。

将用户查询匹配到最佳命令（见下文“常用命令”）。
添加
```
--agent
```
参数执行命令，以获得结构化、高效的Token输出：
bash
```
contact-goat-pp-cli <command> [args] --agent
```

--agent

参数等价于

--json --compact --no-input --no-color --yes

。

来源路由（Cookie vs Bearer）是自动的。自动路由优先使用免费的Cookie认证方式，仅当Cookie配额耗尽时才切换到付费的Bearer认证方式，并在stderr输出“成本消耗”通知。添加

--source api

参数可明确选择Bearer认证（更丰富的数据结构、群组范围搜索），或添加

--source hp

参数强制使用Cookie认证。

Enrichment Preflight (read this before running any enrichment command)

数据增强预检查（执行任何增强命令前请阅读）

These commands spend Deepline credits and REQUIRE

DEEPLINE_API_KEY

or a BYOK setup:

```
waterfall
```
(unless you pass
```
--byok
```
and have BYOK providers configured)
```
dossier --enrich-email
```

deepline find-email

enrich-person

email-find

phone-find

deepline search-people

search-companies

enrich-company

Before invoking any of these, verify auth by running doctor first:

bash

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

deepline_env

shows the resolution source:

```
set (env)
```
—
```
DEEPLINE_API_KEY
```
exported in the current shell
```
set (flag)
```
—
```
--deepline-key
```
passed on the command line
```
set (file:~/.local/deepline/<host>/.env)
```
— auto-discovered from the official Deepline CLI's persisted key (the user authenticated with
```
deepline auth register
```
or
```
deepline auth status
```
; no shell export needed)
```
not set
```
— none of the above. Ask the user for a key, or for a BYOK Hunter/Apollo key

The auto-discovery path means a user who has the Deepline CLI installed and authenticated does NOT need to re-export the key into their shell — contact-goat reads

~/.local/deepline/code-deepline-com/.env

directly (mode 0600, owned by the user). Don't ask the user to re-export when

set (file:...)

is reported. If

deepline_discovery_skipped

is also reported, those are candidate files the resolver rejected for a security reason (wrong mode, missing prefix); surface them so the user can fix the underlying issue.

Provider chain by target kind (waterfall):

Target	Primary	Fallback 1	Fallback 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

Notes:

Name targets MUST pass
```
--company <domain>
```
(or set
```
CONTACT_GOAT_COMPANY
```
env).
Apollo returns
```
personal_emails[]
```
when available; treat
```
email_status: "unavailable"
```
as "no verified work email on file" (the personal email is still usable).
Dropleads returns
```
status: "catch_all"
```
for domains on Google Workspace; the email is a pattern guess, not a verified mailbox.
Provider-level 403s are surfaced as "Provider not connected" rather than "Check DEEPLINE_API_KEY"; they do not abort the chain. The next provider is tried automatically.

以下命令会消耗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命令验证认证状态：

bash

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

deepline_env

会显示密钥的来源：

```
set (env)
```
—
```
DEEPLINE_API_KEY
```
已在当前shell中导出
```
set (flag)
```
— 命令行中已传入
```
--deepline-key
```
参数
```
set (file:~/.local/deepline/<host>/.env)
```
— 从官方Deepline CLI的持久化密钥自动发现（用户已通过
```
deepline auth register
```
或
```
deepline auth status
```
完成认证；无需在shell中导出）
```
not set
```
— 未配置以上任何方式。请向用户索要密钥，或配置BYOK Hunter/Apollo密钥

自动发现路径意味着：若用户已安装并认证Deepline CLI，则无需在shell中重新导出密钥 — contact-goat会直接读取

~/.local/deepline/code-deepline-com/.env

文件（权限为0600，归用户所有）。当显示

set (file:...)

时，无需要求用户重新导出密钥。若同时显示

deepline_discovery_skipped

，表示解析器因安全原因（权限错误、前缀缺失）拒绝了候选文件，请告知用户以便修复底层问题。

按目标类型划分的提供商链（瀑布式）：

目标类型	首选提供商	备用提供商1	备用提供商2
LinkedIn URL	apollo_people_match	hunter_people_find	contactout_enrich_person
邮箱	apollo_people_match	hunter_people_find	-
姓名 + --company	dropleads_email_finder	hunter_email_finder	datagma_find_email

注意事项：

姓名类型的目标必须传入
--company <domain>
参数（或设置
```
CONTACT_GOAT_COMPANY
```
环境变量）。
Apollo会返回
```
personal_emails[]
```
（若有）；当
```
email_status: "unavailable"
```
时，表示“无已验证的工作邮箱记录”（个人邮箱仍可使用）。
Dropleads针对Google Workspace域名会返回
```
status: "catch_all"
```
；此时邮箱为模式猜测值，并非已验证的邮箱。
提供商级别的403错误会显示为“提供商未连接”而非“检查DEEPLINE_API_KEY”；此类错误不会终止提供商链，会自动尝试下一个提供商。

Notable Commands

常用命令

Command	What it does
`coverage <company>`	Who you know at a company across LinkedIn + Happenstance, ranked by relationship strength
`coverage --location <city>`	Who you know in a city. Bearer-only (cookie surface has no city-search); use `--source api` .
`hp people <query>`	Happenstance graph people-search (1st / 2nd / 3rd degree). `--csv` emits flat CSV with semicolon-joined bridges.
`prospect <query>`	Fan-out search across LinkedIn + Happenstance (+ opt-in Deepline), deduped
`warm-intro <target>`	Mutual connections across sources who could intro you to a target
`waterfall <target> [--company X]`	Free-sources-first enrichment, falls through to Deepline provider chain. Requires DEEPLINE_API_KEY or --byok. Bare-name targets need --company
`dossier <target> [--enrich-email]`	Unified LinkedIn + Happenstance + (optional) Deepline dossier. --enrich-email requires DEEPLINE_API_KEY
`deepline find-email "<name>" --company <domain>`	Single-call work-email lookup via dropleads_email_finder
`deepline enrich-person <linkedin-url>`	Full person record via apollo_people_match (includes personal_emails[])
`api hpn search <text>`	Bearer-API search (costs 2 credits, async with poll). `--first-degree-only` keeps only 1st-degree matches; `--min-score N` drops weak signals (see docs/scoring.md); `--all --max-results N` auto-paginates.
`api hpn research <description>`	Bearer-API deep dossier (costs 1 credit on completion)
`api hpn usage`	Live credit balance, purchases, recent usage events (free)
`doctor`	Check CLI health, both Happenstance surfaces, LinkedIn, and Deepline. Reports `happenstance_graph_status` (ok / stale / very_stale) on the LinkedIn upload age.

Run any command with

--help

for full flag documentation.

命令	功能
`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单次查询工作邮箱
`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的连接状态。会报告 `happenstance_graph_status` （ok / stale / very_stale），代表LinkedIn数据上传的时效性。

执行任何命令时添加

--help

参数可查看完整的参数文档。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields, with dotted-path support (see below)
Previewable —
```
--dry-run
```
shows the request without sending
Cacheable — GET responses cached for 5 minutes, bypass with
```
--no-cache
```
Non-interactive — never prompts, every input is a flag

在任何命令后添加

--agent

参数，等价于：

--json --compact --no-input --no-color --yes

。

可管道传输 — 标准输出为JSON格式，错误信息输出到标准错误
可过滤 —
```
--select
```
参数可保留指定字段子集，支持点路径（见下文）
可预览 —
```
--dry-run
```
参数可显示请求内容但不发送
可缓存 — GET请求会缓存5分钟，添加
```
--no-cache
```
参数可绕过缓存
非交互式 — 永不弹出提示，所有输入均通过参数传入

Filtering output

输出过滤

--select

accepts dotted paths to descend into nested responses; arrays traverse element-wise:

bash

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

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

--select

参数接受点路径以遍历嵌套响应；数组会逐个元素遍历：

bash

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

使用该参数可将庞大的响应内容精简到实际需要的字段 — 这对于深度嵌套的API响应至关重要。

Response envelope

响应信封

Data-layer commands wrap output in

{"meta": {...}, "results": <data>}

. Parse

.results

for data and

.meta.source

to know whether it's

live

or local. The

N results (live)

summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout.

数据层命令会将输出包裹在

{"meta": {...}, "results": <data>}

结构中。可解析

.results

获取数据，

.meta.source

可判断数据是

live

（实时）还是本地缓存。当标准输出为TTY时，

N results (live)

摘要会输出到标准错误；管道/Agent消费者仅会在标准输出看到纯JSON内容。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue, including bearer 402 out-of-credits)
7	Rate limited (cookie 429 or bearer 429; auto-fallback may apply)

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题，包括Bearer认证的402点数耗尽）
7	速率限制（Cookie认证429或Bearer认证429；可能自动切换到备用方式）