# Dokumentacja CLI

Wszystkie operacje Queuety są domyślnie dostępne przez WP-CLI w przestrzeni nazw `wp queuety`.

Zdefiniuj `QUEUETY_CLI_COMMAND` przed uruchomieniem Queuety, jeśli chcesz opublikować to samo drzewo poleceń pod innym korzeniem, na przykład `wp themequeue`.

W przypadku środowisk testowych agentów i innych integracji wirtualnego bash traktuj tę stronę jako dokumentację dla użytkowników, a mostek PHP jako kontrakt dla maszyn:

- `Queuety::cli_command_map()` udostępnia możliwy do serializacji katalog poleceń
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` przekształca przeanalizowane dane wejściowe `wp queuety ...` w znormalizowany plan wykonania, który preferuje bezpośrednie funkcje PHP

Maszyny stanów nie mają poleceń w tym drzewie; informacje o nich znajdziesz w PHP API opisanych w sekcji [Maszyny stanów](https://queuety.inline0.dev/pl/docs/state-machines).

## Polecenia zadań

### `wp queuety work`

Uruchamia proces roboczy przetwarzający zadania.

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

| Opcja | Opis |
|---|---|
| `--queue=<queue>` | Kolejki Queue(s) do przetwarzania, oddzielone przecinkami i uporządkowane według priorytetu (domyślnie: `default`) |
| `--once` | Przetwarza najwyżej jedno zadanie i kończy działanie (kończy je również od razu, jeśli nie ma zadania do pobrania) |
| `--workers=<n>` | Uruchamia N procesów roboczych (wymaga rozszerzeń `pcntl` i `posix`, podobnie jak `--min-workers` i `--max-workers`) |
| `--min-workers=<n>` | Minimalna liczba procesów roboczych w puli adaptacyjnej. Wymaga `--max-workers` |
| `--max-workers=<n>` | Maksymalna liczba procesów roboczych w puli adaptacyjnej |

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

Gdy określono wiele kolejek, proces roboczy próbuje pobierać zadania z każdej z nich w podanej kolejności. Wygrywa pierwsza kolejka z dostępnym zadaniem. `--workers` utrzymuje stały rozmiar puli. `--min-workers` i `--max-workers` włączają adaptacyjne skalowanie dla tego samego zestawu poleceń. Strategie wdrożenia opisano w sekcji [Procesy robocze](https://queuety.inline0.dev/pl/docs/features/workers), a model dopuszczania zadań dla pul adaptacyjnych w sekcji [Zarządzanie zasobami](https://queuety.inline0.dev/pl/docs/features/resource-management).

### `wp queuety flush`

Przetwarza wszystkie oczekujące zadania i kończy działanie.

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

| Opcja | Opis |
|---|---|
| `--queue=<queue>` | Kolejki Queue(s) do opróżnienia, oddzielone przecinkami i uporządkowane według priorytetu (domyślnie: `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`

Wysyła zadanie do wykonania z wiersza poleceń.

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

| Opcja | Opis |
|---|---|
| `<handler>` | Nazwa obsługi lub klasy (wymagane) |
| `--payload=<json>` | Dane JSON (domyślnie: `{}`) |
| `--queue=<queue>` | Nazwa kolejki (domyślnie: `default`) |
| `--priority=<priority>` | Poziom priorytetu 0-3 (domyślnie: `0`) |
| `--delay=<seconds>` | Opóźnienie w sekundach (domyślnie: `0`) |

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

### `wp queuety status`

Wyświetla statystyki kolejek.

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

| Opcja | Opis |
|---|---|
| `--queue=<queue>` | Filtruje według nazwy kolejki |

### `wp queuety list`

Wyświetla listę zadań.

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

| Opcja | Opis |
|---|---|
| `--queue=<queue>` | Filtruje według kolejki |
| `--status=<status>` | Filtruje według stanu (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Wyświetla pełne szczegóły zadania, w tym dane i historię dziennika.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator zadania (wymagany) |

### `wp queuety retry`

Ponawia konkretne zadanie.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator zadania do ponowienia (wymagany) |

### `wp queuety retry-buried`

Ponawia wszystkie zadania z archiwum.

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

### `wp queuety bury`

Ręcznie umieszcza zadanie w archiwum.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator zadania do umieszczenia w archiwum (wymagany) |

### `wp queuety delete`

Usuwa zadanie.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator zadania do usunięcia (wymagany) |

### `wp queuety recover`

Odzyskuje nieaktualne zadania, które utknęły w stanie `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

