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

# Tùy chọn toàn cục

> Các cờ có sẵn trên mọi lệnh Youka CLI

Mọi lệnh `youka` đều chấp nhận cùng một tập cờ toàn cục. Chúng kiểm soát chế độ đầu ra, cách xử lý đầu vào, hành vi chờ, và API mục tiêu.

## Flags

| Flag                      | Description                                                                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Chế độ máy: in chính xác một phong bì JSON ra stdout. Log và tiến trình bị ẩn.                                                                             |
| `--body <file\|->`        | Hợp nhất một đối tượng JSON từ tệp hoặc stdin. Các cờ CLI sẽ ghi đè những trường trùng khớp từ `--body`.                                                   |
| `--wait`                  | Thăm dò tài nguyên được tạo cho đến khi đạt trạng thái kết thúc. Thường dùng với `project create`, `project sync`, `project separate`, và `export create`. |
| `--idempotency-key <key>` | Chuyển tiếp khóa idempotency tới API trong các thao tác ghi.                                                                                               |
| `--quiet`                 | Ẩn đầu ra tiến trình không phải JSON khi dùng kèm với `--wait`.                                                                                            |
| `--no-color`              | Tắt đầu ra màu ANSI.                                                                                                                                       |
| `--api <url>`             | Ghi đè URL gốc của API. Hậu tố `/vi/api/v1` sẽ tự động được thêm vào khi cần.                                                                              |

## JSON envelope

Với `--json`, CLI sẽ ghi chính xác một phong bì ra stdout và không ghi gì khác.

Thành công:

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

Thất bại:

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

Mã thoát:

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `0`  | Thành công.                                            |
| `1`  | Lỗi khi chạy (mạng, API, hiển thị).                    |
| `2`  | Đầu vào không hợp lệ (cờ sai, payload không đọc được). |

<Tip>
  Dẫn phong bì qua `jq` để viết script: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## Truyền JSON bodies

Bất kỳ lệnh tạo hoặc cập nhật nào cũng chấp nhận `--body` cho toàn bộ request body. Hãy dùng cách này thay vì phải escape JSON lớn trên dòng lệnh.

<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}
  # Cờ CLI được ưu tiên hơn các trường trùng khớp từ --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## Chờ các tác vụ bất đồng bộ

`--wait` sẽ thăm dò tài nguyên được tạo thay bạn và trả về trạng thái cuối cùng. Nếu không dùng `--wait`, các lệnh sẽ trả về ngay khi tác vụ được đưa vào hàng đợi.

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

Trong script, hãy ghép `--wait` với `--quiet` để ẩn thanh tiến trình nhưng vẫn in ra kết quả JSON.

## Idempotency

Truyền `--idempotency-key` để các lệnh ghi an toàn khi cần thử lại. Dùng lại cùng một khóa với cùng payload sẽ trả về kết quả ban đầu thay vì tạo bản sao.

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

Hãy dùng khóa idempotency bất cứ khi nào một agent có thể thử lại sau khi bị timeout.

## Environment variables

| Variable             | Purpose                                             |
| -------------------- | --------------------------------------------------- |
| `YOUKA_API_KEY`      | Khóa API dùng khi không được đặt qua `youka login`. |
| `YOUKA_API_BASE_URL` | URL gốc API thay thế. Bị ghi đè bởi `--api`.        |

## What's next

* [Account](/vi/cli/account) - lưu khóa API của bạn
* [Projects](/vi/cli/projects) - quy trình làm việc scripted đầu tiên của bạn
* [AI agents](/vi/agents) - các quy tắc vận hành cho tác giả agent