# Riferimento CLI

Tutte le operazioni Queuety sono disponibili tramite WP-CLI nel namespace `wp queuety` per impostazione predefinita.

Definite `QUEUETY_CLI_COMMAND` prima dell'avvio di Queuety se volete pubblicare lo stesso albero di comandi con una radice diversa, come `wp themequeue`.

Per gli harness degli agenti e altre integrazioni virtual-bash, considerate questa pagina come riferimento per le persone e usate il bridge PHP come contratto per le macchine:

- `Queuety::cli_command_map()` espone il catalogo serializzabile dei comandi
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` trasforma l'input `wp queuety ...` analizzato in un piano di esecuzione normalizzato che privilegia i callable diretti PHP

In questo albero non ci sono comandi per le macchine a stati; esaminatele tramite PHP API descritte in [Macchine a stati](https://queuety.inline0.dev/it/docs/state-machines).

## Comandi per i job

### `wp queuety work`

Avvia un worker che elabora i job.

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

| Opzione | Descrizione |
|---|---|
| `--queue=<queue>` | Queue(s) da elaborare, separati da virgole per ordinarli per priorità (predefinito: `default`) |
| `--once` | Elabora al massimo un job e termina (termina subito anche quando non ci sono job disponibili da acquisire) |
| `--workers=<n>` | Avvia N processi worker separati (richiede le estensioni `pcntl` e `posix`, così come `--min-workers` e `--max-workers`) |
| `--min-workers=<n>` | Numero minimo di worker per un pool adattivo. Richiede `--max-workers` |
| `--max-workers=<n>` | Numero massimo di worker per un pool adattivo |

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

Quando vengono specificate più code, il worker tenta di acquisire un job da ciascuna nell'ordine indicato. Vince la prima coda con un job disponibile. `--workers` mantiene fisso il pool. `--min-workers` e `--max-workers` attivano il ridimensionamento adattivo per gli stessi comandi. Consultate [Worker](https://queuety.inline0.dev/it/docs/features/workers) per le strategie di distribuzione e [Gestione delle risorse](https://queuety.inline0.dev/it/docs/features/resource-management) per il modello di ammissione alla base dei pool adattivi.

### `wp queuety flush`

Elabora tutti i job in attesa e termina.

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

| Opzione | Descrizione |
|---|---|
| `--queue=<queue>` | Queue(s) da svuotare, separati da virgole per ordinarli per priorità (predefinito: `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`

Invia un job dalla riga di comando.

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

| Opzione | Descrizione |
|---|---|
| `<handler>` | Nome del gestore o classe (obbligatorio) |
| `--payload=<json>` | Payload JSON (predefinito: `{}`) |
| `--queue=<queue>` | Nome della coda (predefinito: `default`) |
| `--priority=<priority>` | Livello di priorità 0-3 (predefinito: `0`) |
| `--delay=<seconds>` | Ritardo in secondi (predefinito: `0`) |

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

### `wp queuety status`

Mostra le statistiche delle code.

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

| Opzione | Descrizione |
|---|---|
| `--queue=<queue>` | Filtra per nome della coda |

### `wp queuety list`

Elenca i job.

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

| Opzione | Descrizione |
|---|---|
| `--queue=<queue>` | Filtra per coda |
| `--status=<status>` | Filtra per stato (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Mostra tutti i dettagli di un job, inclusi il payload e la cronologia dei log.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del job (obbligatorio) |

### `wp queuety retry`

Riprova un job specifico.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del job da riprovare (obbligatorio) |

### `wp queuety retry-buried`

Riprova tutti i job archiviati.

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

### `wp queuety bury`

Sposta manualmente un job in archivio.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del job da archiviare (obbligatorio) |

### `wp queuety delete`

Elimina un job.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del job da eliminare (obbligatorio) |

### `wp queuety recover`

Recupera i job non aggiornati bloccati nello stato `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

Elimina i job completati.

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

