Sales and CRM

Contact GOAT

pp-contact-goat

Search, enrich, and map warm-introduction paths across LinkedIn, Happenstance, Deepline, and a unified local contacts store.

Printed by @mvanhorn (Matt Van Horn)

Install

npx — recommended

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

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-contact-goat --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-contact-goat skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-contact-goat. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Super LinkedIn for the terminal. Search, enrich, and map warm-intro paths across LinkedIn, Happenstance, and Deepline from one SQLite-backed CLI.

Authentication

Contact Goat reaches three sources. Each has its own auth path; all three are optional — the CLI runs with whichever sources you've authenticated.

Two auth surfaces (Happenstance)

Happenstance has two parallel auth paths and the CLI supports both. The auto router prefers the cookie surface (free monthly allocation) and falls back to the bearer surface (paid credits) only when the cookie quota is exhausted.

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

Pass --source api on coverage, hp people, prospect, or warm-intro to opt into the bearer surface explicitly (richer schema, group-scoped searches). The api hpn * subcommands always use the bearer surface. Provision and rotate keys at https://happenstance.ai/settings/api-keys.

Happenstance (free web-app allocation, cookie auth)

Happenstance uses your logged-in Chrome session — no API key, no credit burn. On macOS, run:

contact-goat-pp-cli auth login --chrome --service happenstance

Cookies are written to ~/.config/contact-goat-pp-cli/cookies-happenstance.json (mode 0600). The file contains plaintext cookie values — treat it like any other credential file. For scripted environments, set the env var instead:

export HAPPENSTANCE_WEB_APP_COOKIE_AUTH="<your-cookie-auth>"

LinkedIn (scraper subprocess, browser session)

Commands under linkedin and the cross-source commands (warm-intro, coverage, prospect) call the stickerdaniel/linkedin-mcp-server via uvx. Log in once:

uvx linkedin-scraper-mcp@latest --login

Deepline (paid, credit-based)

Only needed for waterfall, dossier --enrich-email, prospect --deepline, and budget. Get a key from code.deepline.com:

export DEEPLINE_API_KEY="dlp_..."

If you have the official Deepline CLI installed and authenticated (deepline auth register or deepline auth status), contact-goat auto-discovers the saved key from ~/.local/deepline/<host>/.env — you do not need to re-export it into your shell. The resolver checks --deepline-key first, then DEEPLINE_API_KEY env, then the sibling-CLI file (mode 0600 or 0400 required, value must start with dlp_, no symlinks outside $HOME). contact-goat-pp-cli doctor reports the resolution source as set (env) / set (flag) / set (file:~/.local/...) / not set.

Every Deepline-touching command surfaces estimated credit cost before execution and requires --yes to spend.

Self-hosted Happenstance

Override the base URL with CONTACT_GOAT_BASE_URL=https://your-host.

Quick Start

# 1. Check your setup (shows which sources are authenticated)
contact-goat-pp-cli doctor

# 2. Import Happenstance cookies from Chrome (macOS)
contact-goat-pp-cli auth login --chrome --service happenstance

# 3. See who you already know at a company
contact-goat-pp-cli coverage stripe

# 4. Find warm intros to a target person
contact-goat-pp-cli warm-intro "Patrick Collison"

# 5. What's changed in your network in the last week
contact-goat-pp-cli since 7d

Unique Features

These capabilities aren't available in any other tool for this API.

warm-intro <target> — Given a target person, find mutual connections across your LinkedIn 1st-degree AND your Happenstance network who can introduce you.
coverage <company> — For any company, see who you already know there via LinkedIn 1st-degree or Happenstance friends, ranked by relationship strength.
prospect <query> — Fan-out search across LinkedIn, Happenstance, and Deepline (budget-gated). Dedupes by LinkedIn URL, ranks by network strength plus relevance.
dossier <person> — Compose a single view of a person from LinkedIn profile, Happenstance research, and optionally Deepline enrichment.
budget — Aggregate Deepline spend this month, recent high-cost calls, enforce limits.
intersect — People who appear in BOTH your LinkedIn 1st-degree AND your Happenstance network. Your highest-signal warm intros.
since <duration> — Time-windowed diff across LinkedIn connections, Happenstance feed, and new research.
graph export — Export your full cross-source network as GEXF, DOT, or JSON for Gephi or Graphviz.
waterfall <target> — Clay-style enrichment that walks LinkedIn → Happenstance → Deepline BYOK → Deepline managed, stopping at the first hit to minimize spend.

Commands

Cross-source (the reason to install)

Command	What it does
`warm-intro <target>`	Find mutuals across LinkedIn + Happenstance who can intro
`coverage <company>`	Who you know at a company, across sources
`prospect <query>`	Fan-out search, dedupe, rank by network strength
`dossier <person>`	Unified profile from all configured sources
`intersect`	People in both LinkedIn 1st-degree AND Happenstance
`since <duration>`	Time-windowed diff of new items
`engagement <person>`	Score last-touch engagement across all sources
`stale`	Warm intros going cold — researched but not followed up
`graph export`	Export the unified contact graph as GEXF/DOT/JSON
`waterfall <target>`	Progressive enrichment, cheapest source first

