# Reference CLI

Všechny operace Queuety jsou ve výchozím nastavení dostupné přes WP-CLI v jmenném prostoru `wp queuety`.

Chcete-li publikovat stejný strom příkazů pod jiným kořenem, například `wp themequeue`, definujte `QUEUETY_CLI_COMMAND` před spuštěním Queuety.

Pro testovací nástroje agentů a další integrace virtuálního bashe berte tuto stránku jako referenci pro uživatele a most PHP jako strojové rozhraní:

- `Queuety::cli_command_map()` zpřístupňuje serializovatelný katalog příkazů
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` převádí analyzovaný vstup `wp queuety ...` na normalizovaný plán spuštění, který upřednostňuje přímé funkce PHP

Stavové automaty v tomto stromu nemají žádné příkazy; prohlédněte si je prostřednictvím PHP API popsaného v části [Stavové automaty](https://queuety.inline0.dev/cs/docs/state-machines).

## Příkazy úloh

### `wp queuety work`

Spustí pracovníka, který zpracovává úlohy.

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

| Volba | Popis |
|---|---|
| `--queue=<queue>` | Fronty Queue(s) ke zpracování, oddělené čárkami podle pořadí priority (výchozí: `default`) |
| `--once` | Zpracuje nejvýše jednu úlohu a skončí (skončí také ihned, pokud nelze převzít žádnou úlohu) |
| `--workers=<n>` | Rozvětví se do N pracovních procesů (vyžaduje rozšíření `pcntl` a `posix`, stejně jako `--min-workers` a `--max-workers`) |
| `--min-workers=<n>` | Minimální počet pracovníků pro adaptivní fond. Vyžaduje `--max-workers` |
| `--max-workers=<n>` | Maximální počet pracovníků pro adaptivní fond |

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

Pokud zadáte více front, pracovník se je pokouší procházet v uvedeném pořadí. Vyhraje první fronta s dostupnou úlohou. `--workers` udržuje fond pevně nastavený. `--min-workers` a `--max-workers` zapínají adaptivní škálování pro stejnou sadu příkazů. Strategie nasazení najdete v části [Pracovníci](https://queuety.inline0.dev/cs/docs/features/workers) a model přijímání pro adaptivní fondy v části [Správa zdrojů](https://queuety.inline0.dev/cs/docs/features/resource-management).

### `wp queuety flush`

Zpracuje všechny čekající úlohy a skončí.

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

| Volba | Popis |
|---|---|
| `--queue=<queue>` | Fronty Queue(s), které se mají vyprázdnit, oddělené čárkami podle pořadí priority (výchozí: `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`

Odešle úlohu z příkazového řádku.

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

| Možnost | Popis |
|---|---|
| `<handler>` | Název obslužné funkce nebo třída (povinné) |
| `--payload=<json>` | JSON payload (výchozí: `{}`) |
| `--queue=<queue>` | Název fronty (výchozí: `default`) |
| `--priority=<priority>` | Úroveň priority 0–3 (výchozí: `0`) |
| `--delay=<seconds>` | Prodleva v sekundách (výchozí: `0`) |

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

### `wp queuety status`

Zobrazit statistiky front.

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

| Možnost | Popis |
|---|---|
| `--queue=<queue>` | Filtrovat podle názvu fronty |

### `wp queuety list`

Vypsat úlohy.

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

| Možnost | Popis |
|---|---|
| `--queue=<queue>` | Filtrovat podle fronty |
| `--status=<status>` | Filtrovat podle stavu (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Zobrazit úplné podrobnosti úlohy včetně payloadu a historie záznamů.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID úlohy (povinné) |

### `wp queuety retry`

Zkusit znovu konkrétní úlohu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID úlohy k opakování (povinné) |

### `wp queuety retry-buried`

Zkusit znovu všechny odložené úlohy.

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

### `wp queuety bury`

Ručně odložit úlohu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID úlohy k odložení (povinné) |

### `wp queuety delete`

Smazat úlohu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID úlohy ke smazání (povinné) |

### `wp queuety recover`

Obnovit zastaralé úlohy, které uvízly ve stavu `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

Smazat dokončené úlohy.

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

