> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Supertone CLI로 터미널에서 음성을 생성·스트리밍·일괄 처리하고 보이스를 관리하세요 — 빠른 시작, 명령어, 레시피, 문제 해결.

<Note>
  이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/developer-tools/cli)을 함께 확인해 주세요.
</Note>

코드 없이 터미널에서 바로 텍스트를 음성으로 변환하세요. Supertone CLI는 문자열·파일·표준 입력(stdin)으로 합성하고, 스피커로 실시간 스트리밍하고, 디렉터리 전체를 일괄 처리하고, 보이스·사용량·크레딧을 관리합니다.

소스: [supertone-inc/supertone-cli](https://github.com/supertone-inc/supertone-cli).

## 빠른 시작

<Steps>
  <Step title="설치">
    ```bash theme={"dark"}
    pip install "supertone-cli[stream]"
    ```

    Python 3.12+ 필요. `[stream]` 추가 옵션은 실시간 재생을 더합니다.
  </Step>

  <Step title="API 키 설정">
    ```bash theme={"dark"}
    export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
    ```
  </Step>

  <Step title="소리 듣기">
    ```bash theme={"dark"}
    supertone tts "터미널에서 내뱉는 첫 마디." \
      --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream
    ```

    소리가 들리면 준비 완료입니다. ✅
  </Step>
</Steps>

<Note>
  애플리케이션 코드에 통합하시나요? [Python](/ko/docs/developer-tools/python) 또는 [TypeScript](/ko/docs/developer-tools/typescript) SDK를 사용하세요. AI 에이전트용은 [MCP](/ko/docs/developer-tools/mcp)를 참고하세요.
</Note>

## 설치

<Tabs>
  <Tab title="pip">
    ```bash theme={"dark"}
    pip install supertone-cli
    ```
  </Tab>

  <Tab title="스트리밍 포함">
    ```bash theme={"dark"}
    pip install "supertone-cli[stream]"
    ```
  </Tab>
</Tabs>

Python 3.12+ 필요. `[stream]` 추가 옵션은 `--stream`을 통한 시스템 스피커 실시간 재생을 활성화합니다.

## 인증

<Tabs>
  <Tab title="환경 변수">
    ```bash theme={"dark"}
    export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
    ```
  </Tab>

  <Tab title="설정 파일">
    ```bash theme={"dark"}
    supertone config init             # 대화형 설정
    supertone config set api_key Kp9mZ3xQ7v...
    ```

    `~/.config/supertone/config.toml`에 저장됩니다.
  </Tab>
</Tabs>

<Accordion title="기본값을 설정해 입력 줄이기">
  기본값을 한 번 저장해 두면 매 호출마다 해당 플래그를 생략할 수 있습니다:

  | 설정 키            | 생략 시 사용처        | 기본값             |
  | --------------- | --------------- | --------------- |
  | `api_key`       | 항상              | —               |
  | `default_voice` | `--voice` 미지정 시 | —               |
  | `default_model` | `--model` 미지정 시 | `sona_speech_2` |
  | `default_lang`  | `--lang` 미지정 시  | `ko`            |

  ```bash theme={"dark"}
  supertone config set default_voice 20160a4c5ba38967330c84
  supertone config set default_lang en
  ```
</Accordion>

## 음성 합성

```bash theme={"dark"}
# 문자열로부터
supertone tts "터미널에서 안녕하세요." --voice VOICE_ID -o output.wav

# 파일로부터
supertone tts -i input.txt -v VOICE_ID -o output.wav

# 표준 입력(stdin)으로부터 — 파이프 친화적
echo "파이프로 전달된 텍스트." | supertone tts -v VOICE_ID -o output.wav

# 저장 대신 실시간 재생 ([stream] 추가 옵션 필요)
supertone tts "이건 실시간으로 재생됩니다." -v VOICE_ID -m sona_speech_1 --stream

# 포맷·보이스 설정 조정
supertone tts "더 느리고 더 낮게." -v VOICE_ID --output-format mp3 --speed 0.9 --pitch -2

# 폴더 전체 일괄 처리 — 입력마다 오디오 파일 하나
supertone tts -i scripts/ --outdir audio/ -v VOICE_ID
```

## 보이스 관리

```bash theme={"dark"}
supertone voices list                                  # Supertone 제공 프리셋 보이스
supertone voices list --type custom                    # 내가 복제한 보이스만
supertone voices search --lang en --gender female      # 프리셋 필터링
supertone voices get VOICE_ID                         # 상세 정보
supertone voices clone --name "My Voice" --sample sample.wav
supertone voices edit VOICE_ID --name "Renamed"
supertone voices delete VOICE_ID --yes               # --yes는 확인 절차 생략
```

## 길이 예측 및 사용량 추적

`tts-predict`는 크레딧을 **소모하지 않고** 길이와 크레딧 비용을 추정합니다 — 대량 일괄 처리 전에 유용합니다.

```bash theme={"dark"}
supertone tts-predict "이건 얼마나 길까요?" -v VOICE_ID

supertone usage balance
supertone usage analytics --start 2026-04-01 --end 2026-04-30
supertone usage voices    --start 2026-04-01 --end 2026-04-30
```

## 레시피

<AccordionGroup>
  <Accordion title="스크립트 폴더를 한 번에 내레이션">
    `.txt` 파일을 한 디렉터리에 모아 한꺼번에 합성합니다:

    ```bash theme={"dark"}
    supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3
    ```
  </Accordion>

  <Accordion title="LLM 출력을 실시간으로 읽기">
    어떤 명령의 출력이든 실시간 음성으로 파이프합니다:

    ```bash theme={"dark"}
    my-llm "오늘 헤드라인 요약해줘" | supertone tts -v VOICE_ID -m sona_speech_1 --stream
    ```
  </Accordion>

  <Accordion title="jq로 커스텀 보이스 찾기">
    `--format json`은 모든 읽기 명령을 스크립트화할 수 있게 합니다:

    ```bash theme={"dark"}
    supertone voices list --type custom --format json | jq '.[].name'
    ```
  </Accordion>

  <Accordion title="일괄 처리 전 비용 추정">
    입력을 순회하며 예측 길이를 합산해 크레딧 소모 전에 가늠합니다:

    ```bash theme={"dark"}
    for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done
    ```
  </Accordion>
</AccordionGroup>

## 레퍼런스

<AccordionGroup>
  <Accordion title="지원 모델">
    `sona_speech_1`, `sona_speech_2`, `sona_speech_2_flash`, `sona_speech_2t`, `supertonic_api_1`, `supertonic_api_3`. 각 모델의 기능과 장단점은 [모델](/ko/docs/core-concepts/models)을 참고하세요.
  </Accordion>

  <Accordion title="종료 코드">
    | 코드    | 의미           |
    | ----- | ------------ |
    | `0`   | 성공           |
    | `1`   | API 오류       |
    | `2`   | 인증 오류        |
    | `3`   | 입력 검증 오류     |
    | `130` | 중단됨 (Ctrl-C) |
  </Accordion>
</AccordionGroup>

## 문제 해결

<AccordionGroup>
  <Accordion title="command not found: supertone">
    설치 디렉터리가 `PATH`에 없거나, 활성화되지 않은 가상환경에 설치된 경우입니다. 가상환경을 다시 활성화하거나, `pip install --user supertone-cli`로 재설치하고 사용자 스크립트 디렉터리를 `PATH`에 추가하세요.
  </Accordion>

  <Accordion title="인증 오류 (종료 코드 2)">
    API 키가 없거나 잘못되었습니다. `echo $SUPERTONE_API_KEY`로 확인하거나 `supertone config set api_key your-api-key`를 실행하세요. 키는 [Developer Console](https://console.supertoneapi.com)에서 발급받습니다.
  </Accordion>

  <Accordion title="--stream에서 소리가 안 남">
    실시간 재생에는 스트리밍 추가 옵션(`pip install "supertone-cli[stream]"`)과 **`sona_speech_1` 모델**이 필요합니다 — `-m sona_speech_1`을 전달하세요. 다른 모델은 *"Streaming requires sona\_speech\_1"* 오류를 내며, 그 경우 `-o output.wav`로 파일에 저장하세요.
  </Accordion>

  <Accordion title="크레딧 소진 (402)">
    잔액이 바닥나면 합성이 중단됩니다. `supertone usage balance`로 확인하고 [Developer Console](https://console.supertoneapi.com)에서 충전하세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="MCP" icon="robot" href="/ko/docs/developer-tools/mcp">
    Model Context Protocol을 통해 AI 에이전트가 Supertone를 호출하도록 합니다.
  </Card>

  <Card title="Python SDK" icon="python" href="/ko/docs/developer-tools/python">
    애플리케이션 코드를 위한 동일한 API.
  </Card>
</CardGroup>