# Справочник 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/ru/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/ru/docs/features/workers), а описание модели допуска для адаптивных пулов — в разделе [Управление ресурсами](https://queuety.inline0.dev/ru/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/ru/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/ru/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/ru/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/ru/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/ru/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` как отдельную команду, поэтому подкоманда недоступна и завершается ошибкой «Too many positional arguments: 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 вебхука для удаления (обязательно) |