# CLI Referenz

Alle Queuety-Operationen sind standardmäßig über WP-CLI im Namespace `wp queuety` verfügbar.

Definiere `QUEUETY_CLI_COMMAND`, bevor Queuety gestartet wird, wenn du denselben Befehlsbaum unter einem anderen Root wie `wp themequeue` veröffentlichen möchtest.

Für Agenten-Harnesses und andere Virtual-Bash-Integrationen dient diese Seite als Referenz für Menschen und die PHP-Bridge als maschinenlesbarer Vertrag:

- `Queuety::cli_command_map()` stellt den serialisierbaren Befehlskatalog bereit
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` wandelt geparste `wp queuety ...`-Eingaben in einen normalisierten Ausführungsplan um, der direkte PHP-Aufrufobjekte bevorzugt

State Machines haben in diesem Baum keine Befehle. Sie lassen sich über den PHP-API untersuchen, der unter [State Machines](https://queuety.inline0.dev/de/docs/state-machines) beschrieben ist.

## Job-Befehle

### `wp queuety work`

Startet einen Worker, der Jobs verarbeitet.

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

| Option | Beschreibung |
|---|---|
| `--queue=<queue>` | Queue(s) zur Verarbeitung; durch Kommas getrennt, in Prioritätsreihenfolge (Standard: `default`) |
| `--once` | Verarbeitet höchstens einen Job und beendet sich (auch sofort, wenn kein Job beansprucht werden kann) |
| `--workers=<n>` | Startet N Worker-Prozesse (erfordert die Erweiterungen `pcntl` und `posix`, ebenso wie `--min-workers` und `--max-workers`) |
| `--min-workers=<n>` | Mindestanzahl an Workern für einen adaptiven Pool. Erfordert `--max-workers` |
| `--max-workers=<n>` | Höchstanzahl an Workern für einen adaptiven Pool |

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

Wenn mehrere Queues angegeben sind, versucht der Worker, Jobs in der angegebenen Reihenfolge aus jeder Queue zu beanspruchen. Die erste Queue mit einem verfügbaren Job gewinnt. `--workers` hält den Pool unverändert. `--min-workers` und `--max-workers` aktivieren die adaptive Skalierung für dieselbe Befehlsoberfläche. Bereitstellungsstrategien findest du unter [Workers](https://queuety.inline0.dev/de/docs/features/workers) und das Zulassungsmodell für adaptive Pools unter [Resource Management](https://queuety.inline0.dev/de/docs/features/resource-management).

### `wp queuety flush`

Verarbeitet alle ausstehenden Jobs und beendet sich.

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

| Option | Beschreibung |
|---|---|
| `--queue=<queue>` | Queue(s) zum Leeren; durch Kommas getrennt, in Prioritätsreihenfolge (Standard: `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`

Stellt einen Job über die Kommandozeile ein.

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

| Option | Beschreibung |
|---|---|
| `<handler>` | Handlername oder -klasse (erforderlich) |
| `--payload=<json>` | JSON-Payload (Standard: `{}`) |
| `--queue=<queue>` | Queue-Name (Standard: `default`) |
| `--priority=<priority>` | Prioritätsstufe 0–3 (Standard: `0`) |
| `--delay=<seconds>` | Verzögerung in Sekunden (Standard: `0`) |

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

### `wp queuety status`

Zeigt Queue-Statistiken an.

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

| Option | Beschreibung |
|---|---|
| `--queue=<queue>` | Nach Queue-Namen filtern |

### `wp queuety list`

Listet Jobs auf.

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

| Option | Beschreibung |
|---|---|
| `--queue=<queue>` | Nach Queue filtern |
| `--status=<status>` | Nach Status filtern (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Zeigt alle Details eines Jobs an, einschließlich Payload und Protokollverlauf.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Job-ID (erforderlich) |

### `wp queuety retry`

Versucht einen bestimmten Job erneut.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Job-ID für den erneuten Versuch (erforderlich) |

### `wp queuety retry-buried`

Versucht alle vergrabenen Jobs erneut.

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

### `wp queuety bury`

Vergräbt einen Job manuell.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Job-ID zum Vergraben (erforderlich) |

### `wp queuety delete`

Löscht einen Job.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Job-ID zum Löschen (erforderlich) |

### `wp queuety recover`

Stellt veraltete Jobs wieder her, die im Status `processing` feststecken.

```bash
wp queuety recover
```

### `wp queuety purge`

Löscht abgeschlossene Jobs.

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

| Option | Beschreibung |
|---|---|
| `--older-than=<days>` | Löscht Jobs, die älter als N Tage sind (Standard: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Eine Warteschlange pausieren, damit Worker sie überspringen.

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

| Option | Beschreibung |
|---|---|
| `<queue>` | Name der zu pausierenden Queue (erforderlich) |

### `wp queuety resume`

Eine pausierte Warteschlange fortsetzen.

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

| Option | Beschreibung |
|---|---|
| `<queue>` | Name der fortzusetzenden Queue (erforderlich) |

### `wp queuety metrics`

Zeigt handlerbezogene Metriken an.

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

| Option | Beschreibung |
|---|---|
| `--minutes=<minutes>` | Zeitfenster in Minuten (Standard: `60`) |
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

### `wp queuety discover`

Ermittelt Handlerklassen in einem Verzeichnis.

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

| Option | Beschreibung |
|---|---|
| `<directory>` | Zu durchsuchendes Verzeichnis für Handlerklassen (erforderlich) |
| `<namespace>` | PSR-4-Namespace-Präfix für das Verzeichnis (erforderlich) |
| `--register` | Registriert die gefundenen Handler tatsächlich |

## Workflow-Befehle

### `wp queuety workflow status`

Zeigt Workflow-Status und Fortschritt an.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |

`status` gibt den aktuellen Schritt, einen optionalen Schrittnamen, Versions-/Hash-Metadaten, den Wartemodus und eine Artefaktübersicht aus. Wenn der Workflow aktuell auf Signale oder Abhängigkeiten wartet, wird außerdem ein `WaitInfo`-JSON-Blob ausgegeben.

### `wp queuety workflow list`

Listet Workflows auf.

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

| Option | Beschreibung |
|---|---|
| `--status=<status>` | Nach Status filtern: `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

