> ## Documentation Index
> Fetch the complete documentation index at: https://developer.happenstance.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and use the Happenstance CLI to search your network and research people from the terminal.

The [Happenstance CLI](https://pypi.org/project/happenstance/) (`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+.

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
    brew tap happenstance-ai/tap
    brew install happenstance
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv tool install happenstance
    ```
  </Tab>

  <Tab title="pipx">
    ```bash theme={null}
    pipx install happenstance
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install happenstance
    ```
  </Tab>
</Tabs>

## Configure

Get your API key from the [Settings](https://happenstance.ai/integrations/keys) page, then:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
# 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.

```bash theme={null}
# 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:

```bash theme={null}
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):

```bash theme={null}
hpn search find-more SEARCH_ID
```

## Research a Person

```bash theme={null}
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:

```bash theme={null}
hpn research "Jane Smith, CTO at Acme Corp" --no-wait

hpn research get RESEARCH_ID
```

## Check Credits

```bash theme={null}
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:

```bash theme={null}
# 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?

<CardGroup cols={1}>
  <Card title="Support" icon="life-ring" href="https://happenstance.ai/contact">
    Contact our support team
  </Card>
</CardGroup>