# Довідник 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, описані в розділі [Автомати станів](https://queuety.inline0.dev/uk/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` вмикають адаптивне масштабування для того самого набору команд. Стратегії розгортання див. у розділі [Воркери](https://queuety.inline0.dev/uk/docs/features/workers), а модель допуску для адаптивних пулів — у розділі [Керування ресурсами](https://queuety.inline0.dev/uk/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>` | ID завдання (обов’язково) |

### `wp queuety retry`

Повторити спробу виконання певного завдання.

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

| Параметр | Опис |
|---|---|
| `<id>` | ID завдання, для якого потрібно повторити спробу (обов’язково) |

### `wp queuety retry-buried`

Повторити спробу виконання всіх відкладених завдань.

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

### `wp queuety bury`

Вручну перемістити завдання до відкладених.

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

| Параметр | Опис |
|---|---|
| `<id>` | ID завдання, яке потрібно перемістити до відкладених (обов’язково) |

### `wp queuety delete`

Видалити завдання.

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

| Параметр | Опис |
|---|---|
| `<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>` | 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>` | ID робочого процесу (обов’язково) |

### `wp queuety workflow approve`

Надіслати робочому процесу сигнал схвалення.

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

| Опція | Опис |
|---|---|
| `<id>` | 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>` | ID робочого процесу (обов’язково) |
| `--data=<json>` | Необов’язкові дані об’єкта JSON |
| `--signal=<name>` | Перевизначити назву сигналу відхилення (за замовчуванням: `rejected`) |

### `wp queuety workflow input`

Надіслати робочому процесу структуровані вхідні дані.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |
| `--data=<json>` | Необов’язкові дані об’єкта JSON |
| `--signal=<name>` | Перевизначити назву вхідного сигналу (за замовчуванням: `input`) |

### `wp queuety workflow artifacts`

Перелічити збережені артефакти робочого процесу.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |
| `--format=<format>` | Формат виводу: `table` (за замовчуванням) або `json` |
| `--with-content` | Додати вміст артефактів до виводу |

### `wp queuety workflow artifact`

Показати один збережений артефакт робочого процесу.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |
| `<key>` | Ключ артефакту (обов’язково) |

### `wp queuety workflow pause`

Призупинити запущений робочий процес.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |

### `wp queuety workflow resume`

Відновити призупинений робочий процес.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |

### `wp queuety workflow cancel`

Скасувати робочий процес, який ще не перебуває у стані `completed` або `cancelled`. В одній транзакції Queuety встановлює стан `cancelled`, переміщує відкладені завдання та завдання в обробці цього робочого процесу до сховища й записує `workflow_cancelled`; потім запускає компенсаційні дії та всі зареєстровані обробники очищення.

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

| Опція | Опис |
|---|---|
| `<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>` | 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>` | ID робочого процесу (обов’язково) |
| `<step>` | Індекс кроку, починаючи з 0 (обов’язково) |

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

Докладніше про те, що записується, і сценарії використання див. в [Журналі подій робочого процесу](https://queuety.inline0.dev/uk/docs/workflows/event-log).

### `wp queuety workflow rewind`

Повернути робочий процес до попереднього кроку й продовжити з наступного після нього. Стан відновлюється з журналу подій `state_after` для вказаного кроку, а наступний крок (`<step> + 1`) ставиться в чергу; сам указаний крок повторно не запускається.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |
| `<step>` | Індекс кроку для повернення, починаючи з 0 (обов’язково) |

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

Докладніше див. в [Подорожі в часі](https://queuety.inline0.dev/uk/docs/workflows/time-travel).

### `wp queuety workflow fork`

Розгалузити запущений робочий процес у незалежну копію його поточного стану. Розгалужений робочий процес отримує новий ID і виконується незалежно.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу для розгалуження (обов’язково) |

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

Докладніше див. в [Розгалуження](https://queuety.inline0.dev/uk/docs/workflows/forking).

### `wp queuety workflow export`

Експортувати повну історію виконання робочого процесу в JSON. Вона містить запис робочого процесу, завдання, події робочого процесу, записи журналу, збережені сигнали та очікування на залежності робочого процесу.

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

| Опція | Опис |
|---|---|
| `<id>` | ID робочого процесу (обов’язково) |
| `--output=<file>` | Шлях до файлу для запису JSON. За замовчуванням — стандартний вивід. |

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

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

Докладніше про структуру JSON див. у розділі [Експорт і відтворення](https://queuety.inline0.dev/uk/docs/workflows/export-replay).

### `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/uk/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>` | Фільтр за ID завдання |
| `--workflow=<id>` | Фільтр за 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` як одну команду, тому до підкоманди не можна звернутися, і виникає помилка «Забагато позиційних аргументів: purge» ([#11](https://github.com/inline0/queuety/issues/11)). Натомість видаляйте старі записи журналу з PHP:

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

## Команди вебхуків

### `wp queuety webhook add`

Зареєструвати вебхук URL для події.

```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`

Перелічити всі зареєстровані вебхуки.

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

| Опція | Опис |
|---|---|
| `--format=<format>` | Формат виводу: `table` (за замовчуванням), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Видалити вебхук за ID.

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

| Опція | Опис |
|---|---|
| `<id>` | ID вебхука для видалення (обов’язково) |