認証

CLI の認証方法は 2 つあり、それぞれが 2 つのコマンドネームスペースに対応します：

• OAuth ログイン — listenhub auth login はブラウザを開いて ListenHub ユーザーとしてサインインし、更新可能なトークンを保存します。素のコマンド（listenhub podcast …、listenhub tts …）はそのユーザーとして実行されます。
• API キー — lh_sk_… で始まるキーが listenhub openapi … コマンドの認証に使われます。環境変数、または保存した設定ファイルで指定します。サーバー、スクリプト、CI 向けのモードです。

2 つのモードはそれぞれ別の認証情報ファイルを使い、互いに干渉することはありません。両方を同時に設定しておけます。

OAuth ログイン

自分が管理するマシンで対話的に作業するときは OAuth を使います。長期間有効な認証情報がスクリプトに埋め込まれることはありません — CLI は短命なアクセストークンとリフレッシュトークンを保持し、自動で更新します。

ログイン

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 は現在のトークンで API を呼び出し、まだ有効かどうかを確認します。機械可読な形式にするには --json を付けます：

listenhub auth status --json

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

ログインしていない場合、またはトークンが期限切れで使用できない場合、status はその旨を報告し、非ゼロの終了コードで終了します：

{ "loggedIn": false }

ログアウト

listenhub auth logout

これはサーバー上のリフレッシュトークンを失効させ、そのあとローカルの credentials.json を削除します：

✓ Logged out

リモートの失効呼び出しが失敗した場合（たとえばオフラインのとき）、CLI は警告を表示したうえでローカルの認証情報を削除します。いずれにせよ、そのマシンはサインアウトした状態になります。

トークンの保存と更新

credentials.json にはアクセストークン、リフレッシュトークン、expiresAt タイムスタンプが入っています。トークンを手動で更新する必要はありません — コマンドの実行中に、CLI が必要に応じてリフレッシュトークンからアクセストークンを更新します。ファイルはアトミックに（一時ファイルに書いてからリネーム）0600 権限で書き込まれます。

API キー

ブラウザフローを完了できない場所でコマンドを実行するときは API キーを使います — CI パイプライン、cron ジョブ、サーバーなどです。API キー認証は listenhub openapi … ネームスペースを動かします。

listenhub.ai/settings/api-keys でキーを作成します。キーは lh_sk_ で始まります。

キーを渡す方法は 2 つあります。環境変数は常に、保存されたファイルより優先されます。

環境変数

シェルまたは CI のシークレットに LISTENHUB_API_KEY を設定します：

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

CI/CD ではこちらを推奨します。キーはプラットフォームのシークレットストアに置き、環境変数として注入してください。ディスクには何も書き込まれません。

設定ファイルに保存する

ローカルで繰り返し使う場合は、キーを一度保存しておきます：

listenhub openapi config set-key

このコマンドはキーの入力を求め（入力は stderr に出るため、パイプした出力には混ざりません）、lh_sk_ で始まることを検証して、0600 権限で ~/.config/listenhub/openapi.json に書き込みます。そのうえでマスクした確認を表示します：

✓ API Key saved (lh_sk_***)

lh_sk_ で始まらないキーは、何も保存される前に拒否されます：

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

確認と削除

どのキーが有効で、どこから来ているかを確認します：

listenhub openapi config show

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

source は、LISTENHUB_API_KEY が設定されているときは env、キーが openapi.json から来ているときは file になります。完全なキーが表示されることはなく、マスクされた lh_sk_*** の接頭辞だけが出ます。スクリプトで扱うには --json を付けます：

listenhub openapi config show --json

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

キーが設定されていない場合、show はその旨を報告し、非ゼロで終了します。

保存したキーを削除します（削除されるのはファイルだけで、環境変数は解除されません）：

listenhub openapi config clear

✓ API Key cleared

どちらのモードを使うべきか

• 自分のマシンで対話的に作業する → OAuth ログイン。長期間有効なキーをディスクに置かずに済み、コマンドはあなたの身分で実行されます。
• スクリプト、CI/CD、サーバー → LISTENHUB_API_KEY による API キー。ブラウザなしで動作し、シークレットマネージャーに組み込めます。

2 つは独立しています。日常のターミナル作業には OAuth ログイン、CI には API キー、というのがよくある構成です — 同じマシンで両方を競合なく設定できます。

認証エラーのトラブルシューティング

CLI は 認証失敗に終了コード 2 を使うため、スクリプトは「認可されていない」を他のエラーと区別できます（1 = 一般的なエラー、3 = タイムアウト）。エラーは stderr に書き出されます。

よくあるケースと対処：

CLI が現在認識している状態を確認するには：

listenhub auth status            # OAuth session
listenhub openapi config show    # API key source (env vs file)

次のステップ