Usuwa ukończone zadania.

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

| Opcja | Opis |
|---|---|
| `--older-than=<days>` | Usuwa zadania starsze niż N dni (domyślnie: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Wstrzymaj kolejkę, aby procesy robocze ją pomijały.

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

| Opcja | Opis |
|---|---|
| `<queue>` | Nazwa kolejki do wstrzymania (wymagana) |

### `wp queuety resume`

Wznów wstrzymaną kolejkę.

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

| Opcja | Opis |
|---|---|
| `<queue>` | Nazwa kolejki do wznowienia (wymagana) |

### `wp queuety metrics`

Wyświetla metryki dla poszczególnych obsług.

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

| Opcja | Opis |
|---|---|
| `--minutes=<minutes>` | Okno czasowe w minutach (domyślnie: `60`) |
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

### `wp queuety discover`

Wyszukuje klasy obsługi w katalogu.

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

| Opcja | Opis |
|---|---|
| `<directory>` | Katalog do przeskanowania w poszukiwaniu klas obsługi (wymagany) |
| `<namespace>` | Prefiks przestrzeni nazw PSR-4 dla katalogu (wymagany) |
| `--register` | Faktycznie rejestruje znalezione obsługi |

## Polecenia przepływu pracy

### `wp queuety workflow status`

Wyświetla stan i postęp przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |

`status` wyświetla bieżący krok, opcjonalną nazwę kroku, metadane wersji i skrótu, tryb oczekiwania, podsumowanie artefaktów oraz obiekt `WaitInfo` JSON, gdy przepływ pracy oczekuje na sygnały lub zależności.

### `wp queuety workflow list`

Wyświetla listę przepływów pracy.

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

| Opcja | Opis |
|---|---|
| `--status=<status>` | Filtruje według stanu: `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

Polecenie zwraca najwyżej 50 przepływów pracy. Odczytuje wartość `--limit`, ale WP-CLI obecnie odrzuca tę flagę, ponieważ polecenie jej nie deklaruje ([#12](https://github.com/inline0/queuety/issues/12)); użyj `Queuety::list_workflows()`, aby ustawić inny limit.

Domyślna tabela zawiera `StepName` i `WaitMode`, dzięki czemu łatwiej przeglądać zablokowane przepływy pracy.

### `wp queuety workflow retry`

Ponów nieudany przepływ pracy od kroku, w którym wystąpił błąd.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |

### `wp queuety workflow approve`

Wysyła sygnał zatwierdzenia do przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `--data=<json>` | Opcjonalny obiekt danych JSON |
| `--signal=<name>` | Zastępuje nazwę sygnału zatwierdzenia (domyślnie: `approval`, zgodna z `wait_for_approval()`; krok `wait_for_decision()` domyślnie nasłuchuje `approved`, dlatego przekaż tam `--signal=approved`) |

### `wp queuety workflow reject`

Wysyła sygnał odrzucenia do przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `--data=<json>` | Opcjonalny obiekt danych JSON |
| `--signal=<name>` | Zastępuje nazwę sygnału odrzucenia (domyślnie: `rejected`) |

### `wp queuety workflow input`

Wysyła ustrukturyzowane dane wejściowe do przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `--data=<json>` | Opcjonalny obiekt danych JSON |
| `--signal=<name>` | Zastępuje nazwę sygnału wejściowego (domyślnie: `input`) |

### `wp queuety workflow artifacts`

Wyświetla listę zapisanych artefaktów przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `--format=<format>` | Format wyjściowy: `table` (domyślny) lub `json` |
| `--with-content` | Dołącza zawartość artefaktu do wyniku |

### `wp queuety workflow artifact`

Wyświetla jeden zapisany artefakt przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `<key>` | Klucz artefaktu (wymagany) |

### `wp queuety workflow pause`

Wstrzymuje działający przepływ pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |

### `wp queuety workflow resume`

Wznów wstrzymany przepływ pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |

### `wp queuety workflow cancel`

Anuluje przepływ pracy, który nie znajduje się już w stanie `completed` ani `cancelled`. W ramach jednej transakcji Queuety ustawia stan na `cancelled`, umieszcza oczekujące i przetwarzane zadania przepływu pracy w archiwum oraz rejestruje `workflow_cancelled`; następnie uruchamia kompensacje i każdy zarejestrowany procedurę czyszczącą.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy do anulowania (wymagany) |

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

### `wp queuety workflow timeline`

Wyświetla oś czasu zdarzeń przepływu pracy. Pokazuje wszystkie zdarzenia kroków (rozpoczęcie, zakończenie, niepowodzenie) wraz ze znacznikami czasu, obsługami i czasem trwania.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `--limit=<limit>` | Maksymalna liczba zwracanych zdarzeń (domyślnie: `100`) |
| `--offset=<offset>` | Liczba wcześniejszych zdarzeń do pominięcia (domyślnie: `0`) |
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

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

Kolumny wyjściowe: `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Wyświetla publiczny stan przepływu pracy po zakończeniu lub wznowieniu określonego kroku.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `<step>` | Indeks kroku, liczony od 0 (wymagany) |

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

Szczegóły zapisywanych danych i przypadki użycia znajdziesz w sekcji [Dziennik zdarzeń przepływu pracy](https://queuety.inline0.dev/pl/docs/workflows/event-log).

### `wp queuety workflow rewind`

Przewija przepływ pracy do wcześniejszego kroku i kontynuuje od następnego. Stan jest przywracany z dziennika zdarzeń `state_after` dla wskazanego kroku, a następny krok (`<step> + 1`) trafia do kolejki; wskazany krok nie jest uruchamiany ponownie.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy (wymagany) |
| `<step>` | Indeks kroku, do którego należy cofnąć, liczony od 0 (wymagany) |

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

Szczegółowe informacje znajdziesz w sekcji [Podróże w czasie](https://queuety.inline0.dev/pl/docs/workflows/time-travel).

### `wp queuety workflow fork`

Rozdziela działający przepływ pracy, tworząc jego niezależną kopię w bieżącym stanie. Rozdzielony przepływ pracy otrzymuje nowy identyfikator i jest wykonywany niezależnie.

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

| Opcja | Opis |
|---|---|
| `<id>` | Identyfikator przepływu pracy do rozdzielenia (wymagany) |

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

Szczegółowe informacje znajdziesz w sekcji [Rozdzielanie](https://queuety.inline0.dev/pl/docs/workflows/forking).

### `wp queuety workflow export`

Eksportuje pełną historię wykonania przepływu pracy do JSON. Zawiera wiersz przepływu pracy, zadania, zdarzenia przepływu pracy, wpisy dziennika, zapisane sygnały i oczekiwania na zależności przepływu pracy.

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

| Opcja | Opis |
|---|---|
| `<id>` | Ścieżka pliku, do którego zapisać JSON. Domyślnie: standardowe wyjście. |
| `--output=<file>` |  |

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

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

Szczegóły struktury JSON znajdziesz w sekcji [Eksport i odtwarzanie](https://queuety.inline0.dev/pl/docs/workflows/export-replay).

### `wp queuety workflow replay`

Odtwarza wyeksportowany przepływ pracy z pliku JSON. Tworzy nowy przepływ pracy z wyeksportowanym stanem, metadanymi i historyczną osią czasu.

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

| Opcja | Opis |
|---|---|
| `<file>` | Ścieżka do wyeksportowanego pliku JSON (wymagana) |

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

Szczegóły znajdziesz w [Eksportowaniu i odtwarzaniu](https://queuety.inline0.dev/pl/docs/workflows/export-replay).

## Polecenia harmonogramu

### `wp queuety schedule list`

Wyświetla listę wszystkich cyklicznych harmonogramów.

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

| Opcja | Opis |
|---|---|
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Dodaje cykliczny harmonogram.

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

| Opcja | Opis |
|---|---|
| `<handler>` | Nazwa obsługi lub klasy (wymagane) |
| `--every=<interval>` | Wyrażenie interwału (e.g, `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Wyrażenie Cron (e.g, `0 3 * * *`) |
| `--payload=<json>` | Dane JSON (domyślnie: `{}`) |
| `--queue=<queue>` | Nazwa kolejki (domyślnie: `default`) |

Należy podać `--every` lub `--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`

Usuwa harmonogram według nazwy obsługi.

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

| Opcja | Opis |
|---|---|
| `<handler>` | Nazwa obsługi do usunięcia (wymagana) |

### `wp queuety schedule run`

Ręcznie uruchamia takt harmonogramu. Dodaje do kolejki zadania ze wszystkich harmonogramów, których termin nadszedł.

```bash
wp queuety schedule run
```

## Polecenia dziennika

### `wp queuety log`

Wyszukuje wpisy dziennika.

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

| Opcja | Opis |
|---|---|
| `--job=<id>` | Filtruj według ID zadania |
| `--workflow=<id>` | Filtruj według ID przepływu pracy |
| `--handler=<name>` | Filtruj według nazwy procedury obsługi |
| `--event=<event>` | Filtruj według typu zdarzenia (`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>` | Pokaż wpisy od tej daty i godziny |
| `--limit=<n>` | Maksymalna liczba wyświetlanych wpisów (domyślnie: `50`) |
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

Filtry nie łączą się: Queuety stosuje pierwszy obecny filtr w kolejności `--job`, `--workflow`, `--handler`, `--event`, `--since`. `--job` i `--workflow` zwracają wszystkie wpisy, od najstarszego, i ignorują `--limit`. `--handler` i `--event` zwracają najnowsze wpisy jako pierwsze. Bez filtra polecenie odczytuje wpisy z ostatnich 24 godzin; to zapytanie oraz `--since` wyświetlają wpisy od najstarszego, więc `--limit` zachowuje najstarsze wpisy z tego przedziału.

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

### Czyszczenie logów

`LogCommand` definiuje podpolecenie `purge` (`wp queuety log purge --older-than=<days>`), ale WP-CLI rejestruje `wp queuety log` jako pojedyncze polecenie, przez co nie można wywołać podpolecenia i kończy się ono błędem „Too many positional arguments: purge” ([#11](https://github.com/inline0/queuety/issues/11)). Zamiast tego usuń stare wpisy logów z PHP:

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

## Polecenia webhooków

### `wp queuety webhook add`

Zarejestruj webhook URL dla zdarzenia.

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

| Opcja | Opis |
|---|---|
| `<event>` | Nazwa zdarzenia: `job.completed`, `job.failed` lub `job.buried` albo `workflow.failed` (wymagane) |
| `<url>` | URL, na który wysyłać powiadomienia metodą POST (wymagane) |

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

### `wp queuety webhook list`

Wyświetl wszystkie zarejestrowane webhooki.

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

| Opcja | Opis |
|---|---|
| `--format=<format>` | Format wyjściowy: `table` (domyślny), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Usuń webhook według ID.

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

| Opcja | Opis |
|---|---|
| `<id>` | ID webhooka do usunięcia (wymagane) |