| Opzione | Descrizione |
|---|---|
| `--older-than=<days>` | Elimina i job più vecchi di N giorni (predefinito: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Metti in pausa una coda, così i worker la saltano.

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

| Opzione | Descrizione |
|---|---|
| `<queue>` | Nome della coda da mettere in pausa (obbligatorio) |

### `wp queuety resume`

Riprendi una coda in pausa.

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

| Opzione | Descrizione |
|---|---|
| `<queue>` | Nome della coda da riprendere (obbligatorio) |

### `wp queuety metrics`

Mostra le metriche per gestore.

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

| Opzione | Descrizione |
|---|---|
| `--minutes=<minutes>` | Finestra temporale in minuti (predefinita: `60`) |
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

### `wp queuety discover`

Individua le classi handler in una directory.

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

| Opzione | Descrizione |
|---|---|
| `<directory>` | Directory in cui cercare le classi handler (obbligatorio) |
| `<namespace>` | Prefisso namespace PSR-4 della directory (obbligatorio) |
| `--register` | Registra effettivamente gli handler individuati |

## Comandi del workflow

### `wp queuety workflow status`

Mostra lo stato e l'avanzamento del workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |

`status` stampa il passaggio corrente, il nome facoltativo del passaggio, i metadati di versione/hash, la modalità di attesa, il riepilogo degli artefatti e un blocco `WaitInfo` JSON quando il workflow è in attesa di segnali o dipendenze.

### `wp queuety workflow list`

Elenca i workflow.

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

| Opzione | Descrizione |
|---|---|
| `--status=<status>` | Filtra per stato: `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

Il comando restituisce al massimo 50 workflow. Legge un valore `--limit`, ma WP-CLI attualmente rifiuta il flag perché il comando non lo dichiara ([#12](https://github.com/inline0/queuety/issues/12)); usa `Queuety::list_workflows()` per impostare un limite diverso.

La tabella predefinita include `StepName` e `WaitMode` per facilitare la consultazione dei workflow bloccati.

### `wp queuety workflow retry`

Riprova un flusso di lavoro non riuscito a partire dal passaggio che ha causato l'errore.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |

### `wp queuety workflow approve`

Invia un segnale di approvazione a un workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `--data=<json>` | Payload dell'oggetto JSON facoltativo |
| `--signal=<name>` | Sostituisce il nome del segnale di approvazione (predefinito: `approval`, corrispondente a `wait_for_approval()`; un passaggio `wait_for_decision()` è in ascolto di `approved` per impostazione predefinita, quindi passa `--signal=approved` in quel caso) |

### `wp queuety workflow reject`

Invia un segnale di rifiuto a un workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `--data=<json>` | Payload dell'oggetto JSON facoltativo |
| `--signal=<name>` | Sostituisce il nome del segnale di rifiuto (predefinito: `rejected`) |

### `wp queuety workflow input`

Invia input strutturato a un workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `--data=<json>` | Payload dell'oggetto JSON facoltativo |
| `--signal=<name>` | Sostituisce il nome del segnale di input (predefinito: `input`) |

### `wp queuety workflow artifacts`

Elenca gli artefatti salvati per un workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `--format=<format>` | Formato di output: `table` (predefinito) o `json` |
| `--with-content` | Include il contenuto degli artefatti nell'output |

### `wp queuety workflow artifact`

Mostra un artefatto salvato per un workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `<key>` | Chiave dell'artefatto (obbligatoria) |

### `wp queuety workflow pause`

Sospende un workflow in esecuzione.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |

### `wp queuety workflow resume`

Riprende un flusso di lavoro in pausa.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |

### `wp queuety workflow cancel`

Annulla un workflow che non sia già `completed` o `cancelled`. In un'unica transazione, Queuety imposta lo stato su `cancelled`, mette da parte i job in sospeso e in elaborazione del workflow e registra `workflow_cancelled`; poi esegue le compensazioni e l'eventuale handler di pulizia registrato.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow da annullare (obbligatorio) |

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

### `wp queuety workflow timeline`

Mostra la cronologia degli eventi di un workflow. Visualizza tutti gli eventi dei passaggi (avviato, completato, non riuscito) con timestamp, handler e durate.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `--limit=<limit>` | Numero massimo di eventi da restituire (predefinito: `100`) |
| `--offset=<offset>` | Numero di eventi precedenti da saltare (predefinito: `0`) |
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

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

Colonne di output: `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Mostra lo stato pubblico del workflow dopo che un passaggio specifico è stato completato o ripreso.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `<step>` | Indice del passaggio, a partire da 0 (obbligatorio) |

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

Per i dettagli su ciò che viene registrato e sui casi d'uso, consulta [Registro eventi del workflow](https://queuety.inline0.dev/it/docs/workflows/event-log).

### `wp queuety workflow rewind`

Riporta un workflow a un passaggio precedente e prosegue da quello successivo. Lo stato viene ripristinato dal registro eventi `state_after` relativo al passaggio indicato e il passaggio successivo (`<step> + 1`) viene accodato; il passaggio indicato non viene eseguito di nuovo.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `<step>` | Indice del passaggio a cui tornare, a partire da 0 (obbligatorio) |

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

Per i dettagli, consulta [Viaggio nel tempo](https://queuety.inline0.dev/it/docs/workflows/time-travel).

### `wp queuety workflow fork`

Crea una copia indipendente di un workflow in esecuzione, mantenendone lo stato corrente. Il workflow duplicato riceve un nuovo ID e procede in modo indipendente.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow da duplicare (obbligatorio) |

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

Per i dettagli, consulta [Creazione di fork](https://queuety.inline0.dev/it/docs/workflows/forking).

### `wp queuety workflow export`

Esporta la cronologia completa di esecuzione di un workflow in JSON. Include la riga del workflow, i job, gli eventi del workflow, le voci di log, i segnali salvati e le attese sulle dipendenze del workflow.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `--output=<file>` | Percorso del file in cui scrivere JSON. Per impostazione predefinita, usa stdout. |

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

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

Per i dettagli sulla struttura di JSON, consulta [Esportazione e riproduzione](https://queuety.inline0.dev/it/docs/workflows/export-replay).

### `wp queuety workflow replay`

Riproduce un workflow esportato da un file JSON. Crea un nuovo workflow con lo stato esportato, i metadati e la cronologia degli eventi.

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

| Opzione | Descrizione |
|---|---|
| `<file>` | Percorso del file JSON esportato (obbligatorio) |

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

Per i dettagli, vedi [Esportazione e riproduzione](https://queuety.inline0.dev/it/docs/workflows/export-replay).

## Comandi di pianificazione

### `wp queuety schedule list`

Elenca tutte le pianificazioni ricorrenti.

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

| Opzione | Descrizione |
|---|---|
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Aggiunge una pianificazione ricorrente.

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

| Opzione | Descrizione |
|---|---|
| `<handler>` | Nome o classe dell'handler (obbligatorio) |
| `--every=<interval>` | Espressione di intervallo (e.g. `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Espressione Cron (e.g. `0 3 * * *`) |
| `--payload=<json>` | Payload JSON (predefinito: `{}`) |
| `--queue=<queue>` | Nome della coda (predefinito: `default`) |

È necessario specificare `--every` oppure `--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`

Rimuove una pianificazione in base al nome dell'handler.

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

| Opzione | Descrizione |
|---|---|
| `<handler>` | Nome dell'handler da rimuovere (obbligatorio) |

### `wp queuety schedule run`

Avvia manualmente un ciclo dello scheduler. Accoda i job per tutte le pianificazioni in scadenza.

```bash
wp queuety schedule run
```

## Comandi dei log

### `wp queuety log`

Interroga le voci di log.

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

| Opzione | Descrizione |
|---|---|
| `--job=<id>` | Filtra per ID del job |
| `--workflow=<id>` | Filtra per ID del workflow |
| `--handler=<name>` | Filtra per nome dell'handler |
| `--event=<event>` | Filtra per tipo di evento (`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>` | Mostra le voci a partire da questa data e ora |
| `--limit=<n>` | Numero massimo di voci da mostrare (predefinito: `50`) |
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

I filtri non si combinano: Queuety applica il primo filtro presente, nell'ordine `--job`, `--workflow`, `--handler`, `--event`, `--since`. `--job` e `--workflow` restituiscono tutte le voci, dalla più vecchia, e ignorano `--limit`. `--handler` e `--event` restituiscono prima le voci più recenti. Senza un filtro, il comando legge le ultime 24 ore; questa query e `--since` elencano le voci dalla più vecchia, quindi `--limit` conserva le voci più vecchie nell'intervallo.

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

### Eliminazione dei log

`LogCommand` definisce il sottocomando `purge` (`wp queuety log purge --older-than=<days>`), ma WP-CLI registra `wp queuety log` come comando singolo, quindi non è possibile richiamare il sottocomando e l'operazione fallisce con "Too many positional arguments: purge" ([#11](https://github.com/inline0/queuety/issues/11)). Usa invece PHP per eliminare le vecchie voci di log:

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

## Comandi dei webhook

### `wp queuety webhook add`

Registra un webhook URL per un evento.

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

| Opzione | Descrizione |
|---|---|
| `<event>` | Nome dell'evento: `job.completed`, `job.failed`, `job.buried` o `workflow.failed` (obbligatorio) |
| `<url>` | URL a cui inviare notifiche tramite POST (obbligatorio) |

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

### `wp queuety webhook list`

Elenca tutti i webhook registrati.

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

| Opzione | Descrizione |
|---|---|
| `--format=<format>` | Formato di output: `table` (predefinito), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Rimuove un webhook in base all'ID.

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del webhook da rimuovere (obbligatorio) |