# Référence CLI

Toutes les opérations Queuety sont disponibles par défaut via WP-CLI dans l’espace de noms `wp queuety`.

Définissez `QUEUETY_CLI_COMMAND` avant le démarrage de Queuety si vous souhaitez publier le même arbre de commandes sous une autre racine, par exemple `wp themequeue`.

Pour les environnements de test d’agents et autres intégrations de bash virtuel, utilisez cette page comme référence destinée aux personnes et le pont PHP comme contrat machine :

- `Queuety::cli_command_map()` expose le catalogue sérialisable des commandes
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` transforme les entrées `wp queuety ...` analysées en un plan d’exécution normalisé qui privilégie les fonctions appelables directes PHP

Il n’y a aucune commande dans cet arbre pour les machines à états ; consultez-les via le PHP API présenté dans [Machines à états](https://queuety.inline0.dev/fr/docs/state-machines).

## Commandes de tâches

### `wp queuety work`

Démarre un processus de travail qui traite les tâches.

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

| Option | Description |
|---|---|
| `--queue=<queue>` | Queue(s) à traiter, séparées par des virgules pour définir l’ordre de priorité (par défaut : `default`) |
| `--once` | Traite au maximum une tâche, puis quitte (quitte également immédiatement si aucune tâche ne peut être récupérée) |
| `--workers=<n>` | Lance N processus de travail (nécessite les extensions `pcntl` et `posix`, tout comme `--min-workers` et `--max-workers`) |
| `--min-workers=<n>` | Nombre minimal de processus pour un pool adaptatif. Nécessite `--max-workers` |
| `--max-workers=<n>` | Nombre maximal de processus pour un pool adaptatif |

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

Lorsque plusieurs files d’attente sont spécifiées, le processus de travail essaie de récupérer une tâche dans chacune, dans l’ordre indiqué. La première file contenant une tâche disponible est retenue. `--workers` maintient le pool à taille fixe. `--min-workers` et `--max-workers` activent la mise à l’échelle adaptative pour les mêmes commandes. Consultez [Processus de travail](https://queuety.inline0.dev/fr/docs/features/workers) pour les stratégies de déploiement et [Gestion des ressources](https://queuety.inline0.dev/fr/docs/features/resource-management) pour le modèle d’admission utilisé par les pools adaptatifs.

### `wp queuety flush`

Traite toutes les tâches en attente, puis quitte.

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

| Option | Description |
|---|---|
| `--queue=<queue>` | Queue(s) à vider, séparées par des virgules pour définir l’ordre de priorité (par défaut : `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`

Distribue une tâche depuis la ligne de commande.

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

| Option | Description |
|---|---|
| `<handler>` | Nom ou classe du gestionnaire (obligatoire) |
| `--payload=<json>` | Données utiles JSON (par défaut : `{}`) |
| `--queue=<queue>` | Nom de la file d’attente (par défaut : `default`) |
| `--priority=<priority>` | Niveau de priorité 0-3 (par défaut : `0`) |
| `--delay=<seconds>` | Délai en secondes (par défaut : `0`) |

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

### `wp queuety status`

Affiche les statistiques des files d’attente.

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

| Option | Description |
|---|---|
| `--queue=<queue>` | Filtre par nom de file d’attente |

### `wp queuety list`

Liste les tâches.

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

| Option | Description |
|---|---|
| `--queue=<queue>` | Filtre par file d’attente |
| `--status=<status>` | Filtre par statut (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Affiche tous les détails d’une tâche, y compris sa charge utile et l’historique des journaux.

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

| Option | Description |
|---|---|
| `<id>` | ID de tâche (obligatoire) |

### `wp queuety retry`

Relance une tâche précise.

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

| Option | Description |
|---|---|
| `<id>` | ID de la tâche à relancer (obligatoire) |

### `wp queuety retry-buried`

Relance toutes les tâches mises en quarantaine.

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

### `wp queuety bury`

Met manuellement une tâche en quarantaine.

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

| Option | Description |
|---|---|
| `<id>` | ID de la tâche à mettre en quarantaine (obligatoire) |

### `wp queuety delete`

Supprime une tâche.

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

| Option | Description |
|---|---|
| `<id>` | ID de la tâche à supprimer (obligatoire) |

### `wp queuety recover`

Récupère les tâches obsolètes bloquées au statut `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

Purge les tâches terminées.

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

