Metadata-Version: 2.4
Name: happenstance
Version: 0.1.0
Summary: Happenstance CLI — search your network and research individual people
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 the [Happenstance](https://happenstance.ai) API — search your network and research individual people.

## Install

```bash
# pip
pip install happenstance

# pipx (recommended for CLI tools)
pipx install happenstance

# uv
uv tool install happenstance
```

## Quick start

```bash
# Configure your API key (get one at https://happenstance.ai/settings/api)
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 "Jane Smith, CTO at Acme Corp"

# 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
