# Справочник за 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/bg/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/bg/docs/features/workers) за стратегии за внедряване и [Управление на ресурсите](https://queuety.inline0.dev/bg/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
```

Вижте [Регистър на събитията в работния поток](https://queuety.inline0.dev/bg/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
```

Вижте [Пътуване във времето](https://queuety.inline0.dev/bg/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.
```

Вижте [Разклоняване](https://queuety.inline0.dev/bg/docs/workflows/forking) за подробности.

### `wp queuety workflow export`

Експортиране на пълната история на изпълнение на работен поток в JSON. Включва реда на работния поток, задачите, събитията в работния поток, записите в регистъра, съхранените сигнали и изчакванията за зависимости на работния поток.

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

| Опция | Описание |
|---|---|
| `<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
```

Вижте [Експортиране и повторно възпроизвеждане](https://queuety.inline0.dev/bg/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/bg/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` като една команда, затова подкомандата не може да бъде достигната и връща грешка „Твърде много позиционни аргументи: 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`

Премахване на уебхук по ИД.

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

| Опция | Описание |
|---|---|
| `<id>` | ИД на уебхука за премахване (задължително) |