@averroes/cli

Paid data APIs, billed to a balance you fund with a card. One npm package ships two front doors onto the same client core:

• averroes — the CLI
• averroes-mcp — an MCP server, for agents without a terminal

Both call the same HTTP API, so pricing, holds and settlement have exactly one implementation, on the server.

Install

npm install -g @averroes/cli

Getting started

averroes login <api-key>          # from the dashboard
averroes balance
averroes operations               # what you can call, and each ceiling
averroes operations jobs          # filter by key, title, tag or category

averroes call apollo.people_search --person-titles "VP of Engineering" \
  --q-organization-domains-list stripe.com

Calling any operation

averroes call <operation> works for every operation in the catalog. Its flags are derived from that operation's JSON Schema at runtime, so an operation added server-side is callable immediately — this package does not need upgrading to reach it.

averroes call <operation> --help  # flags, bounds, price, and what it chains to

Flag names are the schema's property names with underscores as dashes (per_page → --per-page). Array parameters repeat (--person-titles A --person-titles B), booleans are presence flags, and everything is type-checked against the schema's own bounds before anything is sent or charged.

Three flags are worth knowing:

• --dry-run prints the payload that would be sent and the ceiling it would reserve, without calling.
• --input '{...}' passes raw JSON, for a parameter this catalog has not transcribed yet or one too nested to be a flag. Explicit flags win over its keys.
• --idempotency-key <uuid> makes a re-run of the same command return the first result instead of paying again — see below.

Paying once for one call

Every paid call carries an Idempotency-Key, minted here and reused across each attempt this client makes. If a response is lost — a dropped connection, a 502, a gateway timeout — the retry arrives with the same key, and the server returns the original result rather than calling the provider a second time. When that happens the cost line says replayed from an earlier call · not charged again, so a replay is never mistaken for a fresh charge.

Three attempts, with doubling backoff. Only failures that might have been delivered are retried: a transport error, a 502/503/504, and the server's "your earlier attempt is still running" response. A refusal — not enough balance, a bad payload — is returned immediately, because repeating it cannot change it.

That covers the retries this process makes. It cannot cover a new process: re-running averroes call after a crash mints a new key and pays again. Pass your own to close that gap —

averroes call apollo.people_enrich --id 60d6bc... --idempotency-key "$RUN_ID"

— and the second run returns the first run's result, free. Keys are bound to the exact operation and input and last 24 hours; reusing one for a different request is an error rather than a silently wrong answer.

Data goes to stdout and the cost line to stderr, so averroes call ... > out.json gives you clean JSON with the price still visible.

find-people and enrich remain as aliases for the two most-used operations, and their original flag spellings still work.

MCP

Add to your agent's MCP config:

{
  "mcpServers": {
    "averroes": {
      "command": "averroes-mcp",
      "env": { "AVERROES_API_KEY": "ave_..." }
    }
  }
}

Tools are generated from the server's operation catalog, so new providers appear without upgrading this package — the same mechanism averroes call uses, from the same endpoint.

Agents get the idempotency protection above with no configuration: an agent retries without a human watching, which is precisely the caller a lost response would otherwise charge twice. A replayed result says so in the tool output, so an agent tracking its own spend does not count it again.

What a call costs

Every call reports what it charged and the balance left, on both surfaces. The max_price in averroes operations is a ceiling reserved before the price is known, not a quote — the real cost is usually well below it, and the difference is returned as soon as the call settles.

You are charged when the upstream payment settles. If a call fails without a payment settling, the reservation is returned in full.

Configuration

| Variable | Meaning | | --- | --- | | AVERROES_API_KEY | API key; overrides the config file | | AVERROES_BASE_URL | Override the API base URL. Defaults to https://api.myaverroes.com |

averroes login writes ~/.config/averroes/config.json with mode 0600. The environment always wins, so CI needs no writable home directory.