SDKs & CLI

ListenHub ships two official client libraries on top of the OpenAPI: a JavaScript/TypeScript SDK and a command-line tool. Both talk to the same endpoints, unwrap the standard { code, message, data } envelope for you, and handle 429 retries automatically — so you write less plumbing than calling the HTTP API directly.

Pick your tool

Install

npm i @marswave/listenhub-sdk

npm i -g @marswave/listenhub-cli

Which one should I use?

The SDK and CLI are convenience layers. Anything they do, you can also do with raw HTTP against the OpenAPI — the reference is the source of truth for every endpoint, parameter, and enum.

Two auth models

Both clients support the same two ways to authenticate. Choose based on where the code runs.

• API key — for servers, scripts, and CI. Pass the key as Authorization: Bearer $LISTENHUB_API_KEY. Create keys at listenhub.ai/settings/api-keys. In the SDK this is OpenAPIClient; in the CLI it is the listenhub openapi … command group.
• OAuth login — for interactive and user-facing use, where actions run on behalf of a signed-in account. In the SDK this is ListenHubClient; in the CLI it is listenhub auth login, which opens a browser and stores tokens under ~/.config/listenhub/.

// Server-side, API key
import { OpenAPIClient } from '@marswave/listenhub-sdk';

const client = new OpenAPIClient({ apiKey: process.env.LISTENHUB_API_KEY });
const { items: speakers } = await client.listSpeakers({ language: 'en' });

# Same thing from the terminal
export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language en --json

Error handling at a glance

Every response is wrapped in { "code": 0, "message": "", "data": { … } }. A non-zero code means an error.

• SDK — unwraps data on code 0 and throws ListenHubError (with status, code, and requestId) otherwise. On 429, it reads Retry-After and retries up to maxRetries (default 2). client.api is a ky escape hatch for endpoints the SDK does not wrap yet.
• CLI — prints errors to stderr and uses exit codes: 0 success, 1 error, 2 auth, 3 timeout. Long-running generations poll every 10s; pass --no-wait to return the ID immediately or --timeout <s> to bound the wait.

Keep reading