CLI
Create podcasts, speech, images, music, and video from your terminal — OAuth for interactive use, an API key for scripts and CI.
@marswave/listenhub-cli is the official command-line interface for ListenHub. It wraps @marswave/listenhub-sdk and exposes the same capabilities — podcasts, text-to-speech, explainer videos, slides, images, music, and video — as terminal commands you can run by hand or drop into a script.
- Two auth modes. OAuth login for interactive work, an API key for scripts and CI. The two map to separate command namespaces.
- Built on the SDK. Every command goes through
@marswave/listenhub-sdk, so the CLI inherits its response unwrapping,429retries, and error semantics. - Node.js >= 20. ESM-only, installed globally as the
listenhubbinary.
Install
npm install -g @marswave/listenhub-cliThis installs the listenhub binary on your PATH. Verify it:
listenhub --version
listenhub --helpTwo auth modes, two namespaces
The CLI has two top-level command groups. They cover the same products but authenticate differently and target different API surfaces. Pick the namespace that matches your auth mode.
| OAuth login | API key | |
|---|---|---|
| Commands | listenhub <cmd> | listenhub openapi <cmd> |
| Set up with | listenhub auth login (opens browser) | listenhub openapi config set-key or LISTENHUB_API_KEY |
| Acts as | The signed-in user | Your account / key owner |
| Best for | Interactive use, account management | Scripts, CI/CD, automation |
| Credentials | ~/.config/listenhub/credentials.json | ~/.config/listenhub/openapi.json or env var |
Both modes reach the same underlying capabilities. The split is about identity and where the command runs, not about which features are available.
OAuth — run listenhub auth login once to authenticate through your browser, then use the bare commands:
listenhub auth login
listenhub podcast create --query "AI agent trends in 2026" --mode quickAPI key — create a key at listenhub.ai/settings/api-keys, set it in the environment (or store it with openapi config set-key), then use the openapi namespace:
export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language enTreat API keys as secrets. Use the API-key (openapi) mode on servers and in CI, where you control the environment. For your own interactive use on a workstation, OAuth login keeps you from putting a long-lived key on disk.
Global flags
These flags work across commands:
| Flag | Description |
|---|---|
--json, -j | Print machine-readable JSON instead of human-readable text. Pipe it to jq. |
--help, -h | Show help for the CLI or any subcommand. |
Creation commands — anything that kicks off asynchronous generation — also accept:
| Flag | Description |
|---|---|
--no-wait | Return the task ID immediately instead of polling to completion. |
--timeout <seconds> | Polling timeout before the command gives up. The default varies by command. |
By default a creation command polls until the task finishes, printing progress with a spinner. Polling runs on a 10-second interval. Use --no-wait to get the ID and poll yourself — useful in scripts:
ID=$(listenhub openapi flow-speech create \
--source-text "Some article content" \
--speaker-id voice-xxx \
--no-wait -j | jq -r '.episodeId')
listenhub openapi flow-speech get "$ID" -jExit codes
The CLI exits with a distinct code per outcome, so scripts can branch on the result:
| Code | Meaning |
|---|---|
0 | Success |
1 | Error (validation, API error, network failure) |
2 | Authentication required or invalid (log in again, or check your API key) |
3 | Timeout — polling exceeded --timeout before the task finished |
Errors are written to stderr; normal output goes to stdout, so --json output stays clean when you redirect it.
Estimating credits
Generation consumes credits. Before creating, use the relevant estimate command to see the cost — for example listenhub openapi video estimate or listenhub video estimate. Check your remaining balance with listenhub openapi subscription.
Next steps
Quickstart
Install, authenticate, and create your first episode from the terminal.
Authentication
OAuth login vs. API key, where credentials live, and switching between them.
OAuth commands
Every bare listenhub command: podcast, tts, music, image, video, and more.
OpenAPI commands
Every listenhub openapi command for scripts and CI, keyed off your API key.
Examples
End-to-end recipes for podcasts, video, music, and JSON-driven scripting.
JavaScript SDK
The library the CLI wraps — for when you want to call ListenHub from code.