npm package: @humandividendprotocol/cli
Description: HDP CLI — capture AI API usage from desktop apps and terminal tools
Latest version: 0.1.0

# @hdp/cli

**HDP CLI** — capture AI API usage from terminal tools and desktop apps. Earn HDPT token rewards for every API call.

## Installation

```bash
npm install -g @hdp/cli
```

Or run directly with npx:

```bash
npx @hdp/cli proxy
```

## Commands

### `hdp proxy`

Start a local capture proxy that intercepts AI API calls and submits compute receipts to the HDP Desktop App.

```bash
hdp proxy
```

The proxy listens on `127.0.0.1:19877` and forwards requests to the real AI provider while transparently capturing token usage from responses.

**How it works:**

```
Your App → HDP Proxy (:19877) → AI API (Anthropic, OpenAI, Google, etc.)
                │
          Extract token usage
                │
          Submit receipt → HDP Desktop App (:19876)
```

Point your AI SDK at the proxy:

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:19877
export OPENAI_BASE_URL=http://127.0.0.1:19877

# Now any AI API call goes through the capture proxy
python my_script.py
```

**Options:**

| Flag | Default | Description |
|------|---------|-------------|
| `-p, --port <port>` | `19877` | Proxy listen port |
| `--provider <name>` | auto-detect | Force a provider: `anthropic`, `openai`, `google`, `mistral`, `xai` |
| `--ipc-url <url>` | `http://127.0.0.1:19876` | Desktop App IPC address |
| `-q, --quiet` | off | Suppress per-request logging |
| `-f, --force` | off | Start even if Desktop App proxy is already running |

**Desktop App detection:** If the HDP Desktop App is already running with its embedded proxy on `:19877`, `hdp proxy` exits gracefully (unless `--force` is passed). No duplicate proxies.

### `hdp wrap`

Wrap a command to capture its AI API usage. Sets `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` automatically.

```bash
hdp wrap -- python my_ai_script.py
hdp wrap -- node bot.js
hdp wrap -- curl https://api.anthropic.com/v1/messages ...
```

This starts a temporary proxy, runs your command with the right environment variables, and shuts down when the command exits.

If the Desktop App proxy is already running, `hdp wrap` piggybacks on it instead of starting a new one.

**Options:**

| Flag | Default | Description |
|------|---------|-------------|
| `-p, --port <port>` | `19877` | Proxy port |
| `--ipc-url <url>` | `http://127.0.0.1:19876` | Desktop App IPC address |
| `-q, --quiet` | off | Suppress proxy logging |

### `hdp status`

Check HDP Desktop App status, proxy health, and capture statistics.

```bash
hdp status
```

Example output:

```
HDP Desktop App: RUNNING
  Capture Proxy:   Running on :19877
  Shell Capture:   Active (HDP_TRACKING=1)

  Active:          Yes
  Total tokens:    12,450
  Compute units:   8,200
  Receipts:        2 pending, 15 submitted
  Proof score:     35/100
  Reward mult:     1.00x
  Session:         45m 12s
```

## Supported Providers

The proxy auto-detects the AI provider from the request path:

| Provider | Path Pattern | Real Host |
|----------|-------------|-----------|
| **Anthropic** | `/v1/messages`, `/v1/complete` | `api.anthropic.com` |
| **OpenAI** | `/v1/chat/completions` | `api.openai.com` |
| **Google** | `/models/*/generateContent` | `generativelanguage.googleapis.com` |
| **Mistral** | `/v1/chat/completions` | `api.mistral.ai` |
| **xAI** | `/v1/chat/completions` | `api.x.ai` |

Both JSON and SSE (streaming) responses are supported. Token usage is extracted from the response body after forwarding the complete response to the client.

## Shell Integration

The HDP Desktop App can automatically configure your shell so all AI API calls are captured without needing `hdp proxy` or `hdp wrap`. It writes to `~/.hdp/shell-integration.sh` and sources it from your `.zshrc` / `.bashrc`.

When shell integration is active, `hdp status` shows `Shell Capture: Active (HDP_TRACKING=1)`.

## Reward Tier

CLI receipts are scored as **Provider tier (1.0x multiplier)** — the highest reward tier, since the Desktop App builds full hardware-attested compute receipts from the lightweight usage records the CLI submits.

## Prerequisites

The HDP Desktop App must be running for receipts to be processed. The CLI sends lightweight usage records (`{ provider, input_tokens, output_tokens, latency_ms }`) to the Desktop App's local IPC server, which builds full compute receipts with hardware attestation.

## Development

```bash
npm install
npm run build     # Build to dist/
npm run dev       # Watch mode
npm test          # Run 18 tests
```

## License

MIT