> ## 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 명령에서 사용할 수 있는 플래그

모든 `youka` 명령은 동일한 전역 플래그 세트를 지원합니다. 이 플래그들은 출력 모드, 입력 처리, 대기 동작, 그리고 대상 API를 제어합니다.

## 플래그

| Flag                      | Description                                                                                                                      |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | 머신 모드: stdout에 정확히 하나의 JSON 엔벨로프를 출력합니다. 로그와 진행 표시가 억제됩니다.                                                                       |
| `--body <file\|->`        | 파일 또는 stdin에서 JSON 객체를 병합합니다. CLI 플래그가 `--body`의 동일 필드를 덮어씁니다.                                                                   |
| `--wait`                  | 생성된 리소스가 종료 상태(terminal state)에 도달할 때까지 폴링합니다. `project create`, `project sync`, `project separate`, `export create`에서 자주 사용됩니다. |
| `--idempotency-key <key>` | 쓰기 작업 시 API로 멱등성 키를 전달합니다.                                                                                                       |
| `--quiet`                 | `--wait`와 함께 사용할 때 비-JSON 진행 출력물을 억제합니다.                                                                                         |
| `--no-color`              | ANSI 컬러 출력을 비활성화합니다.                                                                                                             |
| `--api <url>`             | API 기본 URL을 재정의합니다. 필요 시 `/ko/api/v1` 접미사가 자동으로 추가됩니다.                                                                           |

## JSON 엔벨로프

`--json`를 사용하면, CLI는 stdout에 정확히 하나의 엔벨로프만 출력하고 그 외에는 아무것도 출력하지 않습니다.

성공:

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

실패:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "details": null
  }
}
```

종료 코드:

| Code | Meaning                        |
| ---- | ------------------------------ |
| `0`  | 성공.                            |
| `1`  | 런타임 오류(네트워크, API, 렌더링).        |
| `2`  | 잘못된 입력(잘못된 플래그, 읽을 수 없는 페이로드). |

<Tip>
  스크립팅을 위해 엔벨로프를 `jq`로 파이프하세요: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## JSON 바디 전달

모든 create 또는 update 명령은 전체 요청 바디를 위해 `--body`를 지원합니다. 명령줄에서 큰 JSON을 이스케이프하는 대신 이를 사용하세요.

<CodeGroup>
  ```bash from-file theme={null}
  youka preset create --body ./preset.json --json
  ```

  ```bash from-stdin theme={null}
  cat preset.json | youka preset create --body - --json
  ```

  ```bash override-with-flag theme={null}
  # CLI flag takes priority over matching fields from --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## 비동기 작업 대기

`--wait`는 생성된 리소스를 대신 폴링하여 최종 상태를 반환합니다. `--wait` 없이 실행하면, 작업이 큐에 등록되는 즉시 명령이 반환됩니다.

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

스크립트에서는 `--wait`와 `--quiet`를 함께 사용해 진행 바는 숨기면서도 JSON 결과는 계속 출력할 수 있습니다.

## 멱등성

`--idempotency-key`를 전달하면 쓰기 명령을 안전하게 재시도할 수 있습니다. 동일한 키를 동일한 페이로드와 함께 재사용하면, 중복을 생성하는 대신 원래 결과를 반환합니다.

```bash theme={null}
youka project create ./song.mp3 \
  --idempotency-key "import-2026-04-08-song-001" \
  --json
```

타임아웃 이후 에이전트가 재시도할 수 있는 상황이라면 언제든 멱등성 키를 사용하세요.

## 환경 변수

| Variable             | Purpose                                   |
| -------------------- | ----------------------------------------- |
| `YOUKA_API_KEY`      | `youka login`으로 설정하지 않았을 때 사용되는 API 키입니다. |
| `YOUKA_API_BASE_URL` | 대체 API 기본 URL입니다. `--api`로 재정의됩니다.        |

## 다음 단계

* [Account](/ko/cli/account) - API 키 저장하기
* [Projects](/ko/cli/projects) - 첫 번째 스크립트 기반 워크플로우
* [AI agents](/ko/agents) - 에이전트 작성자를 위한 운영 규칙