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

## 标志

| 标志                        | 说明                                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `--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 精确写出一个信封且不输出其他内容。

成功：

```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 | 含义                        |
| ---- | ------------------------- |
| `0`  | 成功。                       |
| `1`  | 运行时错误（网络、API、渲染）。         |
| `2`  | 输入无效（错误标志、无法读取的 payload）。 |

<Tip>
  在脚本中可用 `jq` 管道处理信封：`youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## 传递 JSON body

任何创建或更新命令都接受 `--body` 作为完整请求 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` 可让写入命令安全重试。对同一 payload 复用同一个 key 会返回原始结果，而不是创建重复项。

```bash theme={null}
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](/zh/cli/account) - 保存你的 API key
* [Projects](/zh/cli/projects) - 你的第一个脚本化工作流
* [AI agents](/zh/agents) - 面向代理作者的操作规则