# مرجع CLI

تتوفر جميع عمليات Queuety عبر WP-CLI ضمن مساحة الأسماء `wp queuety` افتراضيًا.

عرّف `QUEUETY_CLI_COMMAND` قبل بدء Queuety إذا أردت نشر شجرة الأوامر نفسها تحت جذر مختلف، مثل `wp themequeue`.

بالنسبة إلى أدوات الوكلاء وغيرها من تكاملات bash الافتراضية، استخدم هذه الصفحة كمرجع للبشر وجسر PHP كواجهة تعاقدية للآلة:

- يعرض `Queuety::cli_command_map()` فهرس الأوامر القابل للتسلسل
- يحوّل `Queuety::resolve_cli_command( $path, $args, $assoc_args )` مدخل `wp queuety ...` محللًا إلى خطة تنفيذ مطبّعة تفضّل دوال استدعاء PHP مباشرة

لا تحتوي آلات الحالات على أوامر في هذه الشجرة؛ افحصها عبر PHP API الموضح في [State Machines](https://queuety.inline0.dev/ar/docs/state-machines).

## أوامر المهام

### `wp queuety work`

ابدأ عاملًا يعالج المهام.

```bash
wp queuety work [--queue=<queue>] [--once] [--workers=<n>]
wp queuety work [--queue=<queue>] [--min-workers=<n>] --max-workers=<n>
```

| الخيار | الوصف |
|---|---|
| `--queue=<queue>` | Queue(s) للمعالجة، مفصولة بفواصل لترتيب الأولوية (الافتراضي: `default`) |
| `--once` | معالجة مهمة واحدة كحد أقصى ثم الخروج (ويخرج فورًا أيضًا إذا لم تتوفر مهمة للمطالبة بها) |
| `--workers=<n>` | إنشاء N من عمليات العامل (يتطلب امتدادي `pcntl` و`posix`، وكذلك `--min-workers` و`--max-workers`) |
| `--min-workers=<n>` | الحد الأدنى لعدد العمال في مجموعة قابلة للتكيّف. يتطلب `--max-workers` |
| `--max-workers=<n>` | الحد الأقصى لعدد العمال في مجموعة قابلة للتكيّف |

```bash
# Single worker on default queue
wp queuety work

# Process a specific queue
wp queuety work --queue=emails

# Process multiple queues in priority order
wp queuety work --queue=critical,default,low

# One-shot mode
wp queuety work --once

# Multi-worker mode
wp queuety work --workers=4

# Adaptive worker pool
wp queuety work --queue=providers --min-workers=2 --max-workers=6
```

عند تحديد قوائم انتظار متعددة، يحاول العامل المطالبة بمهمة من كل قائمة بالترتيب المحدد. تفوز أول قائمة انتظار تتوفر فيها مهمة. يُبقي `--workers` المجموعة ثابتة. ويتيح `--min-workers` و`--max-workers` التوسّع التكيّفي عبر واجهة الأوامر نفسها. راجع [Workers](https://queuety.inline0.dev/ar/docs/features/workers) لاستراتيجيات النشر و[Resource Management](https://queuety.inline0.dev/ar/docs/features/resource-management) لنموذج القبول الذي تستند إليه المجموعات التكيّفية.

### `wp queuety flush`

عالج كل المهام المعلّقة ثم اخرج.

```bash
wp queuety flush [--queue=<queue>]
```

| الخيار | الوصف |
|---|---|
| `--queue=<queue>` | Queue(s) المراد إفراغها، مفصولة بفواصل لترتيب الأولوية (الافتراضي: `default`) |

```bash
# Flush a single queue
wp queuety flush --queue=emails

# Flush multiple queues in priority order
wp queuety flush --queue=critical,default,low
```

### `wp queuety dispatch`

أرسل مهمة من سطر الأوامر.

```bash
wp queuety dispatch <handler> [--payload=<json>] [--queue=<queue>] [--priority=<priority>] [--delay=<seconds>]
```

| الخيار | الوصف |
|---|---|
| `<handler>` | اسم المعالج أو الصنف (مطلوب) |
| `--payload=<json>` | حمولة JSON (الافتراضي: `{}`) |
| `--queue=<queue>` | اسم قائمة الانتظار (الافتراضي: `default`) |
| `--priority=<priority>` | مستوى الأولوية 0-3 (الافتراضي: `0`) |
| `--delay=<seconds>` | التأخير بالثواني (الافتراضي: `0`) |

```bash
wp queuety dispatch send_email --payload='{"to":"user@example.com"}' --queue=emails
```

### `wp queuety status`

اعرض إحصاءات قوائم الانتظار.

```bash
wp queuety status [--queue=<queue>]
```

| الخيار | الوصف |
|---|---|
| `--queue=<queue>` | التصفية حسب اسم قائمة الانتظار |

### `wp queuety list`

اعرض المهام.

```bash
wp queuety list [--queue=<queue>] [--status=<status>] [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `--queue=<queue>` | التصفية حسب قائمة الانتظار |
| `--status=<status>` | التصفية حسب الحالة (`pending`، `processing`، `completed`، `failed`، `buried`) |
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

### `wp queuety inspect`

اعرض التفاصيل الكاملة لمهمة، بما فيها الحمولة وسجل السجلّات.

```bash
wp queuety inspect <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف المهمة (مطلوب) |

### `wp queuety retry`

أعِد محاولة مهمة محددة.

```bash
wp queuety retry <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف المهمة المطلوب إعادة محاولتها (مطلوب) |

### `wp queuety retry-buried`

أعِد محاولة جميع المهام المدفونة.

```bash
wp queuety retry-buried
```

### `wp queuety bury`

ادفن مهمة يدويًا.

```bash
wp queuety bury <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف المهمة المراد دفنها (مطلوب) |

### `wp queuety delete`

احذف مهمة.

```bash
wp queuety delete <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف المهمة المراد حذفها (مطلوب) |

### `wp queuety recover`

استعد المهام القديمة العالقة في الحالة `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

احذف المهام المكتملة.

```bash
wp queuety purge [--older-than=<days>]
```

| الخيار | الوصف |
|---|---|
| `--older-than=<days>` | احذف المهام الأقدم من N يومًا (الافتراضي: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

أوقف قائمة انتظار مؤقتًا كي يتجاوزها العاملون.

```bash
wp queuety pause <queue>
```

| الخيار | الوصف |
|---|---|
| `<queue>` | اسم قائمة الانتظار المراد إيقافها مؤقتًا (مطلوب) |

### `wp queuety resume`

استأنف قائمة انتظار متوقفة مؤقتًا.

```bash
wp queuety resume <queue>
```

| الخيار | الوصف |
|---|---|
| `<queue>` | اسم قائمة الانتظار المراد استئنافها (مطلوب) |

### `wp queuety metrics`

اعرض المقاييس لكل معالج.

```bash
wp queuety metrics [--minutes=<minutes>] [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `--minutes=<minutes>` | النافذة الزمنية بالدقائق (الافتراضي: `60`) |
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

### `wp queuety discover`

اكتشف أصناف المعالجات في دليل.

```bash
wp queuety discover <directory> <namespace> [--register]
```

| الخيار | الوصف |
|---|---|
| `<directory>` | الدليل المراد فحصه بحثًا عن أصناف المعالجات (مطلوب) |
| `<namespace>` | بادئة مساحة أسماء PSR-4 للدليل (مطلوب) |
| `--register` | سجّل المعالجات المكتشفة فعليًا |

## أوامر سير العمل

### `wp queuety workflow status`

اعرض حالة سير العمل وتقدّمه.

```bash
wp queuety workflow status <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |

يطبع `status` الخطوة الحالية واسمها الاختياري وبيانات الإصدار/التجزئة ووضع الانتظار وملخص العناصر الأثرية وكتلة `WaitInfo` JSON عند تعذّر متابعة سير العمل بسبب انتظار إشارات أو تبعيات.

### `wp queuety workflow list`

اعرض قوائم سير العمل.

```bash
wp queuety workflow list [--status=<status>] [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `--status=<status>` | التصفية حسب الحالة: `running`، `completed`، `failed`، `paused`، `waiting_for_signal`، `waiting_for_workflows`، `cancelled` |
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

يعيد الأمر 50 سير عمل كحد أقصى. يقرأ قيمة `--limit`، لكن WP-CLI يرفض هذا الخيار حاليًا لأن الأمر لا يعرّفها ([#12](https://github.com/inline0/queuety/issues/12))؛ استخدم `Queuety::list_workflows()` لتحديد حد مختلف.

يتضمن الجدول الافتراضي `StepName` و`WaitMode` لتسهيل استعراض مسارات العمل المتوقفة.

### `wp queuety workflow retry`

أعِد محاولة تدفق عمل فاشل بدءًا من الخطوة التي أخفقت.

```bash
wp queuety workflow retry <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |

### `wp queuety workflow approve`

أرسل إشارة موافقة إلى سير عمل.

```bash
wp queuety workflow approve <id> [--data=<json>] [--signal=<name>]
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `--data=<json>` | حمولة كائن JSON اختيارية |
| `--signal=<name>` | تجاوز اسم إشارة الموافقة (الافتراضي: `approval`، المطابق لـ `wait_for_approval()`؛ تستمع خطوة `wait_for_decision()` إلى `approved` افتراضيًا، لذا مرّر `--signal=approved` إليها) |

### `wp queuety workflow reject`

أرسل إشارة رفض إلى سير عمل.

```bash
wp queuety workflow reject <id> [--data=<json>] [--signal=<name>]
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `--data=<json>` | حمولة كائن JSON اختيارية |
| `--signal=<name>` | تجاوز اسم إشارة الرفض (الافتراضي: `rejected`) |

### `wp queuety workflow input`

أرسل مدخلات منظّمة إلى سير عمل.

```bash
wp queuety workflow input <id> [--data=<json>] [--signal=<name>]
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `--data=<json>` | حمولة كائن JSON اختيارية |
| `--signal=<name>` | تجاوز اسم إشارة الإدخال (الافتراضي: `input`) |

### `wp queuety workflow artifacts`

اعرض العناصر الأثرية المخزنة لسير عمل.

```bash
wp queuety workflow artifacts <id> [--format=<format>] [--with-content]
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي) أو `json` |
| `--with-content` | تضمين محتوى العناصر الأثرية في الإخراج |

### `wp queuety workflow artifact`

اعرض عنصرًا أثريًا مخزنًا واحدًا لسير عمل.

```bash
wp queuety workflow artifact <id> <key>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `<key>` | مفتاح العنصر الأثري (مطلوب) |

### `wp queuety workflow pause`

أوقف سير عمل قيد التشغيل مؤقتًا.

```bash
wp queuety workflow pause <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |

### `wp queuety workflow resume`

استأنف تدفق عمل متوقفًا مؤقتًا.

```bash
wp queuety workflow resume <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |

### `wp queuety workflow cancel`

ألغِ سير عمل ليس في الحالة `completed` أو `cancelled`. في معاملة واحدة، تضبط Queuety الحالة على `cancelled`، وتدفن المهام المعلّقة والجارية الخاصة بسير العمل وتسجّل `workflow_cancelled`؛ ثم تشغّل عمليات التعويض وأي معالج تنظيف مسجّل.

```bash
wp queuety workflow cancel <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل المراد إلغاؤه (مطلوب) |

```bash
wp queuety workflow cancel 42
```

### `wp queuety workflow timeline`

اعرض التسلسل الزمني لأحداث سير العمل. يعرض جميع أحداث الخطوات (البدء والإكمال والفشل) مع الطوابع الزمنية والمعالجات والمدد.

```bash
wp queuety workflow timeline <id> [--limit=<limit>] [--offset=<offset>] [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `--limit=<limit>` | الحد الأقصى للأحداث المعادة (الافتراضي: `100`) |
| `--offset=<offset>` | عدد الأحداث الأقدم التي يجب تخطيها (الافتراضي: `0`) |
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

```bash
wp queuety workflow timeline 42
```

أعمدة الإخراج: `ID`، `Step`، `Event`، `Handler`، `Duration_ms`، `Error`، `Created_at`.

### `wp queuety workflow state-at`

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

```bash
wp queuety workflow state-at <id> <step>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `<step>` | فهرس الخطوة، يبدأ العد من 0 (مطلوب) |

```bash
wp queuety workflow state-at 42 0
```

اطّلع على [Workflow Event Log](https://queuety.inline0.dev/ar/docs/workflows/event-log) لمعرفة تفاصيل ما يُسجّل وحالات الاستخدام.

### `wp queuety workflow rewind`

ارجع بسير العمل إلى خطوة سابقة ثم تابعه من الخطوة التالية لها. تُستعاد الحالة من سجل الأحداث `state_after` للخطوة المحددة، وتُدرج الخطوة التالية (`<step> + 1`) في قائمة الانتظار؛ ولا تُشغّل الخطوة المحددة مجددًا.

```bash
wp queuety workflow rewind <id> <step>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `<step>` | فهرس الخطوة المراد الرجوع إليها، يبدأ العد من 0 (مطلوب) |

```bash
wp queuety workflow rewind 42 1
```

اطّلع على [Time Travel](https://queuety.inline0.dev/ar/docs/workflows/time-travel) لمعرفة التفاصيل.

### `wp queuety workflow fork`

أنشئ نسخة مستقلة من سير عمل قيد التشغيل عند حالته الحالية. تحصل النسخة المتفرعة على معرّف جديد وتتابع العمل بشكل مستقل.

```bash
wp queuety workflow fork <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل المراد تفريعه (مطلوب) |

```bash
wp queuety workflow fork 42
# Success: Workflow #42 forked. New workflow ID: 43.
```

اطّلع على [Forking](https://queuety.inline0.dev/ar/docs/workflows/forking) لمعرفة التفاصيل.

### `wp queuety workflow export`

صدّر سجل التنفيذ الكامل لسير العمل إلى JSON. يشمل صف سير العمل والمهام وأحداث سير العمل وإدخالات السجلّات والإشارات المخزنة وانتظارات تبعيات سير العمل.

```bash
wp queuety workflow export <id> [--output=<file>]
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `--output=<file>` | مسار الملف الذي سيُكتب فيه JSON. الإخراج الافتراضي إلى stdout. |

```bash
# Print to stdout
wp queuety workflow export 42

# Write to a file
wp queuety workflow export 42 --output=/tmp/workflow-42.json
```

اطّلع على [Export and Replay](https://queuety.inline0.dev/ar/docs/workflows/export-replay) لمعرفة تفاصيل بنية JSON.

### `wp queuety workflow replay`

أعِد تشغيل سير عمل مُصدّر من ملف JSON. ينشئ سير عمل جديدًا بالحالة والبيانات الوصفية والتسلسل الزمني التاريخي المُصدّرة.

```bash
wp queuety workflow replay <file>
```

| الخيار | الوصف |
|---|---|
| `<file>` | مسار ملف JSON المُصدّر (مطلوب) |

```bash
wp queuety workflow replay /tmp/workflow-42.json
# Success: Workflow replayed. New workflow ID: 85.
```

راجع [التصدير وإعادة التشغيل](https://queuety.inline0.dev/ar/docs/workflows/export-replay) للاطلاع على التفاصيل.

## أوامر الجدولة

### `wp queuety schedule list`

اعرض جميع الجداول المتكررة.

```bash
wp queuety schedule list [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

### `wp queuety schedule add`

أضف جدولًا متكررًا.

```bash
wp queuety schedule add <handler> [--every=<interval>] [--cron=<expression>] [--payload=<json>] [--queue=<queue>]
```

| الخيار | الوصف |
|---|---|
| `<handler>` | اسم المعالج أو الصنف (مطلوب) |
| `--every=<interval>` | تعبير الفاصل الزمني (e.g. `1 hour`، `30 minutes`) |
| `--cron=<expression>` | تعبير Cron (e.g. `0 3 * * *`) |
| `--payload=<json>` | حمولة JSON (الافتراضي: `{}`) |
| `--queue=<queue>` | اسم قائمة الانتظار (الافتراضي: `default`) |

يجب تحديد `--every` أو `--cron`.

```bash
wp queuety schedule add cleanup_handler --every="1 hour"
wp queuety schedule add nightly_report --cron="0 3 * * *" --queue=reports
```

### `wp queuety schedule remove`

أزل جدولًا حسب اسم المعالج.

```bash
wp queuety schedule remove <handler>
```

| الخيار | الوصف |
|---|---|
| `<handler>` | اسم المعالج المراد إزالته (مطلوب) |

### `wp queuety schedule run`

شغّل نبضة المجدول يدويًا. تُدرج مهامًا لكل الجداول المستحقة.

```bash
wp queuety schedule run
```

## أوامر السجلّات

### `wp queuety log`

استعلم عن إدخالات السجلّات.

```bash
wp queuety log [--job=<id>] [--workflow=<id>] [--handler=<name>] [--event=<event>] [--since=<datetime>] [--limit=<n>] [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `--job=<id>` | التصفية حسب معرّف المهمة |
| `--workflow=<id>` | التصفية حسب معرّف سير العمل |
| `--handler=<name>` | التصفية حسب اسم المعالج |
| `--event=<event>` | التصفية حسب نوع الحدث (`started`، `completed`، `failed`، `buried`، `retried`، `workflow_started`، `workflow_completed`، `workflow_failed`، `workflow_paused`، `workflow_resumed`، `workflow_cancelled`، `workflow_rewound`، `workflow_forked`، `workflow_deadline_exceeded`، `debug`) |
| `--since=<datetime>` | عرض الإدخالات منذ هذا التاريخ والوقت |
| `--limit=<n>` | الحد الأقصى للإدخالات المعروضة (الافتراضي: `50`) |
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

لا تتحد عوامل التصفية: يطبّق Queuety أول عامل موجود حسب الترتيب `--job`، `--workflow`، `--handler`، `--event`، `--since`. يعيد `--job` و`--workflow` جميع الإدخالات من الأقدم إلى الأحدث، ويتجاهلان `--limit`. يعيد `--handler` و`--event` أحدث الإدخالات أولًا. ومن دون عامل تصفية، يستعلم الأمر عن آخر 24 ساعة؛ ويعرض هذا الاستعلام و`--since` الإدخالات من الأقدم إلى الأحدث، لذا يُبقي `--limit` أقدم الإدخالات في النافذة.

```bash
# Logs from the last 24 hours (oldest first)
wp queuety log

# Logs for a job
wp queuety log --job=42

# Failed events
wp queuety log --event=failed --limit=100

# Logs since a specific time
wp queuety log --since="2025-03-01 00:00:00"
```

### حذف السجلّات القديمة

يعرّف `LogCommand` أمرًا فرعيًا لـ `purge` (`wp queuety log purge --older-than=<days>`)، لكن WP-CLI يسجّل `wp queuety log` كأمر واحد، لذلك يتعذر الوصول إلى الأمر الفرعي ويفشل برسالة "Too many positional arguments: purge" ([#11](https://github.com/inline0/queuety/issues/11)). احذف إدخالات السجلّات القديمة من PHP بدلًا من ذلك:

```bash
wp eval 'echo Queuety\Queuety::purge_logs( 30 );'
```

## أوامر Webhook

### `wp queuety webhook add`

سجّل URL Webhook لحدث.

```bash
wp queuety webhook add <event> <url>
```

| الخيار | الوصف |
|---|---|
| `<event>` | اسم الحدث: `job.completed` أو `job.failed` أو `job.buried` أو `workflow.failed` (مطلوب) |
| `<url>` | URL لإرسال الإشعارات إليه عبر POST (مطلوب) |

```bash
wp queuety webhook add job.buried https://hooks.slack.com/services/...
```

### `wp queuety webhook list`

اعرض جميع Webhooks المسجّلة.

```bash
wp queuety webhook list [--format=<format>]
```

| الخيار | الوصف |
|---|---|
| `--format=<format>` | تنسيق الإخراج: `table` (الافتراضي)، `json`، `csv`، `yaml` |

### `wp queuety webhook remove`

أزل Webhook حسب المعرّف.

```bash
wp queuety webhook remove <id>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف Webhook المراد إزالته (مطلوب) |