인증

CLI는 두 가지 방식으로 인증하며, 각각 하나의 명령 네임스페이스에 대응합니다:

• OAuth 로그인 — listenhub auth login은 브라우저를 열어 ListenHub 사용자로 로그인시키고, 갱신 가능한 토큰을 저장합니다. 기본 명령(bare command, listenhub podcast …, listenhub tts …)은 해당 사용자 권한으로 실행됩니다.
• API 키 — lh_sk_…로 시작하는 키가 listenhub openapi … 명령을 인증합니다. 환경 변수 또는 저장된 설정 파일로 지정합니다. 서버, 스크립트, CI를 위한 방식입니다.

두 방식은 서로 다른 자격 증명 파일을 사용하며 절대 간섭하지 않습니다. 둘을 동시에 설정해 두어도 됩니다.

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는 그 사실을 알리고 0이 아닌 코드로 종료합니다:

{ "loggedIn": false }

로그아웃

listenhub auth logout

서버에서 리프레시 토큰을 폐기한 뒤, 로컬의 credentials.json을 삭제합니다:

✓ Logged out

원격 폐기 호출이 실패하면(예: 오프라인 상태), CLI는 경고를 출력하고 그래도 로컬 자격 증명을 지웁니다. 따라서 어느 쪽이든 그 머신은 로그아웃 상태로 남습니다.

토큰 저장과 갱신

credentials.json에는 액세스 토큰, 리프레시 토큰, expiresAt 타임스탬프가 들어 있습니다. 토큰을 직접 갱신할 필요는 없습니다 — 명령을 실행하는 동안 CLI가 필요에 따라 리프레시 토큰으로 액세스 토큰을 갱신합니다. 파일은 원자적으로(임시 파일에 쓴 뒤 이름 변경) 0600 권한으로 기록됩니다.

API 키

브라우저 플로우를 완료할 수 없는 환경에서 명령을 실행할 때 — CI 파이프라인, cron 작업, 서버 — API 키를 사용하세요. API 키 인증은 listenhub openapi … 네임스페이스를 담당합니다.

listenhub.ai/settings/api-keys에서 키를 만드세요. 키는 lh_sk_로 시작합니다.

키를 전달하는 방법은 두 가지입니다. 환경 변수가 항상 저장된 파일보다 우선합니다.

환경 변수

셸이나 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_로 시작하는지 검증한 뒤, ~/.config/listenhub/openapi.json에 0600 권한으로 기록합니다. 그다음 마스킹된 확인 메시지를 출력합니다:

✓ 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는 그 사실을 알리고 0이 아닌 코드로 종료합니다.

저장된 키를 삭제합니다(파일만 지울 뿐, 환경 변수를 해제하지는 않습니다):

listenhub openapi config clear

✓ API Key cleared

어떤 방식을 써야 하나요?

• 자기 머신에서 대화형으로 작업 → OAuth 로그인. 장기 키를 디스크에 두지 않아도 되고, 명령이 본인 권한으로 실행됩니다.
• 스크립트, CI/CD, 서버 → LISTENHUB_API_KEY를 통한 API 키. 브라우저 없이 동작하고 시크릿 매니저에 그대로 들어맞습니다.

둘은 서로 독립적입니다. 일상적인 터미널 작업에는 OAuth 로그인, CI에는 API 키를 쓰는 조합이 흔합니다 — 같은 머신에 둘 다 설정해도 충돌하지 않습니다.

인증 에러 문제 해결

CLI는 인증 실패에 종료 코드 2를 사용하므로, 스크립트가 "권한 없음"을 다른 에러와 구분할 수 있습니다(1 = 일반 에러, 3 = 타임아웃). 에러는 stderr에 기록됩니다.

흔한 사례와 해결책:

CLI가 현재 무엇을 보고 있는지 확인하려면:

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

다음 단계