CLI

在终端里创建 podcast、语音、图片、音乐与视频——交互场景用 OAuth，脚本与 CI 用 API key。

@marswave/listenhub-cli 是 ListenHub 的官方命令行工具。它封装了 @marswave/listenhub-sdk，把同样的能力——podcast、文本转语音、解说视频、幻灯片、图片、音乐与视频——暴露为可以手动运行、也可以放进脚本的终端命令。

两种鉴权模式。 交互场景用 OAuth 登录，脚本与 CI 用 API key，二者对应不同的命令命名空间。
基于 SDK 构建。 每个命令都经由 @marswave/listenhub-sdk，因此 CLI 继承了它的响应拆包、429 重试以及错误语义。
Node.js >= 20。 仅 ESM，全局安装为 listenhub 可执行文件。

安装

npm install -g @marswave/listenhub-cli

这会把 listenhub 可执行文件装到你的 PATH 上。验证一下：

listenhub --version
listenhub --help

两种鉴权模式，两个命名空间

CLI 有两个顶层命令组。它们覆盖相同的产品，但鉴权方式不同、面向的 API 范围也不同。根据你的鉴权模式选择对应的命名空间。

	OAuth 登录	API key
命令	`listenhub <cmd>`	`listenhub openapi <cmd>`
配置方式	`listenhub auth login`（打开浏览器）	`listenhub openapi config set-key` 或 `LISTENHUB_API_KEY`
身份	已登录的用户	你的账户 / key 所有者
适用场景	交互使用、账户管理	脚本、CI/CD、自动化
凭据	`~/.config/listenhub/credentials.json`	`~/.config/listenhub/openapi.json` 或环境变量

两种模式都能触达相同的底层能力。区别在于身份以及命令运行的位置，而非可用的功能集。

OAuth——运行一次 listenhub auth login 通过浏览器完成鉴权，之后直接使用裸命令：

listenhub auth login
listenhub podcast create --query "AI agent trends in 2026" --mode quick

API key——在 listenhub.ai/settings/api-keys 创建一个 key，在环境中设置它（或用 openapi config set-key 存储），然后使用 openapi 命名空间：

export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language en

请将 API key 视为机密。在你能掌控环境的服务器和 CI 上使用 API key（openapi）模式。在工作站上自己交互使用时，OAuth 登录可以避免把长期有效的 key 写到磁盘上。

全局参数

下列参数在各命令间通用：

参数	说明
`--json`、`-j`	输出机器可读的 JSON，而非人类可读文本。可管道传给 `jq`。
`--help`、`-h`	显示 CLI 或任一子命令的帮助。

创建类命令——任何会发起异步生成的命令——还接受：

参数	说明
`--no-wait`	立即返回任务 ID，而不轮询到完成。
`--timeout <seconds>`	放弃前的轮询超时时间。默认值因命令而异。

默认情况下，创建类命令会轮询到任务结束，并用 spinner 显示进度。轮询以 10 秒为间隔。使用 --no-wait 拿到 ID 后自行轮询——在脚本中很有用：

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" -j

退出码

CLI 针对不同结果以不同的退出码退出，方便脚本据此分支：

退出码	含义
`0`	成功
`1`	错误（校验、API 错误、网络失败）
`2`	需要鉴权或鉴权无效（重新登录，或检查 API key）
`3`	超时——轮询在任务完成前超过了 `--timeout`

错误写入 stderr，正常输出写入 stdout，因此重定向时 --json 的输出保持干净。