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

​
플래그

FlagDescription
--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-colorANSI 컬러 출력을 비활성화합니다.
--api <url>API 기본 URL을 재정의합니다. 필요 시 /ko/api/v1 접미사가 자동으로 추가됩니다.

​
JSON 엔벨로프

--json를 사용하면, CLI는 stdout에 정확히 하나의 엔벨로프만 출력하고 그 외에는 아무것도 출력하지 않습니다. 성공: 
{
  "ok": true,
  "data": {
    /* command result */
  }
}
실패: 
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "details": null
  }
}
종료 코드:
CodeMeaning
0성공.
1런타임 오류(네트워크, API, 렌더링).
2잘못된 입력(잘못된 플래그, 읽을 수 없는 페이로드).
스크립팅을 위해 엔벨로프를 jq로 파이프하세요: youka project show $ID --json | jq '.data.state'.

​
JSON 바디 전달

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

​
비동기 작업 대기

--wait는 생성된 리소스를 대신 폴링하여 최종 상태를 반환합니다. --wait 없이 실행하면, 작업이 큐에 등록되는 즉시 명령이 반환됩니다. 
youka project create ./song.mp3 --wait --json
youka export create $ID --wait --download --output ./out.mp4
스크립트에서는 --wait와 --quiet를 함께 사용해 진행 바는 숨기면서도 JSON 결과는 계속 출력할 수 있습니다.

​
멱등성

--idempotency-key를 전달하면 쓰기 명령을 안전하게 재시도할 수 있습니다. 동일한 키를 동일한 페이로드와 함께 재사용하면, 중복을 생성하는 대신 원래 결과를 반환합니다. 
youka project create ./song.mp3 \
  --idempotency-key "import-2026-04-08-song-001" \
  --json
타임아웃 이후 에이전트가 재시도할 수 있는 상황이라면 언제든 멱등성 키를 사용하세요.

​
환경 변수

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

​
다음 단계

  • Account - API 키 저장하기
  • Projects - 첫 번째 스크립트 기반 워크플로우
  • AI agents - 에이전트 작성자를 위한 운영 규칙