> ## 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`                  | وضع الآلة: يطبع ظرف 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. تتم إضافة اللاحقة `/ar/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
  }
}
```

رموز الخروج:

| الرمز | المعنى                                          |
| ----- | ----------------------------------------------- |
| `0`   | نجاح.                                           |
| `1`   | خطأ وقت التشغيل (الشبكة، API، العرض).           |
| `2`   | إدخال غير صالح (أعلام خاطئة، حمولة غير مقروءة). |

<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 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` لجعل أوامر الكتابة آمنة لإعادة المحاولة. إن إعادة استخدام نفس المفتاح مع نفس الحمولة يعيد النتيجة الأصلية بدلًا من إنشاء نسخة مكررة.

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

استخدم مفاتيح عدم التكرار كلما كان من الممكن أن يعيد وكيل المحاولة بعد انتهاء المهلة.

## متغيرات البيئة

| المتغير              | الغرض                                                     |
| -------------------- | --------------------------------------------------------- |
| `YOUKA_API_KEY`      | مفتاح API المستخدم عندما لا يتم تعيينه عبر `youka login`. |
| `YOUKA_API_BASE_URL` | عنوان URL أساسي بديل للـ API. يتم تجاوزه بواسطة `--api`.  |

## ما التالي

* [الحساب](/ar/cli/account) - حفظ مفتاح API الخاص بك
* [المشاريع](/ar/cli/projects) - أول سير عمل مؤتمت بالسكربتات
* [وكلاء الذكاء الاصطناعي](/ar/agents) - قواعد التشغيل لمؤلفي الوكلاء