Skip to main content
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+.

​
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

CommandDescription
hpn config set --api-key KEYSave your API key
hpn config showShow saved API key (masked)
hpn search "query"Search your network
hpn search get IDGet search results by ID
hpn search find-more IDFind additional results for an existing search
hpn research "description"Research a person
hpn research get IDGet research results by ID
hpn friendsList your friends (useful for @mentions)
hpn groupsList your groups
hpn groups get IDGet group details and members
hpn usageShow 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