Metadata-Version: 2.4
Name: happenstance
Version: 0.2.2
Summary: Happenstance CLI — search your network with AI for sales, hiring, fundraising, and more
Project-URL: Homepage, https://happenstance.ai
Project-URL: Documentation, https://developer.happenstance.ai
Author-email: Happenstance <support@happenstance.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,happenstance,network,people,search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# happenstance

Command-line interface for [Happenstance](https://happenstance.ai) — search your network with AI. Find warm intros for sales, source referral candidates for hiring, discover investors for fundraising, and research anyone in your network.

## Install

```bash
# Homebrew (macOS / Linux)
brew tap happenstance-ai/tap
brew install happenstance

# uv
uv tool install happenstance

# pipx
pipx install happenstance

# pip
pip install happenstance
```

## Quick start

```bash
# Configure your API key (get one at https://happenstance.ai/integrations/keys)
hpn config set --api-key YOUR_API_KEY

# Search your network
hpn search "CISOs interested in AI in the SF Bay Area"

# Research a specific person
hpn research "https://www.linkedin.com/in/garrytan/"

# Check your credit balance
hpn usage
```

## 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 |
| `hpn search find-more ID` | Find additional results |
| `hpn research "description"` | Research a person |
| `hpn research get ID` | Get research results |
| `hpn friends` | List your friends |
| `hpn groups` | List your groups |
| `hpn groups get ID` | Get group details |
| `hpn usage` | Show credit balance |

## Configuration

The API key can be provided in three ways (in priority order):

1. `--api-key` flag on any command
2. `HPN_API_KEY` environment variable
3. Config file at `~/.hpn/config.json` (set via `hpn config set`)

All output is JSON and can be piped to `jq` for processing.

## Documentation

Full API docs: https://developer.happenstance.ai
