> ## 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

> Create karaoke, customize the style, and export MP4 videos from the command line

The Youka CLI wraps the public API so you can create karaoke from a song, customize the lyrics and video style, and export a finished MP4 from your terminal or from an agent.

## Install

<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>

Verify the install:

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

## Set up auth

<Steps>
  <Step title="Get an API key">
    Go to [online.youka.io/account](https://online.youka.io/account), open
    **API keys**, and copy a new key.
  </Step>

  <Step title="Save the key">
    Persist the key to `~/.youka/config.json`:

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

    Or export it as an environment variable:

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

## Create karaoke from a file

Use a local audio or video file as the source:

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

That uploads the source, creates the karaoke project, renders an export, and downloads the finished MP4 video.

## Create karaoke from a URL

Pass an HTTP or HTTPS source URL instead of a file path:

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

For hosted video URLs, Youka uses `yt-dlp` to download from the URL. You can install the URL download dependencies before the first URL import:

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

## Guides

<Columns cols={2}>
  <Card title="Bulk Creation" icon="layer-group" href="/en/cli/bulk-create">
    Create karaoke from a directory of files or a list of URLs in one batch.
  </Card>
</Columns>

## Reference

<Columns cols={2}>
  <Card title="Account" icon="key" href="/en/cli/account">
    Log in, log out, and inspect auth state.
  </Card>

  <Card title="Credits" icon="coins" href="/en/cli/credits">
    Inspect current balance and expiring credit packages.
  </Card>

  <Card title="Billing" icon="credit-card" href="/en/cli/billing">
    Show pricing and create checkout or portal URLs.
  </Card>

  <Card title="Projects" icon="folder" href="/en/cli/projects">
    Create, inspect, wait on, and update projects.
  </Card>

  <Card title="Exports" icon="file-video" href="/en/cli/exports">
    Render cloud or local export artifacts and download them.
  </Card>

  <Card title="Presets" icon="palette" href="/en/cli/presets">
    Manage reusable render configurations.
  </Card>

  <Card title="Media" icon="image" href="/en/cli/media">
    Upload and manage reusable media.
  </Card>

  <Card title="Tasks" icon="list-check" href="/en/cli/tasks">
    Inspect low-level task state when needed.
  </Card>

  <Card title="Dependencies" icon="box" href="/en/cli/deps">
    Inspect and install URL import and local render dependencies.
  </Card>

  <Card title="Global options" icon="gear" href="/en/cli/global-options">
    Flags available on every command.
  </Card>
</Columns>

## Agent-ready by default

Every command supports a machine-readable mode that returns a single JSON envelope with a stable shape. Use these flags to drive the CLI from agents or scripts:

| Flag                      | Purpose                                                                        |
| ------------------------- | ------------------------------------------------------------------------------ |
| `--json`                  | Print exactly one JSON envelope to stdout. Progress and logs are suppressed.   |
| `--body <file\|->`        | Merge a JSON payload from a file or stdin. CLI flags override matching fields. |
| `--wait`                  | Poll async jobs (project create, exports) until they reach a terminal state.   |
| `--idempotency-key <key>` | Pass an idempotency key to any write operation.                                |
| `--quiet`                 | Suppress non-JSON progress output when used with `--wait`.                     |
| `--api <url>`             | Override the public API base URL.                                              |

JSON envelope shape:

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

On failure:

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

See [Global options](/en/cli/global-options) for the full list.

## Cloud vs local export

`export create` runs in the cloud by default. Pass `--local` to render on your machine using the bundled Remotion toolchain. Local renders require the render dependencies:

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

See [Exports](/en/cli/exports) for the full workflow.

## What's next

* [Account](/en/cli/account) - save your API key
* [Projects](/en/cli/projects) - create and process projects
* [Exports](/en/cli/exports) - render a finished karaoke video
* [AI agents](/en/agents) - drive the CLI from an automated workflow