Der Befehl gibt höchstens 50 Workflows zurück. Er liest einen Wert für `--limit`, aber WP-CLI weist das Flag derzeit zurück, da der Befehl es nicht deklariert ([#12](https://github.com/inline0/queuety/issues/12)); verwende `Queuety::list_workflows()` für einen anderen Grenzwert.

Die Standardtabelle enthält `StepName` und `WaitMode`, damit sich blockierte Workflows leichter überblicken lassen.

### `wp queuety workflow retry`

Einen fehlgeschlagenen Workflow ab dem fehlgeschlagenen Schritt erneut versuchen.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |

### `wp queuety workflow approve`

Sendet ein Genehmigungssignal an einen Workflow.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `--data=<json>` | Optionaler JSON-Objekt-Payload |
| `--signal=<name>` | Überschreibt den Namen des Genehmigungssignals (Standard: `approval`, passend zu `wait_for_approval()`; ein Schritt vom Typ `wait_for_decision()` wartet standardmäßig auf `approved`, gib dort also `--signal=approved` an) |

### `wp queuety workflow reject`

Sendet ein Ablehnungssignal an einen Workflow.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `--data=<json>` | Optionaler JSON-Objekt-Payload |
| `--signal=<name>` | Überschreibt den Namen des Ablehnungssignals (Standard: `rejected`) |

### `wp queuety workflow input`

Sendet strukturierte Eingaben an einen Workflow.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `--data=<json>` | Optionaler JSON-Objekt-Payload |
| `--signal=<name>` | Überschreibt den Namen des Eingabesignals (Standard: `input`) |

### `wp queuety workflow artifacts`

Listet gespeicherte Artefakte für einen Workflow auf.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `--format=<format>` | Ausgabeformat: `table` (Standard) oder `json` |
| `--with-content` | Artefaktinhalt in die Ausgabe aufnehmen |

### `wp queuety workflow artifact`

Zeigt ein gespeichertes Artefakt eines Workflows an.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `<key>` | Artefaktschlüssel (erforderlich) |

### `wp queuety workflow pause`

Pausiert einen laufenden Workflow.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |

### `wp queuety workflow resume`

Einen pausierten Workflow fortsetzen.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |

### `wp queuety workflow cancel`

Bricht einen Workflow ab, der sich nicht bereits im Status `completed` oder `cancelled` befindet. In einer Transaktion setzt Queuety den Status auf `cancelled`, vergräbt die ausstehenden und laufenden Jobs des Workflows und protokolliert `workflow_cancelled`. Anschließend führt es Kompensationen und alle registrierten Bereinigungshandler aus.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID für den Abbruch (erforderlich) |

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

### `wp queuety workflow timeline`

Zeigt die Ereigniszeitleiste eines Workflows an. Sie enthält alle Schritt-Ereignisse (gestartet, abgeschlossen, fehlgeschlagen) mit Zeitstempeln, Handlern und Laufzeiten.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `--limit=<limit>` | Höchstzahl der zurückzugebenden Ereignisse (Standard: `100`) |
| `--offset=<offset>` | Anzahl der zu überspringenden älteren Ereignisse (Standard: `0`) |
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

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

Ausgabespalten: `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Zeigt den öffentlichen Workflow-Status nach Abschluss oder Fortsetzung eines bestimmten Workflow-Schritts an.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `<step>` | Schrittindex, beginnend bei 0 (erforderlich) |

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

Details dazu, was aufgezeichnet wird und wofür es verwendet werden kann, findest du unter [Workflow Event Log](https://queuety.inline0.dev/de/docs/workflows/event-log).

### `wp queuety workflow rewind`

Setzt einen Workflow auf einen früheren Schritt zurück und fährt mit dem darauffolgenden Schritt fort. Der Status wird anhand des Ereignisprotokolls `state_after` für den angegebenen Schritt wiederhergestellt; der nächste Schritt (`<step> + 1`) wird in die Queue gestellt. Der angegebene Schritt wird nicht erneut ausgeführt.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `<step>` | Schrittindex, auf den zurückgesetzt werden soll, beginnend bei 0 (erforderlich) |

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

Details findest du unter [Time Travel](https://queuety.inline0.dev/de/docs/workflows/time-travel).

### `wp queuety workflow fork`

Erstellt aus einem laufenden Workflow am aktuellen Status eine unabhängige Kopie. Der abgezweigte Workflow erhält eine neue ID und läuft eigenständig weiter.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID für die Abzweigung (erforderlich) |

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

Details findest du unter [Forking](https://queuety.inline0.dev/de/docs/workflows/forking).

### `wp queuety workflow export`

Exportiert den vollständigen Ausführungsverlauf eines Workflows nach JSON. Enthalten sind der Workflow-Datensatz, Jobs, Workflow-Ereignisse, Protokolleinträge, gespeicherte Signale und Wartevorgänge für Workflow-Abhängigkeiten.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `--output=<file>` | Dateipfad für die Ausgabe von JSON. Standardmäßig stdout. |

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

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

Details zur Struktur von JSON findest du unter [Export and Replay](https://queuety.inline0.dev/de/docs/workflows/export-replay).

### `wp queuety workflow replay`

Spielt einen exportierten Workflow aus einer JSON-Datei erneut ab. Erstellt einen neuen Workflow mit dem exportierten Status, den Metadaten und der historischen Zeitleiste.

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

| Option | Beschreibung |
|---|---|
| `<file>` | Pfad zur exportierten JSON-Datei (erforderlich) |

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

Einzelheiten findest du unter [Export und Wiedergabe](https://queuety.inline0.dev/de/docs/workflows/export-replay).

## Schedule-Befehle

### `wp queuety schedule list`

Listet alle wiederkehrenden Zeitpläne auf.

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

| Option | Beschreibung |
|---|---|
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Fügt einen wiederkehrenden Zeitplan hinzu.

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

| Option | Beschreibung |
|---|---|
| `<handler>` | Handlername oder -klasse (erforderlich) |
| `--every=<interval>` | Intervallausdruck (e.g. `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Cron-Ausdruck (e.g. `0 3 * * *`) |
| `--payload=<json>` | JSON-Payload (Standard: `{}`) |
| `--queue=<queue>` | Queue-Name (Standard: `default`) |

Du musst entweder `--every` oder `--cron` angeben.

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

Entfernt einen Zeitplan anhand des Handlernamens.

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

| Option | Beschreibung |
|---|---|
| `<handler>` | Zu entfernender Handlername (erforderlich) |

### `wp queuety schedule run`

Löst manuell einen Scheduler-Tick aus. Stellt Jobs für alle fälligen Zeitpläne in die Queue.

```bash
wp queuety schedule run
```

## Protokollbefehle

### `wp queuety log`

Fragt Protokolleinträge ab.

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

| Option | Beschreibung |
|---|---|
| `--job=<id>` | Nach Job-ID filtern |
| `--workflow=<id>` | Nach Workflow-ID filtern |
| `--handler=<name>` | Nach Handlernamen filtern |
| `--event=<event>` | Nach Ereignistyp filtern (`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>` | Einträge ab diesem Datum und dieser Uhrzeit anzeigen |
| `--limit=<n>` | Höchstzahl der anzuzeigenden Einträge (Standard: `50`) |
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

Filter werden nicht kombiniert: Queuety wendet den ersten vorhandenen Filter in der Reihenfolge `--job`, `--workflow`, `--handler`, `--event`, `--since` an. `--job` und `--workflow` geben alle Einträge in aufsteigender Reihenfolge zurück und ignorieren `--limit`. `--handler` und `--event` geben die neuesten Einträge zuerst zurück. Ohne Filter liest der Befehl die letzten 24 Stunden. Diese Abfrage und `--since` listen Einträge in aufsteigender Reihenfolge auf, sodass `--limit` die ältesten Einträge im Zeitfenster beibehält.

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

### Protokolleinträge löschen

`LogCommand` definiert einen Unterbefehl `purge` (`wp queuety log purge --older-than=<days>`), aber WP-CLI registriert `wp queuety log` als einzelnen Befehl. Daher ist der Unterbefehl nicht erreichbar und schlägt mit „Too many positional arguments: purge“ fehl ([#11](https://github.com/inline0/queuety/issues/11)). Lösche alte Protokolleinträge stattdessen über PHP:

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

## Webhook-Befehle

### `wp queuety webhook add`

Registriert einen Webhook URL für ein Ereignis.

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

| Option | Beschreibung |
|---|---|
| `<event>` | Ereignisname: `job.completed`, `job.failed`, `job.buried` oder `workflow.failed` (erforderlich) |
| `<url>` | URL für POST-Benachrichtigungen (erforderlich) |

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

### `wp queuety webhook list`

Listet alle registrierten Webhooks auf.

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

| Option | Beschreibung |
|---|---|
| `--format=<format>` | Ausgabeformat: `table` (Standard), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Entfernt einen Webhook anhand seiner ID.

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

| Option | Beschreibung |
|---|---|
| `<id>` | Zu entfernende Webhook-ID (erforderlich) |