身份认证

CLI 提供两种认证方式，分别对应两个命令命名空间：

• OAuth 登录 —— listenhub auth login 会打开浏览器，以 ListenHub 用户身份登录，并保存一个可刷新的 token。裸命令（listenhub podcast …、listenhub tts …）以该用户身份运行。
• API key —— 以 lh_sk_… 开头的 key 为 listenhub openapi … 命令提供认证。你通过环境变量或存储的配置文件来设置它。这是服务器、脚本和 CI 场景使用的模式。

两种模式使用各自独立的凭据文件，互不干扰。你可以同时配置两者。

OAuth 登录

当你在自己控制的机器上交互式工作时，使用 OAuth。不会有长期凭据被写进脚本 —— CLI 持有一个短期访问 token 加一个刷新 token，并自动续期。

登录

listenhub auth login

这会执行一次性的浏览器流程：

✓ Logged in as Ada Lovelace

浏览器流程有 5 分钟超时。若你未在该时间窗口内完成登录，命令会以 Login timed out after 5 minutes 中止 —— 重新运行 listenhub auth login 即可。若浏览器没有自动打开，登录 URL 会打印在终端，手动打开即可。

查看状态

listenhub auth status

✓ Logged in as Ada Lovelace
  Email:      ada@example.com
  Expires at: 2026-07-01T12:00:00.000Z

status 会用当前 token 调用 API，确认它仍然有效。加上 --json 可得到机器可读形式：

listenhub auth status --json

{
  "loggedIn": true,
  "user": "Ada Lovelace",
  "email": "ada@example.com",
  "expiresAt": "2026-07-01T12:00:00.000Z"
}

若你未登录，或 token 已过期且无法使用，status 会如实报告并以非零码退出：

{ "loggedIn": false }

登出

listenhub auth logout

这会在服务器端吊销你的刷新 token，然后删除本地的 credentials.json：

✓ Logged out

如果远程吊销调用失败（例如你处于离线状态），CLI 会打印一条警告，并仍然清除本地凭据，因此无论如何机器都会处于登出状态。

Token 存储与刷新

credentials.json 保存访问 token、刷新 token 和一个 expiresAt 时间戳。你无需手动刷新 token —— 运行命令时，CLI 会按需用刷新 token 续期访问 token。该文件以原子方式写入（先写临时文件再重命名），权限为 0600。

API key

当命令运行在无法完成浏览器流程的环境时，使用 API key —— CI 流水线、定时任务、服务器。API key 认证驱动 listenhub openapi … 命名空间。

在 listenhub.ai/settings/api-keys 创建 key。key 以 lh_sk_ 开头。

提供 key 有两种方式。环境变量始终优先于存储的文件。

环境变量

在 shell 或 CI secret 中设置 LISTENHUB_API_KEY：

export LISTENHUB_API_KEY="lh_sk_your_key_here"
listenhub openapi speakers list --language en

这是 CI/CD 的推荐做法：把 key 放在平台的 secret 存储里，以环境变量形式注入。不会有任何内容写入磁盘。

存储配置

若需在本地反复使用，可一次性存储该 key：

listenhub openapi config set-key

命令会提示输入 key（输入写到 stderr，因此不会进入管道输出），校验它以 lh_sk_ 开头，并以 0600 权限写入 ~/.config/listenhub/openapi.json。随后回显一条脱敏确认：

✓ API Key saved (lh_sk_***)

不以 lh_sk_ 开头的 key 会在保存任何内容之前被拒绝：

✗ Invalid API Key format. Must start with "lh_sk_".

查看与清除

查看当前生效的 key 及其来源：

listenhub openapi config show

✓ API Key configured (source: env)
  Key ID: lh_sk_***

当设置了 LISTENHUB_API_KEY 时 source 为 env，当 key 来自 openapi.json 时为 file。完整 key 从不会被打印 —— 只显示脱敏后的 lh_sk_*** 前缀。加上 --json 便于脚本处理：

listenhub openapi config show --json

{ "source": "env", "keyId": "lh_sk_live" }

若未配置任何 key，show 会如实报告并以非零码退出。

移除存储的 key（这只清除文件，不会取消设置环境变量）：

listenhub openapi config clear

✓ API Key cleared

我该用哪种模式？

• 在自己机器上交互式工作 → OAuth 登录。避免把长期 key 留在磁盘上，且命令以你的身份运行。
• 脚本、CI/CD、服务器 → 通过 LISTENHUB_API_KEY 使用 API key。无需浏览器即可工作，且能接入 secret 管理器。

两者相互独立。常见配置是：日常终端工作用 OAuth 登录，CI 中用 API key —— 同一台机器上可同时配置两者而不冲突。

认证错误排查

CLI 使用 退出码 2 表示认证失败，因此脚本可以把「未授权」与其他错误区分开（1 = 通用错误，3 = 超时）。错误信息写到 stderr。

常见情况及修复：

确认 CLI 当前所看到的状态：

listenhub auth status            # OAuth 会话
listenhub openapi config show    # API key 来源（env 还是 file）

下一步