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

# Youka CLI

> 명령줄에서 노래방을 만들고, 스타일을 커스터마이즈하고, MP4 비디오를 내보내기

Youka CLI는 공개 API를 감싸서, 노래로부터 노래방을 생성하고 가사와 비디오 스타일을 커스터마이즈한 뒤, 터미널이나 에이전트에서 완성된 MP4를 내보낼 수 있게 해줍니다.

## 설치

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @youka/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @youka/cli
  ```

  ```bash yarn theme={null}
  yarn global add @youka/cli
  ```
</CodeGroup>

설치 확인:

```bash theme={null}
youka --version
youka --help
```

## 인증 설정

<Steps>
  <Step title="API 키 받기">
    [online.youka.io/account](https://online.youka.io/account)로 이동해
    **API keys**를 열고 새 키를 복사하세요.
  </Step>

  <Step title="키 저장하기">
    키를 `~/.youka/config.json`에 영구 저장합니다:

    ```bash theme={null}
    youka login YOUR_API_KEY
    ```

    또는 환경 변수로 내보내세요:

    ```bash theme={null}
    export YOUKA_API_KEY=YOUR_API_KEY
    ```
  </Step>
</Steps>

## 파일로 노래방 만들기

로컬 오디오 또는 비디오 파일을 소스로 사용하세요:

```bash theme={null}
youka project create ./song.mp3 --download --output ./karaoke.mp4 --wait --json
```

이 명령은 소스를 업로드하고, 노래방 프로젝트를 생성하며, 내보내기를 렌더링한 다음, 완성된 MP4 비디오를 다운로드합니다.

## URL로 노래방 만들기

파일 경로 대신 HTTP 또는 HTTPS 소스 URL을 전달하세요:

```bash theme={null}
youka project create "https://example.com/song.mp4" --download --output ./karaoke.mp4 --wait --json
```

호스팅된 비디오 URL의 경우, Youka는 URL에서 다운로드하기 위해 `yt-dlp`를 사용합니다. 첫 URL 가져오기 전에 URL 다운로드 의존성을 설치할 수 있습니다:

```bash theme={null}
youka deps ensure --for url
```

## 레퍼런스

<Columns cols={2}>
  <Card title="Account" icon="key" href="/ko/cli/account">
    로그인/로그아웃하고 인증 상태를 확인합니다.
  </Card>

  <Card title="Credits" icon="coins" href="/ko/cli/credits">
    현재 잔액과 만료 예정 크레딧 패키지를 확인합니다.
  </Card>

  <Card title="Billing" icon="credit-card" href="/ko/cli/billing">
    가격을 표시하고 결제 또는 포털 URL을 생성합니다.
  </Card>

  <Card title="Projects" icon="folder" href="/ko/cli/projects">
    프로젝트를 생성하고, 확인하고, 완료될 때까지 대기하고, 업데이트합니다.
  </Card>

  <Card title="Exports" icon="file-video" href="/ko/cli/exports">
    클라우드 또는 로컬 내보내기 아티팩트를 렌더링하고 다운로드합니다.
  </Card>

  <Card title="Presets" icon="palette" href="/ko/cli/presets">
    재사용 가능한 렌더 설정을 관리합니다.
  </Card>

  <Card title="Media" icon="image" href="/ko/cli/media">
    재사용 가능한 미디어를 업로드하고 관리합니다.
  </Card>

  <Card title="Tasks" icon="list-check" href="/ko/cli/tasks">
    필요할 때 저수준 작업 상태를 확인합니다.
  </Card>

  <Card title="Dependencies" icon="box" href="/ko/cli/deps">
    URL 가져오기 및 로컬 렌더 의존성을 확인하고 설치합니다.
  </Card>

  <Card title="Global options" icon="gear" href="/ko/cli/global-options">
    모든 명령에서 사용 가능한 플래그입니다.
  </Card>
</Columns>

## 기본으로 에이전트 친화적

모든 명령은 안정적인 형태를 가진 단일 JSON 엔벨로프를 반환하는 기계 판독 모드를 지원합니다. 다음 플래그를 사용해 에이전트나 스크립트에서 CLI를 구동하세요:

| Flag                      | Purpose                                               |
| ------------------------- | ----------------------------------------------------- |
| `--json`                  | stdout에 정확히 하나의 JSON 엔벨로프를 출력합니다. 진행 상황과 로그는 숨겨집니다.   |
| `--body <file\|->`        | 파일 또는 stdin의 JSON 페이로드를 병합합니다. CLI 플래그가 동일 필드를 덮어씁니다. |
| `--wait`                  | 비동기 작업(프로젝트 생성, 내보내기)을 최종 상태에 도달할 때까지 폴링합니다.          |
| `--idempotency-key <key>` | 모든 쓰기 작업에 멱등성 키를 전달합니다.                               |
| `--quiet`                 | `--wait`와 함께 사용할 때 비-JSON 진행 출력 내용을 숨깁니다.             |
| `--api <url>`             | 공개 API 기본 URL을 재정의합니다.                                |

JSON 엔벨로프 형태:

```json theme={null}
{
  "ok": true,
  "data": {
    /* command result */
  }
}
```

실패 시:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Human-readable description",
    "details": {
      /* optional */
    }
  }
}
```

전체 목록은 [Global options](/ko/cli/global-options)를 참고하세요.

## 클라우드 vs 로컬 내보내기

`export create`는 기본적으로 클라우드에서 실행됩니다. `--local`을 전달하면 번들된 Remotion 툴체인을 사용해 내 컴퓨터에서 렌더링합니다. 로컬 렌더는 렌더 의존성이 필요합니다:

```bash theme={null}
youka deps ensure --for render
```

전체 워크플로는 [Exports](/ko/cli/exports)를 참고하세요.

## 다음 단계

* [Account](/ko/cli/account) - API 키 저장
* [Projects](/ko/cli/projects) - 프로젝트 생성 및 처리
* [Exports](/ko/cli/exports) - 완성된 노래방 비디오 렌더링
* [AI agents](/ko/agents) - 자동화된 워크플로에서 CLI 구동