> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/almyzat-alreysyh/headless/command-line-interface.md).

# واجهة سطر الأوامر (CLI)

استخدم واجهة سطر الأوامر `studio` للتحقق من الترخيص وتشغيل سيناريوهات `.pmod` المحفوظة دون فتح تطبيق سطح المكتب.

الطريقة الأكثر أمانًا لاستدعاء CLI هي عبر تنفيذ Python الذي تم تثبيت AugeLab Studio فيه:

```bash
python -m studio --help
```

إذا كان بيئتك تعرض أيضًا الأمر `studio` في الـ PATH، فيمكنك استخدامه أيضًا:

```bash
studio --help
```

## قبل أن تبدأ

تحتاج إلى:

* تثبيت AugeLab Studio.
* سيناريو محفوظ بامتداد `.pmod`.
* رمز التحقق الخاص بـ AugeLab، ما لم تكن الآلة مفَعَّلة بالفعل.
* تنفيذ Python من البيئة التي تم تثبيت `studio` فيها.

{% hint style="info" %}
استخدم مسارات مطلقة عند التشغيل من خدمات، مهام مجدولة، Docker، أو جلسات SSH. هذا يتجنب تشغيل بيئة Python خاطئة.
{% endhint %}

## الخطوة 1: العثور على Python

### Windows

إذا قمت بالتثبيت باستخدام مثبت AugeLab، فعادةً تكون بيئة Python في:

```powershell
$py = "$env:USERPROFILE\studio_venv\Scripts\python.exe"
& $py -m studio --help
```

إذا قمت بتثبيته يدويًا داخل بيئة افتراضية لمشروع، فأشر إلى تلك البيئة بدلًا من ذلك:

```powershell
$py = "C:\path\to\studio_venv\Scripts\python.exe"
& $py -m studio --help
```

إذا كان `studio` موجودًا في `PATH`، يمكنك التحقق منه مباشرةً:

```powershell
studio --help
```

### Linux

إذا قمت بالتثبيت باستخدام مثبت Linux، فعادةً تكون بيئة Python في:

```bash
PY="$HOME/studio_venv/bin/python"
"$PY" -m studio --help
```

إذا قمت بتثبيته يدويًا داخل بيئة افتراضية لمشروع، فأشر إلى تلك البيئة بدلًا من ذلك:

```bash
PY="/path/to/studio_venv/bin/python"
"$PY" -m studio --help
```

إذا كانت البيئة الافتراضية مفعلة بالفعل:

```bash
python -m studio --help
```

### Docker

داخل أمثلة Docker، شغّل شكل الوحدة:

```bash
python -m studio --help
```

## الخطوة 2: التحقق من الترخيص

شغّل هذا مرة واحدة لكل جهاز أو لكل صورة حاوية:

```powershell
& $py -m studio verify "YOUR_VERIFICATION_CODE"
```

Linux:

```bash
"$PY" -m studio verify "YOUR_VERIFICATION_CODE"
```

المخرجات المتوقعة:

```
Verification succeeded.
```

لا تقم بتضمين رموز التحقق الحقيقية في سكربتات مشتركة أو Dockerfiles أو مستودعات Git. استخدم متغيرات البيئة أو مخزن الأسرار عند أتمتة النشر.

## الخطوة 3: تشغيل السيناريو

Windows:

```powershell
& $py -m studio run "C:\path\to\scenario.pmod"
```

Linux:

```bash
"$PY" -m studio run /path/to/scenario.pmod
```

الأمر يبقي السيناريو قيد التشغيل حتى يتوقف السيناريو أو يفشل، أو تقوم بقطعه بواسطة `Ctrl+C`.

{% hint style="warning" %}
انسخ مجلد المشروع الكامل عندما يستخدم السيناريو ملفات خارجية مثل الصور، النماذج، ملفات المعايرة، أو أصول البلوكات المخصصة. احتفظ بتلك الملفات في نفس المواقع النسبية المستخدمة عند حفظ السيناريو.
{% endhint %}