| Možnost | Popis |
|---|---|
| `--older-than=<days>` | Smazat úlohy starší než N dní (výchozí: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Pozastaví frontu, aby ji pracovní procesy přeskočily.

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

| Možnost | Popis |
|---|---|
| `<queue>` | Název fronty, kterou pozastavit (povinné) |

### `wp queuety resume`

Obnoví pozastavenou frontu.

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

| Možnost | Popis |
|---|---|
| `<queue>` | Název fronty, ve které pokračovat (povinné) |

### `wp queuety metrics`

Zobrazit metriky podle obslužné funkce.

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

| Možnost | Popis |
|---|---|
| `--minutes=<minutes>` | Časové okno v minutách (výchozí: `60`) |
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

### `wp queuety discover`

Vyhledat třídy obslužných funkcí v adresáři.

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

| Možnost | Popis |
|---|---|
| `<directory>` | Adresář, ve kterém hledat třídy obslužných funkcí (povinné) |
| `<namespace>` | Předpona jmenného prostoru PSR-4 pro adresář (povinné) |
| `--register` | Skutečně zaregistrovat nalezené obslužné funkce |

## Příkazy pro pracovní postupy

### `wp queuety workflow status`

Zobrazit stav a průběh pracovního postupu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |

`status` vypíše aktuální krok, případný název kroku, metadata verze/haše, režim čekání, přehled artefaktů a blob `WaitInfo` JSON, pokud pracovní postup právě čeká na signály nebo závislosti.

### `wp queuety workflow list`

Vypsat pracovní postupy.

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

| Možnost | Popis |
|---|---|
| `--status=<status>` | Filtrovat podle stavu: `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

Příkaz vrátí nejvýše 50 pracovních postupů. Načítá hodnotu `--limit`, ale WP-CLI tento příznak v současnosti odmítá, protože jej příkaz nedefinuje ([#12](https://github.com/inline0/queuety/issues/12)); chcete-li jiný limit, použijte `Queuety::list_workflows()`.

Výchozí tabulka obsahuje `StepName` a `WaitMode`, takže se zablokované pracovní postupy snáze kontrolují.

### `wp queuety workflow retry`

Opakuje neúspěšný pracovní postup od kroku, ve kterém selhal.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |

### `wp queuety workflow approve`

Odeslat pracovnímu postupu schvalovací signál.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `--data=<json>` | Volitelný payload objektu JSON |
| `--signal=<name>` | Přepsat název schvalovacího signálu (výchozí: `approval`, který odpovídá `wait_for_approval()`; krok `wait_for_decision()` standardně naslouchá signálu `approved`, proto mu předejte `--signal=approved`) |

### `wp queuety workflow reject`

Odeslat pracovnímu postupu zamítací signál.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `--data=<json>` | Volitelný payload objektu JSON |
| `--signal=<name>` | Přepsat název zamítacího signálu (výchozí: `rejected`) |

### `wp queuety workflow input`

Odeslat pracovnímu postupu strukturovaný vstup.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `--data=<json>` | Volitelný payload objektu JSON |
| `--signal=<name>` | Přepsat název vstupního signálu (výchozí: `input`) |

### `wp queuety workflow artifacts`

Vypsat uložené artefakty pracovního postupu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `--format=<format>` | Výstupní formát: `table` (výchozí) nebo `json` |
| `--with-content` | Zahrnout do výstupu obsah artefaktu |

### `wp queuety workflow artifact`

Zobrazit jeden uložený artefakt pracovního postupu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `<key>` | Klíč artefaktu (povinné) |

### `wp queuety workflow pause`

Pozastavit běžící pracovní postup.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |

### `wp queuety workflow resume`

Obnoví pozastavený pracovní postup.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |

### `wp queuety workflow cancel`

Zrušit pracovní postup, který již není ve stavu `completed` ani `cancelled`. V jedné transakci Queuety nastaví stav na `cancelled`, odloží čekající úlohy pracovního postupu i ty, které se právě zpracovávají, a zaznamená `workflow_cancelled`; poté spustí kompenzační akce a případnou zaregistrovanou obslužnou funkci pro úklid.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu ke zrušení (povinné) |

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

### `wp queuety workflow timeline`

Zobrazit časovou osu událostí pracovního postupu. Zobrazuje všechny události kroků (zahájení, dokončení, selhání) s časovými značkami, obslužnými funkcemi a dobou trvání.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `--limit=<limit>` | Maximální počet vrácených událostí (výchozí: `100`) |
| `--offset=<offset>` | Počet dřívějších událostí, které se mají přeskočit (výchozí: `0`) |
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

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

Sloupce výstupu: `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Zobrazit veřejný stav pracovního postupu po dokončení nebo obnovení konkrétního kroku.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `<step>` | Index kroku, od 0 (povinné) |

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

Podrobnosti o zaznamenávaných údajích a možnostech použití najdete v části [Protokol událostí pracovního postupu](https://queuety.inline0.dev/cs/docs/workflows/event-log).

### `wp queuety workflow rewind`

Vrátit pracovní postup k předchozímu kroku a pokračovat od následujícího. Stav se obnoví z protokolu událostí `state_after` pro daný krok a do fronty se zařadí následující krok (`<step> + 1`); samotný zadaný krok se znovu nespustí.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `<step>` | Index kroku, ke kterému se vrátit, od 0 (povinné) |

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

Podrobnosti najdete v části [Cestování časem](https://queuety.inline0.dev/cs/docs/workflows/time-travel).

### `wp queuety workflow fork`

Rozvětvit běžící pracovní postup do nezávislé kopie v jeho aktuálním stavu. Rozvětvený pracovní postup získá nové ID a pokračuje nezávisle.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu k rozvětvení (povinné) |

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

Podrobnosti najdete v části [Větvení](https://queuety.inline0.dev/cs/docs/workflows/forking).

### `wp queuety workflow export`

Exportovat úplnou historii provádění pracovního postupu do JSON. Zahrnuje záznam pracovního postupu, úlohy, události pracovního postupu, položky protokolu, uložené signály a čekání na závislosti pracovního postupu.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID pracovního postupu (povinné) |
| `--output=<file>` | Cesta k souboru, do kterého se zapíše JSON. Výchozí je stdout. |

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

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

Podrobnosti o struktuře JSON najdete v části [Export a přehrání](https://queuety.inline0.dev/cs/docs/workflows/export-replay).

### `wp queuety workflow replay`

Přehrát exportovaný pracovní postup ze souboru JSON. Vytvoří nový pracovní postup s exportovaným stavem, metadaty a historickou časovou osou.

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

| Možnost | Popis |
|---|---|
| `<file>` | Cesta k exportovanému souboru JSON (povinné) |

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

Podrobnosti najdete v části [Export a přehrání](https://queuety.inline0.dev/cs/docs/workflows/export-replay).

## Příkazy pro plánování

### `wp queuety schedule list`

Vypsat všechny opakující se plány.

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

| Možnost | Popis |
|---|---|
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Přidat opakující se plán.

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

| Možnost | Popis |
|---|---|
| `<handler>` | Název obslužné funkce nebo třída (povinné) |
| `--every=<interval>` | Výraz intervalu (e.g. `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Výraz Cron (e.g. `0 3 * * *`) |
| `--payload=<json>` | Payload JSON (výchozí: `{}`) |
| `--queue=<queue>` | Název fronty (výchozí: `default`) |

Je nutné zadat buď `--every`, nebo `--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`

Odebrat plán podle názvu obslužné funkce.

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

| Možnost | Popis |
|---|---|
| `<handler>` | Název obslužné funkce k odebrání (povinné) |

### `wp queuety schedule run`

Ručně spustit plánovací cyklus. Zařadí do fronty úlohy pro všechny plány, jejichž čas nastal.

```bash
wp queuety schedule run
```

## Příkazy pro protokol

### `wp queuety log`

Dotazovat se na položky protokolu.

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

| Možnost | Popis |
|---|---|
| `--job=<id>` | Filtrovat podle ID úlohy |
| `--workflow=<id>` | Filtrovat podle ID pracovního postupu |
| `--handler=<name>` | Filtrovat podle názvu obslužné funkce |
| `--event=<event>` | Filtrovat podle typu události (`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>` | Zobrazit položky od tohoto data a času |
| `--limit=<n>` | Maximální počet zobrazených položek (výchozí: `50`) |
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

Filtry se nekombinují: Queuety použije první dostupný filtr v pořadí `--job`, `--workflow`, `--handler`, `--event`, `--since`. `--job` a `--workflow` vracejí všechny položky od nejstarší a ignorují `--limit`. `--handler` a `--event` vracejí nejnovější položky jako první. Bez filtru příkaz načte posledních 24 hodin; tento dotaz i `--since` vypisují položky od nejstarší, takže `--limit` ponechá v časovém okně nejstarší položky.

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

### Mazání protokolů

`LogCommand` definuje podpříkaz `purge` (`wp queuety log purge --older-than=<days>`), ale WP-CLI registruje `wp queuety log` jako samostatný příkaz, takže podpříkaz nelze spustit a selže s chybou „Příliš mnoho pozičních argumentů: purge“ ([#11](https://github.com/inline0/queuety/issues/11)). Místo toho smažte staré položky protokolu z PHP:

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

## Příkazy pro webhooky

### `wp queuety webhook add`

Zaregistrovat webhook URL pro událost.

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

| Možnost | Popis |
|---|---|
| `<event>` | Název události: `job.completed`, `job.failed`, `job.buried` nebo `workflow.failed` (povinné) |
| `<url>` | URL, na které se mají odesílat oznámení metodou POST (povinné) |

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

### `wp queuety webhook list`

Vypsat všechny zaregistrované webhooky.

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

| Možnost | Popis |
|---|---|
| `--format=<format>` | Výstupní formát: `table` (výchozí), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Odebrat webhook podle ID.

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

| Možnost | Popis |
|---|---|
| `<id>` | ID webhooku k odebrání (povinné) |