pp-contact-goat

Contact Goat - Printing Press CLI

Prerequisites: Install the 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:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install contact-goat --cli-only
2. Verify: contact-goat-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

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

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This 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).

Two Auth Surfaces

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

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 on 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.

Argument Parsing

Parse $ARGUMENTS:

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

MCP Server Installation

1. Install the MCP server:

   go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/contact-goat/cmd/contact-goat-pp-mcp@latest
2. Register with Claude Code:

   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.
3. 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.

Direct Use

1. Check if installed: which contact-goat-pp-cli. If not found, offer CLI installation (above).
2. Discover commands: contact-goat-pp-cli --help. Drill into subcommand help with contact-goat-pp-cli <command> --help or contact-goat-pp-cli api hpn <subcommand> --help.
3. Match the user query to the best command (see Notable Commands below).
4. Execute with the --agent flag for structured, token-efficient output:

   contact-goat-pp-cli <command> [args] --agent
5. 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.

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:

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):

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.

Notable Commands

Run any command with --help for full flag documentation.

Agent Mode

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

Filtering output

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

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.

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.

Exit Codes