## أوضاع التشغيل الشائعة

تشغيل عدد ثابت من الخطوات المكتملة:

```bash
"$PY" -m studio run scenario.pmod --step 10
```

البدء مع لوحة التحكم الوب:

```bash
"$PY" -m studio run scenario.pmod --web --address 0.0.0.0 --port 8080
```

استخدم إشراف إعادة التشغيل للتشغيل غير المراقَب:

```bash
"$PY" -m studio run scenario.pmod --on-fail restart --max-restarts 5 --restart-delay 3
```

إصدار أحداث JSON مفصولة بأسطر لأغراض الأتمتة:

```bash
"$PY" -m studio run scenario.pmod --json
```

تغيير مستوى تفصيل السجلات في وقت التشغيل:

```bash
"$PY" -m studio run scenario.pmod --verbosity 20
```

تجاهل أخطاء تحميل السيناريو فقط عندما تريد الاستمرار عن عمد مع موارد اختيارية مفقودة:

```bash
"$PY" -m studio run scenario.pmod --ignore-errors
```

{% hint style="warning" %}
لا يمكن استخدام `--step` مع `--web` في نفس الأمر.
{% endhint %}

## مرجع الأوامر

| الأمر                                                                    | الغرض                                              |
| ------------------------------------------------------------------------ | -------------------------------------------------- |
| `python -m studio --help`                                                | إظهار مساعدة CLI على المستوى الأعلى.               |
| `python -m studio verify CODE`                                           | تسجيل رمز التحقق للجهاز الحالي.                    |
| `python -m studio run scenario.pmod`                                     | تشغيل سيناريو محفوظ باستمرار.                      |
| `python -m studio run scenario.pmod --step 10`                           | تشغيل سيناريو محفوظ لعدد محدد من الخطوات المكتملة. |
| `python -m studio run scenario.pmod --web --address 0.0.0.0 --port 8080` | التشغيل مع لوحة التحكم الوب.                       |
| `python -m studio run scenario.pmod --on-fail restart --max-restarts 5`  | إعادة تشغيل المحاولات الفاشلة حتى 5 مرات.          |
| `python -m studio run scenario.pmod --json`                              | إصدار سجلات دورة الحياة والنتائج بصيغة JSON.       |

## رموز الخروج

| الرمز | المعنى                                     |
| ----- | ------------------------------------------ |
| `0`   | نجاح.                                      |
| `2`   | خطأ في استخدام الأمر.                      |
| `3`   | فشل في التحقق من الترخيص أو تحميل الترخيص. |
| `4`   | فشل في تحميل السيناريو.                    |
| `5`   | فشل وقت تشغيل السيناريو.                   |
| `6`   | تعطل غير متوقع.                            |
| `7`   | فشل في بدء لوحة التحكم الوب.               |
| `8`   | استنفاد محاولات إعادة التشغيل.             |
| `130` | تم إيقافه بواسطة المستخدم.                 |

## استكشاف الأخطاء وإصلاحها

| العرض                    | الإصلاح                                                                        |
| ------------------------ | ------------------------------------------------------------------------------ |
| `No module named studio` | استخدم تنفيذ Python من البيئة الافتراضية الخاصة بـ Studio.                     |
| أمر `studio` غير موجود   | استخدم `python -m studio` مع تنفيذ Python الصحيح.                              |
| ملف السيناريو غير موجود  | استخدم مسار `.pmod` مطلق أو شغّل من مجلد المشروع.                              |
| فشل الترخيص              | شغّل `studio verify` مرة أخرى وتأكد من رمز التحقق.                             |
| لوحة التحكم الوب لا تبدأ | غيّر `--port`، أو تحقق من جدار الحماية وتعيين منافذ الحاوية.                   |
| فشل تحميل السيناريو      | انسخ الموارد المفقودة مع ملف `.pmod`، أو أصلح مسارات البلوكات/الموارد المخصصة. |