CLI
터미널에서 팟캐스트, 음성, 이미지, 음악, 비디오를 만드세요 — 대화형 사용에는 OAuth, 스크립트와 CI에는 API 키.
@marswave/listenhub-cli는 ListenHub의 공식 명령줄 인터페이스(CLI)입니다. @marswave/listenhub-sdk를 감싸서 동일한 기능 — 팟캐스트, 텍스트 음성 변환, 해설 비디오, 슬라이드, 이미지, 음악, 비디오 — 을 터미널 명령으로 제공하며, 직접 실행하거나 스크립트에 넣어 쓸 수 있습니다.
- 두 가지 인증 방식. 대화형 작업에는 OAuth 로그인, 스크립트와 CI에는 API 키를 사용합니다. 두 방식은 각각 별도의 명령 네임스페이스에 대응합니다.
- SDK 기반. 모든 명령이
@marswave/listenhub-sdk를 거치므로, CLI는 SDK의 응답 언래핑,429재시도, 에러 시맨틱을 그대로 물려받습니다. - Node.js >= 20. ESM 전용이며
listenhub바이너리로 전역 설치됩니다.
설치
npm install -g @marswave/listenhub-cli이렇게 하면 listenhub 바이너리가 PATH에 등록됩니다. 확인해 보세요:
listenhub --version
listenhub --help두 가지 인증 방식, 두 개의 네임스페이스
CLI에는 두 개의 최상위 명령 그룹이 있습니다. 다루는 제품은 같지만 인증 방식이 다르고 대상으로 하는 API 영역도 다릅니다. 자신의 인증 방식에 맞는 네임스페이스를 선택하세요.
| OAuth 로그인 | API 키 | |
|---|---|---|
| 명령 | listenhub <cmd> | listenhub openapi <cmd> |
| 설정 방법 | listenhub auth login(브라우저를 엽니다) | listenhub openapi config set-key 또는 LISTENHUB_API_KEY |
| 실행 주체 | 로그인한 사용자 | 내 계정 / 키 소유자 |
| 적합한 용도 | 대화형 사용, 계정 관리 | 스크립트, CI/CD, 자동화 |
| 자격 증명 | ~/.config/listenhub/credentials.json | ~/.config/listenhub/openapi.json 또는 환경 변수 |
두 방식 모두 동일한 기반 기능에 도달합니다. 구분의 기준은 신원과 명령이 실행되는 위치이지, 사용할 수 있는 기능의 차이가 아닙니다.
OAuth — listenhub auth login을 한 번 실행해 브라우저로 인증한 다음, 기본 명령(bare command)을 사용하세요:
listenhub auth login
listenhub podcast create --query "AI agent trends in 2026" --mode quickAPI 키 — listenhub.ai/settings/api-keys에서 키를 만들고 환경 변수로 설정한 다음(또는 openapi config set-key로 저장한 다음), openapi 네임스페이스를 사용하세요:
export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language enAPI 키는 비밀 정보로 다루세요. 환경을 직접 통제할 수 있는 서버와 CI에서는 API 키(openapi) 방식을 사용하세요. 워크스테이션에서 직접 대화형으로 작업할 때는 OAuth 로그인을 쓰면 수명이 긴 키를 디스크에 두지 않아도 됩니다.
전역 플래그
다음 플래그는 여러 명령에서 공통으로 동작합니다:
| 플래그 | 설명 |
|---|---|
--json, -j | 사람이 읽는 텍스트 대신 기계가 읽을 수 있는 JSON을 출력합니다. jq로 파이프하세요. |
--help, -h | CLI 또는 임의의 하위 명령에 대한 도움말을 표시합니다. |
생성 명령 — 비동기 생성을 시작하는 모든 명령 — 은 다음도 받습니다:
| 플래그 | 설명 |
|---|---|
--no-wait | 완료까지 폴링하지 않고 작업 ID를 즉시 반환합니다. |
--timeout <seconds> | 명령이 포기하기 전까지의 폴링 타임아웃. 기본값은 명령마다 다릅니다. |
기본적으로 생성 명령은 작업이 끝날 때까지 폴링하며 스피너로 진행 상황을 보여 줍니다. 폴링 간격은 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 키를 확인하세요) |
3 | 타임아웃 — 작업이 끝나기 전에 폴링이 --timeout을 초과했습니다 |
에러는 stderr로, 정상 출력은 stdout으로 쓰이므로 리다이렉트해도 --json 출력이 깨끗하게 유지됩니다.
크레딧 추정
생성에는 크레딧이 소비됩니다. 만들기 전에 해당하는 estimate 명령으로 비용을 확인하세요 — 예를 들어 listenhub openapi video estimate나 listenhub video estimate가 있습니다. 남은 잔액은 listenhub openapi subscription으로 확인하세요.
다음 단계
빠른 시작
설치와 인증을 마치고, 터미널에서 첫 에피소드를 만들어 보세요.
인증
OAuth 로그인과 API 키의 차이, 자격 증명이 저장되는 위치, 둘 사이를 전환하는 방법.
OAuth 명령
모든 기본 listenhub 명령: podcast, tts, music, image, video 등.
OpenAPI 명령
API 키로 동작하는, 스크립트와 CI를 위한 모든 listenhub openapi 명령.
예제
팟캐스트, 비디오, 음악, JSON 기반 스크립팅의 엔드투엔드 레시피.
JavaScript SDK
CLI가 감싸고 있는 라이브러리 — 코드에서 직접 ListenHub를 호출하고 싶을 때.