Skip to main content
每个 youka 命令都接受同一组全局标志。它们用于控制输出模式、输入处理、等待行为以及目标 API。

​
标志

标志说明
--json机器模式：向 stdout 精确输出一个 JSON 信封。日志与进度信息会被抑制。
--body <file|->从文件或 stdin 合并一个 JSON 对象。CLI 标志会覆盖 --body 中同名字段。
--wait轮询已创建的资源，直到其到达终止状态。常用于 project create、project sync、project separate 和 export create。
--idempotency-key <key>在写入操作中向 API 传递一个幂等键。
--quiet与 --wait 搭配使用时，抑制非 JSON 的进度输出。
--no-color禁用 ANSI 彩色输出。
--api <url>覆盖 API 基础 URL。需要时会自动追加 /zh/api/v1 后缀。

​
JSON 信封

使用 --json 时，CLI 会向 stdout 精确写出一个信封且不输出其他内容。 成功： 
{
  "ok": true,
  "data": {
    /* command result */
  }
}
失败： 
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "details": null
  }
}
退出码：
Code含义
0成功。
1运行时错误（网络、API、渲染）。
2输入无效（错误标志、无法读取的 payload）。
在脚本中可用 jq 管道处理信封：youka project show $ID --json | jq '.data.state'.

​
传递 JSON body

任何创建或更新命令都接受 --body 作为完整请求 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 可让写入命令安全重试。对同一 payload 复用同一个 key 会返回原始结果，而不是创建重复项。 
youka project create ./song.mp3 \
  --idempotency-key "import-2026-04-08-song-001" \
  --json
只要代理可能在超时后重试，就应使用幂等键。

​
环境变量

Variable用途
YOUKA_API_KEY未通过 youka login 设置时使用的 API key。
YOUKA_API_BASE_URL备用 API 基础 URL。会被 --api 覆盖。

​
接下来

  • Account - 保存你的 API key
  • Projects - 你的第一个脚本化工作流
  • AI agents - 面向代理作者的操作规则