Happenstance (cookie auth)

Command	What it does
`feed`	Latest posts from your Happenstance network
`friends`	Your Happenstance friends (top connectors)
`groups`	Your Happenstance groups
`notifications`	New friend posts, research completions, search results
`research`	List recent research dossiers
`clerk --referrer-id`	Resolve a referrer UUID to a user profile
`dynamo --request-id`	Look up an async search by request_id
`user get`	Current authenticated user
`user get-limits`	Searches remaining, renewal date
`uploads`	Status of uploaded data sources (LinkedIn, Gmail, etc)

LinkedIn (scraper subprocess)

Command	What it does
`linkedin`	LinkedIn scraper powered by stickerdaniel/linkedin-mcp-server

Deepline (paid)

Command	What it does
`deepline`	Contact-data API: email, phone, company enrichment
`budget`	Credit spend this month, top tools, recent calls

Data layer (local SQLite)

Command	What it does
`sync`	Sync API data to local SQLite for offline search
`search <query>`	Full-text search across synced data or live API
`analytics`	Run analytics queries on locally synced data
`export`	Export data to JSONL or JSON for backup
`import`	Import data from JSONL via API create/upsert
`tail`	Stream NEW items across LinkedIn + Happenstance

Utilities

Command	What it does
`doctor`	Check CLI health, auth, and connectivity
`auth login --chrome --service happenstance`	Import Chrome cookies
`config byok set <provider> <env-var-name>`	Register BYOK keys for Deepline
`api`	Browse all API endpoints by interface name
`workflow`	Compound workflows that combine API operations

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

Output Formats

# Human-readable table (default in terminal)
contact-goat-pp-cli coverage stripe

# JSON when piped (automatic) or explicit
contact-goat-pp-cli coverage stripe --json

# Filter to specific fields
contact-goat-pp-cli friends --json --select name,company,connection_count

# CSV for spreadsheet import
contact-goat-pp-cli coverage openai --csv

# Compact — drop nulls and verbose fields
contact-goat-pp-cli dossier "Satya Nadella" --json --compact

# Dry run — preview without spending credits or making API calls
contact-goat-pp-cli prospect "CTO fintech" --deepline --budget 5 --dry-run

# Agent mode — sets --json --compact --no-input --no-color --yes
contact-goat-pp-cli warm-intro "Patrick Collison" --agent

Agent Usage

Contact Goat is designed for AI agent consumption:

Non-interactive — never prompts when --no-input or --agent is set
Pipeable — --json to stdout, errors to stderr, one record per line where sensible
Filterable — --select field1,field2 returns only requested fields
Previewable — --dry-run on every paid/mutating command
Cacheable — GET responses cached; bypass with --no-cache
Confirmable — --yes for explicit acknowledgement of Deepline credit spend
Typed exit codes — 0 success, 2 usage, 3 not found, 4 auth, 5 API, 7 rate limited, 10 config

All agent defaults in one flag: --agent.

Cookbook

# Find warm intros to a target (ranked by source strength)
contact-goat-pp-cli warm-intro "Patrick Collison" --json --limit 5

# Who do I know at OpenAI? Happenstance only, no LinkedIn scraper call.
contact-goat-pp-cli coverage "OpenAI" --source hp --limit 10

# Prospect without spending Deepline credits
contact-goat-pp-cli prospect "VP engineering fintech" --limit 50

# Prospect WITH Deepline, hard-capped at 5 credits
contact-goat-pp-cli prospect "Director Product" --deepline --budget 5 --yes

# One-shot unified profile
contact-goat-pp-cli dossier https://www.linkedin.com/in/patrickcollison --json

# Enrich a bare email via the cheapest source that has it
contact-goat-pp-cli waterfall alice@stripe.com --max-cost 2 --json

# Prefer BYOK keys for Deepline steps; fail if none configured
contact-goat-pp-cli waterfall "Brian Chesky" --company airbnb.com --byok

# What's new in the last 24 hours, JSON
contact-goat-pp-cli since 24h --json

# People in BOTH LinkedIn 1st-degree AND Happenstance friends (your strongest signals)
contact-goat-pp-cli intersect --json

# Export the unified graph for Gephi
contact-goat-pp-cli graph export --format gexf > network.gexf

# Stream NEW items across sources (watch mode)
contact-goat-pp-cli tail --sources li,hp

# Search locally synced data with FTS5
contact-goat-pp-cli search "fintech" --data-source local --limit 20

# Deepline spend this month
contact-goat-pp-cli budget --json

