CLI 快速上手
安装 CLI、完成鉴权，几分钟内在终端里创建你的第一个 podcast。
本指南带你从一台干净的机器走到一个生成完成的 podcast 节目。你将安装 listenhub 可执行文件，完成鉴权（交互场景用 OAuth，脚本场景用 API key），运行第一条生成命令——然后了解轮询如何工作、如何读取结果。
你需要 Node.js >= 20。CLI 仅支持 ESM，全局安装为 listenhub 可执行文件。
交互式配置（OAuth）
在自己的终端上工作时用这条路径。它通过浏览器登录，并以你的用户账户身份执行命令。
安装 CLI
npm install -g @marswave/listenhub-cli这会把 listenhub 可执行文件装到你的 PATH 上。验证一下：
listenhub --version
listenhub --help登录
listenhub auth login这会打开浏览器完成 OAuth。授权之后，CLI 会把 token 存到 ~/.config/listenhub/credentials.json（权限 0600），并打印你登录的账户。token 会自动刷新，所以每台机器只需登录一次。
随时确认会话状态：
listenhub auth status创建你的第一个 podcast
从一个主题生成一段简短的单人节目：
listenhub podcast create --query "AI agent trends in 2026" --mode quick该命令提交任务后会轮询直到节目就绪，并以 spinner 显示进度。完成后会打印 episode ID、标题和状态。
podcast create 上几个值得了解的 flag：
| Flag | 说明 |
|---|---|
--query <text> | 节目的主题或提示词。 |
--source-url <url> | 用于支撑节目的参考 URL。可重复。 |
--source-text <text> | 用于支撑节目的参考文本。可重复。 |
--mode <mode> | quick、deep 或 debate。默认 quick。 |
--lang <lang> | en、zh 或 ja。省略时根据 query 自动检测。 |
--speaker <name> | 按名称指定主播。可重复。一个主播生成单人节目，两个或更多生成多人节目。 |
--speaker-id <id> | 按 inner ID 指定主播。可重复。已知 ID 时用它代替 --speaker。 |
如果不指定主播，CLI 会根据检测到的语言挑选默认主播。要主动选声音，先列出主播列表（openapi 命名空间提供可查询的列表——见下文API key 路径），再传入 --speaker 或 --speaker-id。
读取结果
默认情况下命令会等待生成完成，因此最终输出已经反映一个完成的节目：
✓ Podcast created
ID: ep_xxx
Title: AI agent trends in 2026
Status: success随时列出最近的节目：
listenhub podcast list轮询如何工作
生成是异步的。每条创建命令都会提交任务、拿回一个 ID，然后轮询 API 直到任务进入终态。
- 间隔。 CLI 每 10 秒查询一次状态。
- 超时。
--timeout <seconds>限制等待时长。podcast create的默认值是300（5 分钟）。在任务完成前到达超时时，命令以退出码3结束——任务仍在服务端继续运行，你之后可以用 ID 取回。 - 结果。 成功时命令打印完成的节目；服务端失败时打印失败信息并以非零码退出。
要完全跳过轮询，传入 --no-wait。命令会立即返回 ID 并以 0 退出：
listenhub podcast create --query "AI agent trends in 2026" --no-wait
# ✓ Podcast submitted: ep_xxx在脚本和 CI 里，把 --no-wait 与 --json（-j）配合使用。--json 把机器可读的输出打到 stdout（错误仍在 stderr），因此可以直接管道给 jq：
ID=$(listenhub podcast create --query "Weekly recap" --no-wait -j | jq -r '.episodeId')之后按你自己的节奏轮询，或在你的任务调度器报告就绪后再取回节目。
API key 配置（脚本场景）
在服务器或 CI 上，用 API key 代替 OAuth。API key 命令位于 listenhub openapi 命名空间下，以 key 所有者的身份执行。
创建 API key
在 listenhub.ai/settings/api-keys 创建一个 key。key 以 lh_sk_ 开头。
让 key 可用
有两种方式。对于 CI 和临时环境，设置环境变量——CLI 会优先读取它：
export LISTENHUB_API_KEY="lh_sk_..."对于持久化的本地配置，则把它存到磁盘上。该命令会提示输入 key，并写入 ~/.config/listenhub/openapi.json（权限 0600）：
listenhub openapi config set-key查看当前配置（以及生效的来源）：
listenhub openapi config show挑选主播
与 OAuth 路径不同，openapi podcast create 至少需要一个 --speaker-id。列出可用的声音并复制一个 ID：
listenhub openapi speakers list --language en这会打印一张包含 Name、ID、Gender、Language 的表格。ID 列就是你传给 --speaker-id 的值。
用 API key 创建 podcast
listenhub openapi podcast create \
--query "AI agent trends in 2026" \
--speaker-id <speaker-id> \
--mode quick和 OAuth 命令一样，它提交任务并轮询到完成，结束后打印节目详情。同样支持 --no-wait、--timeout <seconds>（默认 300）和 --json。多传几次 --speaker-id 即可生成多人节目，加上 --source-url / --source-text 来支撑内容。
之后按 ID 取回某个节目：
listenhub openapi podcast get <episode-id>退出码
脚本可以基于退出码分支处理：
| 退出码 | 含义 |
|---|---|
0 | 成功 |
1 | 错误（校验、API 错误、网络故障） |
2 | 需要鉴权或鉴权无效——重新运行 listenhub auth login，或检查你的 API key |
3 | 超时——轮询在任务完成前超过了 --timeout |
估算积分
生成会消耗积分。创建之前，用你所用产品对应的 estimate-credits 命令查看成本，并用 listenhub openapi subscription 查看剩余余额。不要假设固定成本——去查询它。