CLI - Happenstance

The Happenstance CLI (hpn) gives you access to the full Happenstance API from your terminal. All output is JSON, so you can pipe results to jq or integrate with scripts.

Install

Requires Python 3.11+.

Homebrew
uv
pipx
pip

brew tap happenstance-ai/tap
brew install happenstance

uv tool install happenstance

pipx install happenstance

pip install happenstance

Configure

Get your API key from the Settings page, then:

hpn config set --api-key YOUR_API_KEY

The API key can also be provided via the HPN_API_KEY environment variable or the --api-key flag on any command. Priority: flag > env var > config file. Verify your configuration:

hpn config show

Commands

Command	Description
`hpn config set --api-key KEY`	Save your API key
`hpn config show`	Show saved API key (masked)
`hpn search "query"`	Search your network
`hpn search get ID`	Get search results by ID
`hpn search find-more ID`	Find additional results for an existing search
`hpn research "description"`	Research a person
`hpn research get ID`	Get research results by ID
`hpn friends`	List your friends (useful for @mentions)
`hpn groups`	List your groups
`hpn groups get ID`	Get group details and members
`hpn usage`	Show credit balance and usage

Search Your Network

hpn search "engineers who have worked on AI infrastructure"

By default, the CLI waits for the search to complete and prints the results. Use --no-wait to get the search ID immediately and poll later:

# Start search without waiting
hpn search "ML engineers in SF" --no-wait

# Poll for results later
hpn search get SEARCH_ID

Scope Control

Control where to search with scope flags. When no flags are specified, all sources are searched.

# Search only your own connections
hpn search "product managers" --my-connections

# Search only your friends' connections
hpn search "designers" --friends

# Search specific groups
hpn search "engineers" --groups "YC Founders" "AI Club"

# Combine scopes
hpn search "CTOs" --my-connections --groups "YC Founders"

@Mentions

Filter results to a specific person’s connections using @mentions in your query:

hpn search "engineers @Jane Smith knows"

Use hpn friends or hpn groups get ID to look up names for @mentions.

Find More Results

If a search returns has_more: true, get additional results (costs 2 credits):

hpn search find-more SEARCH_ID

Research a Person

hpn research "Garry Tan, CEO of Y Combinator, @garrytan on Twitter"

Include as much detail as possible (full name, company, title, social handles) for best results. The CLI waits for the research to complete (up to 10 minutes). Use --no-wait to return the research ID immediately:

hpn research "Jane Smith, CTO at Acme Corp" --no-wait

hpn research get RESEARCH_ID

Check Credits

hpn usage

Returns your credit balance, purchase history, usage history, and auto-reload settings.

Pipe to jq

All output is JSON. Combine with jq for filtering and formatting:

# Get just the names from search results
hpn search "engineers" | jq '.results[].name'

# Pretty-print a research profile
hpn research "Jane Smith" | jq '.profile'

# List group names
hpn groups | jq '.groups[].name'

Need Help?

Support

Contact our support team

​Install

​Configure

​Commands

​Search Your Network

​Scope Control

​@Mentions

​Find More Results

​Research a Person

​Check Credits

​Pipe to jq

​Need Help?