@hdp/cli

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

Installation

npm install -g @hdp/cli

Or run directly with npx:

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.

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:

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.

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.

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

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

License

MIT