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

## Flags

| Flag                      | Description                                                                                                                                                             |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Машинный режим: вывести ровно один JSON-конверт в stdout. Логи и индикаторы прогресса подавляются.                                                                      |
| `--body <file\|->`        | Объединить JSON-объект из файла или stdin. Флаги CLI переопределяют совпадающие поля из `--body`.                                                                       |
| `--wait`                  | Опрашивать созданный ресурс, пока он не достигнет терминального состояния. Часто используется в `project create`, `project sync`, `project separate` и `export create`. |
| `--idempotency-key <key>` | Передать ключ идемпотентности в API для операций записи.                                                                                                                |
| `--quiet`                 | Подавлять не-JSON вывод прогресса при использовании вместе с `--wait`.                                                                                                  |
| `--no-color`              | Отключить ANSI-цвета в выводе.                                                                                                                                          |
| `--api <url>`             | Переопределить базовый URL API. Суффикс `/ru/api/v1` добавляется автоматически при необходимости.                                                                       |

## JSON envelope

С `--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`  | Неверный ввод (плохие флаги, нечитаемый payload). |

<Tip>
  Пропустите конверт через `jq` для скриптинга: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## Передача JSON-тел

Любая команда создания или обновления принимает `--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 имеет приоритет над совпадающими полями из --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 возвращает исходный результат вместо создания дубликата.

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

Используйте ключи идемпотентности всякий раз, когда агент может повторить запрос после таймаута.

## Переменные окружения

| Variable             | Purpose                                                         |
| -------------------- | --------------------------------------------------------------- |
| `YOUKA_API_KEY`      | API-ключ, используемый, если он не задан через `youka login`.   |
| `YOUKA_API_BASE_URL` | Альтернативный базовый URL API. Переопределяется через `--api`. |

## Что дальше

* [Account](/ru/cli/account) - сохраните ваш API-ключ
* [Projects](/ru/cli/projects) - ваш первый автоматизированный workflow
* [AI agents](/ru/agents) - правила работы для авторов агентов