| Option | Description |
|---|---|
| `--older-than=<days>` | Supprime les tâches datant de plus de N jours (par défaut : `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Met en pause une file d’attente pour que les workers l’ignorent.

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

| Option | Description |
|---|---|
| `<queue>` | Nom de la file d’attente à suspendre (obligatoire) |

### `wp queuety resume`

Reprend une file d’attente en pause.

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

| Option | Description |
|---|---|
| `<queue>` | Nom de la file d’attente à reprendre (obligatoire) |

### `wp queuety metrics`

Affiche les métriques par gestionnaire.

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

| Option | Description |
|---|---|
| `--minutes=<minutes>` | Période en minutes (par défaut : `60`) |
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

### `wp queuety discover`

Détecte les classes de gestionnaires dans un répertoire.

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

| Option | Description |
|---|---|
| `<directory>` | Répertoire dans lequel rechercher les classes de gestionnaires (obligatoire) |
| `<namespace>` | Préfixe d’espace de noms PSR-4 pour le répertoire (obligatoire) |
| `--register` | Enregistre réellement les gestionnaires détectés |

## Commandes de workflow

### `wp queuety workflow status`

Affiche le statut et la progression du workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |

`status` affiche l’étape actuelle, le nom facultatif de l’étape, les métadonnées de version et de hachage, le mode d’attente, le résumé des artefacts et un objet `WaitInfo` JSON lorsque le workflow est bloqué en attente de signaux ou de dépendances.

### `wp queuety workflow list`

Liste les workflows.

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

| Option | Description |
|---|---|
| `--status=<status>` | Filtre par statut : `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

La commande renvoie au maximum 50 workflows. Elle lit une valeur `--limit`, mais WP-CLI rejette actuellement l’option, car la commande ne la déclare pas ([#12](https://github.com/inline0/queuety/issues/12)) ; utilisez `Queuety::list_workflows()` pour définir une autre limite.

Le tableau par défaut inclut `StepName` et `WaitMode` afin de faciliter le repérage des workflows bloqués.

### `wp queuety workflow retry`

Relancer un workflow en échec à partir de l’étape qui a échoué.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |

### `wp queuety workflow approve`

Envoie un signal d’approbation à un workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `--data=<json>` | Objet de données utiles JSON facultatif |
| `--signal=<name>` | Remplace le nom du signal d’approbation (par défaut : `approval`, qui correspond à `wait_for_approval()` ; une étape `wait_for_decision()` attend `approved` par défaut, utilisez donc `--signal=approved` dans ce cas) |

### `wp queuety workflow reject`

Envoie un signal de rejet à un workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `--data=<json>` | Objet de données utiles JSON facultatif |
| `--signal=<name>` | Remplace le nom du signal de rejet (par défaut : `rejected`) |

### `wp queuety workflow input`

Envoie des données structurées à un workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `--data=<json>` | Objet de données utiles JSON facultatif |
| `--signal=<name>` | Remplace le nom du signal d’entrée (par défaut : `input`) |

### `wp queuety workflow artifacts`

Liste les artefacts stockés pour un workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `--format=<format>` | Format de sortie : `table` (par défaut) ou `json` |
| `--with-content` | Inclut le contenu des artefacts dans la sortie |

### `wp queuety workflow artifact`

Affiche un artefact stocké pour un workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `<key>` | Clé de l’artefact (obligatoire) |

### `wp queuety workflow pause`

Suspend un workflow en cours d’exécution.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |

### `wp queuety workflow resume`

Reprendre un workflow en pause.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |

### `wp queuety workflow cancel`

Annule un workflow dont le statut n’est ni `completed` ni `cancelled`. En une transaction, Queuety définit le statut sur `cancelled`, met en quarantaine les tâches en attente et en cours du workflow et consigne `workflow_cancelled` ; il exécute ensuite les compensations et tout gestionnaire de nettoyage enregistré.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow à annuler (obligatoire) |

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

### `wp queuety workflow timeline`

Affiche la chronologie des événements d’un workflow. Présente tous les événements d’étape (démarrée, terminée, échouée) avec leurs horodatages, gestionnaires et durées.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `--limit=<limit>` | Nombre maximal d’événements à renvoyer (par défaut : `100`) |
| `--offset=<offset>` | Nombre d’événements précédents à ignorer (par défaut : `0`) |
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

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

Colonnes de sortie : `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Affiche l’état public du workflow après la fin ou la reprise d’une étape donnée.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `<step>` | Index de l’étape, à partir de 0 (obligatoire) |

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

Consultez [Journal des événements du workflow](https://queuety.inline0.dev/fr/docs/workflows/event-log) pour savoir ce qui est enregistré et découvrir les cas d’utilisation.

### `wp queuety workflow rewind`

Ramène un workflow à une étape précédente et reprend l’exécution à l’étape suivante. L’état est restauré à partir du journal des événements `state_after` de l’étape indiquée et l’étape suivante (`<step> + 1`) est mise en file d’attente ; l’étape indiquée elle-même n’est pas relancée.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `<step>` | Index de l’étape à rétablir, à partir de 0 (obligatoire) |

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

Consultez [Voyage dans le temps](https://queuety.inline0.dev/fr/docs/workflows/time-travel) pour en savoir plus.

### `wp queuety workflow fork`

Crée une copie indépendante d’un workflow en cours à son état actuel. Le workflow dérivé reçoit un nouvel ID et progresse indépendamment.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow à dériver (obligatoire) |

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

Consultez [Création de branches](https://queuety.inline0.dev/fr/docs/workflows/forking) pour en savoir plus.

### `wp queuety workflow export`

Exporte l’historique complet d’exécution d’un workflow vers JSON. Inclut la ligne du workflow, les tâches, les événements du workflow, les entrées de journal, les signaux stockés et les attentes de dépendances du workflow.

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `--output=<file>` | Chemin du fichier dans lequel écrire JSON. La sortie standard est utilisée par défaut. |

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

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

Consultez [Exportation et relecture](https://queuety.inline0.dev/fr/docs/workflows/export-replay) pour en savoir plus sur la structure JSON.

### `wp queuety workflow replay`

Rejoue un workflow exporté à partir d’un fichier JSON. Crée un workflow avec l’état, les métadonnées et la chronologie historique exportés.

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

| Option | Description |
|---|---|
| `<file>` | Chemin vers le fichier JSON exporté (obligatoire) |

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

Consultez [Exportation et rejeu](https://queuety.inline0.dev/fr/docs/workflows/export-replay) pour en savoir plus.

## Commandes de planification

### `wp queuety schedule list`

Liste toutes les planifications récurrentes.

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

| Option | Description |
|---|---|
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Ajoute une planification récurrente.

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

| Option | Description |
|---|---|
| `<handler>` | Nom ou classe du gestionnaire (obligatoire) |
| `--every=<interval>` | Expression d’intervalle (e.g. `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Expression Cron (e.g. `0 3 * * *`) |
| `--payload=<json>` | Données utiles JSON (par défaut : `{}`) |
| `--queue=<queue>` | Nom de la file d’attente (par défaut : `default`) |

Vous devez spécifier soit `--every`, soit `--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`

Supprime une planification par nom de gestionnaire.

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

| Option | Description |
|---|---|
| `<handler>` | Nom du gestionnaire à supprimer (obligatoire) |

### `wp queuety schedule run`

Déclenche manuellement une exécution du planificateur. Met en file d’attente les tâches pour toutes les planifications arrivées à échéance.

```bash
wp queuety schedule run
```

## Commandes de journalisation

### `wp queuety log`

Interroge les entrées de journal.

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

| Option | Description |
|---|---|
| `--job=<id>` | Filtrer par ID de tâche |
| `--workflow=<id>` | Filtrer par ID de workflow |
| `--handler=<name>` | Filtrer par nom de gestionnaire |
| `--event=<event>` | Filtrer par type d’événement (`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>` | Afficher les entrées depuis cette date et heure |
| `--limit=<n>` | Nombre maximal d’entrées à afficher (par défaut : `50`) |
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

Les filtres ne se combinent pas : Queuety applique le premier filtre présent, dans l’ordre `--job`, `--workflow`, `--handler`, `--event`, `--since`. `--job` et `--workflow` renvoient toutes les entrées, de la plus ancienne à la plus récente, et ignorent `--limit`. `--handler` et `--event` renvoient d’abord les entrées les plus récentes. Sans filtre, la commande lit les dernières 24 heures ; cette requête et `--since` listent les entrées de la plus ancienne à la plus récente, donc `--limit` conserve les entrées les plus anciennes de la période.

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

### Purge des journaux

`LogCommand` définit une sous-commande `purge` (`wp queuety log purge --older-than=<days>`), mais WP-CLI enregistre `wp queuety log` comme une commande unique. La sous-commande est donc inaccessible et échoue avec « Too many positional arguments: purge » ([#11](https://github.com/inline0/queuety/issues/11)). Purgez plutôt les anciennes entrées du journal depuis PHP :

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

## Commandes de webhook

### `wp queuety webhook add`

Enregistrer un webhook URL pour un événement.

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

| Option | Description |
|---|---|
| `<event>` | Nom de l’événement : `job.completed`, `job.failed` ou `job.buried`, ou `workflow.failed` (obligatoire) |
| `<url>` | URL vers laquelle envoyer les notifications par POST (obligatoire) |

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

### `wp queuety webhook list`

Lister tous les webhooks enregistrés.

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

| Option | Description |
|---|---|
| `--format=<format>` | Format de sortie : `table` (par défaut), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Supprimer un webhook par ID.

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

| Option | Description |
|---|---|
| `<id>` | ID du webhook à supprimer (obligatoire) |