# Sync, then search, with a dedicated DB path
contact-goat-pp-cli sync --resources friends
contact-goat-pp-cli search "stripe" --data-source local

# Register a BYOK key so waterfall uses your Hunter subscription
contact-goat-pp-cli config byok set hunter HUNTER_API_KEY

Health Check

contact-goat-pp-cli doctor

Sample output:

  OK Config: ok
  OK Auth: configured
  OK API: reachable
  OK Happenstance: cookies: found: 14 cookies (~/.config/contact-goat-pp-cli/cookies-happenstance.json)
  OK Happenstance: session JWT: valid
  OK LinkedIn: Python: ok (3.14.3)
  OK LinkedIn: uvx: ok
  OK LinkedIn: binary: will launch via `uvx linkedin-scraper-mcp@latest`
  WARN LinkedIn: profile: not logged in — run `uvx linkedin-scraper-mcp@latest --login`
  OK Deepline: DEEPLINE_API_KEY: set (file:~/.local/deepline/code-deepline-com/.env)
  OK Deepline: prefix: ok (dlp_)
  OK Deepline: CLI on PATH: /Users/you/.local/bin/deepline
  config_path: ~/.config/contact-goat-pp-cli/config.toml
  base_url: https://happenstance.ai
  version: 0.1.0

WARN rows are OK — they just mean that source isn't wired up yet.

Configuration

Config file: ~/.config/contact-goat-pp-cli/config.toml

Environment variables:

Variable	Purpose
`HAPPENSTANCE_WEB_APP_COOKIE_AUTH`	Cookie auth blob for Happenstance (alternative to `auth login --chrome`)
`HAPPENSTANCE_API_KEY`	Bearer key for the Happenstance public REST API (`hpn_live_personal_...`). Provision at https://happenstance.ai/settings/api-keys
`DEEPLINE_API_KEY`	Deepline API key (`dlp_...`). Required for paid commands
`CONTACT_GOAT_BASE_URL`	Override Happenstance base URL (self-hosted)
`CONTACT_GOAT_CONFIG`	Config file path override
`HUNTER_API_KEY`, `APOLLO_API_KEY`, ...	BYOK keys registered via `config byok set`
`NO_COLOR`	Disable colored output (standard)

Use as MCP Server

Contact Goat ships a companion MCP server for Claude Desktop, Cursor, and other MCP-compatible tools.

Claude Code

claude mcp add contact-goat contact-goat-pp-mcp \
  -e HAPPENSTANCE_WEB_APP_COOKIE_AUTH="$HAPPENSTANCE_WEB_APP_COOKIE_AUTH" \
  -e DEEPLINE_API_KEY="$DEEPLINE_API_KEY"

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "contact-goat": {
      "command": "contact-goat-pp-mcp",
      "env": {
        "HAPPENSTANCE_WEB_APP_COOKIE_AUTH": "<your-cookie-auth>",
        "DEEPLINE_API_KEY": "<your-deepline-key>"
      }
    }
  }
}

Troubleshooting

Authentication errors (exit code 4)

Run contact-goat-pp-cli doctor to see which source is unauthenticated
For Happenstance: contact-goat-pp-cli auth login --chrome --service happenstance
For LinkedIn: uvx linkedin-scraper-mcp@latest --login
For Deepline: export DEEPLINE_API_KEY=dlp_...

Rate limit errors (exit code 7)

The CLI auto-retries with exponential backoff
Default rate limit is 2 requests/second — raise with --rate-limit 5
Happenstance free tier is 14 searches/month; user get-limits shows remaining

Deepline credit errors

waterfall, prospect --deepline, and dossier --enrich-email require both --budget > 0 and --yes to spend
contact-goat-pp-cli budget shows your month-to-date spend

Not found errors (exit code 3)

LinkedIn URLs and slugs are validated strictly — check for typos
Happenstance research dossiers expire; re-run dossier with --no-cache

Rate Limits

LinkedIn scraper: governed by your own browser session; no documented limit
Happenstance web app: 14 searches/month on free tier (your actual limit is in user get-limits)
Deepline: credit-based, see your balance at code.deepline.com

Data Sources

This CLI unifies three distinct sources:

LinkedIn via stickerdaniel/linkedin-mcp-server (Python MCP, subprocess)
Happenstance via sniffed web-app endpoints (Clerk session cookies, free tier)
Deepline via code.deepline.com (Bearer token, credit-based)

The web-app Happenstance endpoints are DISTINCT from the public REST API at api.happenstance.ai/v1 — that one uses Bearer-token auth and burns paid credits. We target the web app your browser already uses.

Sources & Inspiration

Built by studying these projects:

stickerdaniel/linkedin-mcp-server — Python (1610 stars)
joeyism/linkedin_scraper — Python (3969 stars)
tomquirk/linkedin-api — Python
Happenstance hpn — Python
Deepline CLI — Shell

Generated by CLI Printing Press.