# Referencia de CLI

Todas las operaciones de Queuety están disponibles mediante WP-CLI, de forma predeterminada, en el espacio de nombres `wp queuety`.

Define `QUEUETY_CLI_COMMAND` antes de que se inicie Queuety si quieres publicar el mismo árbol de comandos con otra raíz, como `wp themequeue`.

Para las herramientas de prueba de agentes y otras integraciones de bash virtual, usa esta página como referencia para personas y el puente PHP como contrato para máquinas:

- `Queuety::cli_command_map()` expone el catálogo serializable de comandos
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` convierte la entrada analizada de `wp queuety ...` en un plan de ejecución normalizado que prioriza las funciones directas de PHP

Los autómatas de estados no tienen comandos en este árbol; inspecciónalos mediante PHP API, descrito en [Autómatas de estados](https://queuety.inline0.dev/es/docs/state-machines).

## Comandos de tareas

### `wp queuety work`

Inicia un trabajador que procesa tareas.

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

| Opción | Descripción |
|---|---|
| `--queue=<queue>` | Queue(s) que se procesarán, separadas por comas y ordenadas por prioridad (predeterminado: `default`) |
| `--once` | Procesa como máximo una tarea y sale (también sale de inmediato si no hay ninguna tarea disponible para reclamar) |
| `--workers=<n>` | Inicia N procesos de trabajador (requiere las extensiones `pcntl` y `posix`, al igual que `--min-workers` y `--max-workers`) |
| `--min-workers=<n>` | Número mínimo de trabajadores para un grupo adaptable. Requiere `--max-workers` |
| `--max-workers=<n>` | Número máximo de trabajadores para un grupo adaptable |

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

Si se especifican varias colas, el trabajador intenta reclamar tareas de cada una en el orden indicado. Se usa la primera cola que tenga una tarea disponible. `--workers` mantiene fijo el grupo. `--min-workers` y `--max-workers` habilitan el escalado adaptable para los mismos comandos. Consulta [Trabajadores](https://queuety.inline0.dev/es/docs/features/workers) para conocer estrategias de implementación y [Gestión de recursos](https://queuety.inline0.dev/es/docs/features/resource-management) para ver el modelo de admisión que usan los grupos adaptables.

### `wp queuety flush`

Procesa todas las tareas pendientes y sale.

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

| Opción | Descripción |
|---|---|
| `--queue=<queue>` | Queue(s) que se vaciarán, separadas por comas y ordenadas por prioridad (predeterminado: `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`

Envía una tarea desde la línea de comandos.

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

| Opción | Descripción |
|---|---|
| `<handler>` | Nombre o clase del controlador (obligatorio) |
| `--payload=<json>` | Carga útil de JSON (predeterminado: `{}`) |
| `--queue=<queue>` | Nombre de la cola (predeterminado: `default`) |
| `--priority=<priority>` | Nivel de prioridad de 0 a 3 (predeterminado: `0`) |
| `--delay=<seconds>` | Demora en segundos (predeterminado: `0`) |

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

### `wp queuety status`

Muestra las estadísticas de la cola.

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

| Opción | Descripción |
|---|---|
| `--queue=<queue>` | Filtra por nombre de cola |

### `wp queuety list`

Muestra las tareas.

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

| Opción | Descripción |
|---|---|
| `--queue=<queue>` | Filtra por cola |
| `--status=<status>` | Filtra por estado (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Muestra todos los detalles de una tarea, incluida la carga útil y el historial del registro.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID de la tarea (obligatorio) |

### `wp queuety retry`

Reintenta una tarea específica.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID de la tarea que se reintentará (obligatorio) |

### `wp queuety retry-buried`

Reintenta todas las tareas de la cola de tareas fallidas.

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

### `wp queuety bury`

Envía manualmente una tarea a la cola de tareas fallidas.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID de la tarea que se enviará a la cola de tareas fallidas (obligatorio) |

### `wp queuety delete`

Elimina una tarea.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID de la tarea que se eliminará (obligatorio) |

### `wp queuety recover`

Recupera las tareas obsoletas atascadas en el estado `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

Elimina las tareas completadas.

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

| Opción | Descripción |
|---|---|
| `--older-than=<days>` | Elimina las tareas anteriores a N días (predeterminado: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Pausa una cola para que los workers la omitan.

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

| Opción | Descripción |
|---|---|
| `<queue>` | Nombre de la cola que se pausará (obligatorio) |

### `wp queuety resume`

Reanuda una cola pausada.

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

| Opción | Descripción |
|---|---|
| `<queue>` | Nombre de la cola que se reanudará (obligatorio) |

### `wp queuety metrics`

Muestra las métricas por controlador.

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

| Opción | Descripción |
|---|---|
| `--minutes=<minutes>` | Intervalo de tiempo en minutos (predeterminado: `60`) |
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

### `wp queuety discover`

Busca clases de controladores en un directorio.

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

| Opción | Descripción |
|---|---|
| `<directory>` | Directorio donde buscar clases de controladores (obligatorio) |
| `<namespace>` | Prefijo de espacio de nombres PSR-4 para el directorio (obligatorio) |
| `--register` | Registra efectivamente los controladores encontrados |

## Comandos de flujo de trabajo

### `wp queuety workflow status`

Muestra el estado y el progreso del flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |

`status` muestra el paso actual, el nombre opcional del paso, los metadatos de versión/hash, el modo de espera, el resumen de artefactos y un bloque `WaitInfo` JSON cuando el flujo de trabajo está bloqueado por señales o dependencias.

### `wp queuety workflow list`

Muestra los flujos de trabajo.

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

| Opción | Descripción |
|---|---|
| `--status=<status>` | Filtra por estado: `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

El comando devuelve como máximo 50 flujos de trabajo. Lee un valor `--limit`, pero WP-CLI actualmente rechaza la opción porque el comando no la declara ([#12](https://github.com/inline0/queuety/issues/12)); usa `Queuety::list_workflows()` para establecer otro límite.

La tabla predeterminada incluye `StepName` y `WaitMode` para que sea más fácil revisar los flujos de trabajo bloqueados.

### `wp queuety workflow retry`

Reintenta un flujo de trabajo fallido desde el paso en el que falló.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |

### `wp queuety workflow approve`

Envía una señal de aprobación a un flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `--data=<json>` | Carga útil opcional de tipo JSON |
| `--signal=<name>` | Anula el nombre de la señal de aprobación (predeterminado: `approval`, que coincide con `wait_for_approval()`; un paso `wait_for_decision()` escucha `approved` de forma predeterminada, así que pasa `--signal=approved` allí) |

### `wp queuety workflow reject`

Envía una señal de rechazo a un flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `--data=<json>` | Carga útil opcional de objeto JSON |
| `--signal=<name>` | Reemplaza el nombre de la señal de rechazo (predeterminado: `rejected`) |

### `wp queuety workflow input`

Envía datos estructurados a un flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `--data=<json>` | Carga útil opcional de objeto JSON |
| `--signal=<name>` | Reemplaza el nombre de la señal de entrada (predeterminado: `input`) |

### `wp queuety workflow artifacts`

Muestra los artefactos guardados de un flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `--format=<format>` | Formato de salida: `table` (predeterminado) o `json` |
| `--with-content` | Incluye el contenido de los artefactos en la salida |

### `wp queuety workflow artifact`

Muestra un artefacto guardado de un flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `<key>` | Clave del artefacto (obligatorio) |

### `wp queuety workflow pause`

Pausa un flujo de trabajo en ejecución.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |

### `wp queuety workflow resume`

Reanuda un flujo de trabajo en pausa.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |

### `wp queuety workflow cancel`

Cancela un flujo de trabajo cuyo estado no sea ya `completed` ni `cancelled`. En una transacción, Queuety establece el estado en `cancelled`, envía a la cola de tareas fallidas las tareas pendientes y en curso del flujo y registra `workflow_cancelled`; después ejecuta las compensaciones y cualquier controlador de limpieza registrado.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo que se cancelará (obligatorio) |

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

### `wp queuety workflow timeline`

Muestra la cronología de eventos de un flujo de trabajo. Presenta todos los eventos de los pasos (iniciados, completados y fallidos) con marcas de tiempo, controladores y duraciones.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `--limit=<limit>` | Número máximo de eventos que se devolverán (predeterminado: `100`) |
| `--offset=<offset>` | Número de eventos anteriores que se omitirán (predeterminado: `0`) |
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

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

Columnas de salida: `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Muestra el estado público del flujo de trabajo después de que se complete o reanude un paso específico.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `<step>` | Índice del paso, basado en 0 (obligatorio) |

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

Consulta [Registro de eventos del flujo de trabajo](https://queuety.inline0.dev/es/docs/workflows/event-log) para saber qué se registra y conocer los casos de uso.

### `wp queuety workflow rewind`

Retrocede un flujo de trabajo a un paso anterior y continúa desde el siguiente. El estado se restaura a partir de `state_after` del registro de eventos correspondiente al paso indicado y se pone en cola el paso siguiente (`<step> + 1`); el paso indicado no vuelve a ejecutarse.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `<step>` | Índice del paso al que se retrocederá, basado en 0 (obligatorio) |

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

Consulta [Viaje en el tiempo](https://queuety.inline0.dev/es/docs/workflows/time-travel) para obtener más detalles.

### `wp queuety workflow fork`

Bifurca un flujo de trabajo en ejecución para crear una copia independiente en su estado actual. El flujo bifurcado recibe un ID nuevo y continúa de forma independiente.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo que se bifurcará (obligatorio) |

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

Consulta [Bifurcaciones](https://queuety.inline0.dev/es/docs/workflows/forking) para obtener más detalles.

### `wp queuety workflow export`

Exporta todo el historial de ejecución de un flujo de trabajo a JSON. Incluye la fila del flujo de trabajo, las tareas, los eventos del flujo, las entradas del registro, las señales guardadas y las esperas de dependencias del flujo de trabajo.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del flujo de trabajo (obligatorio) |
| `--output=<file>` | Ruta del archivo donde se escribirá JSON. De forma predeterminada, se escribe en la salida estándar. |

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

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

Consulta [Exportación y reproducción](https://queuety.inline0.dev/es/docs/workflows/export-replay) para obtener detalles sobre la estructura de JSON.

### `wp queuety workflow replay`

Reproduce un flujo de trabajo exportado desde un archivo JSON. Crea un flujo nuevo con el estado, los metadatos y la cronología histórica exportados.

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

| Opción | Descripción |
|---|---|
| `<file>` | Ruta al archivo JSON exportado (obligatorio) |

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

Consulta [Exportación y reproducción](https://queuety.inline0.dev/es/docs/workflows/export-replay) para obtener más detalles.

## Comandos de programación

### `wp queuety schedule list`

Muestra todas las programaciones periódicas.

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

| Opción | Descripción |
|---|---|
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Añade una programación periódica.

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

| Opción | Descripción |
|---|---|
| `<handler>` | Nombre o clase del controlador (obligatorio) |
| `--every=<interval>` | Expresión de intervalo (e.g. `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Expresión de Cron (e.g. `0 3 * * *`) |
| `--payload=<json>` | Carga útil de JSON (predeterminado: `{}`) |
| `--queue=<queue>` | Nombre de la cola (predeterminado: `default`) |

Debes especificar `--every` o `--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`

Elimina una programación por nombre de controlador.

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

| Opción | Descripción |
|---|---|
| `<handler>` | Nombre del controlador que se eliminará (obligatorio) |

### `wp queuety schedule run`

Activa manualmente un ciclo del programador. Pone en cola las tareas de todas las programaciones vencidas.

```bash
wp queuety schedule run
```

## Comandos de registro

### `wp queuety log`

Consulta las entradas del registro.

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

| Opción | Descripción |
|---|---|
| `--job=<id>` | Filtrar por ID del trabajo |
| `--workflow=<id>` | Filtrar por ID del flujo de trabajo |
| `--handler=<name>` | Filtrar por nombre del controlador |
| `--event=<event>` | Filtrar por tipo de 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>` | Mostrar entradas desde esta fecha y hora |
| `--limit=<n>` | Número máximo de entradas que se mostrarán (predeterminado: `50`) |
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

Los filtros no se combinan: Queuety aplica el primer filtro presente, en el orden `--job`, `--workflow`, `--handler`, `--event`, `--since`. `--job` y `--workflow` devuelven todas las entradas, de la más antigua a la más reciente, e ignoran `--limit`. `--handler` y `--event` devuelven primero las entradas más recientes. Sin un filtro, el comando lee las últimas 24 horas; esa consulta y `--since` enumeran las entradas de la más antigua a la más reciente, por lo que `--limit` conserva las entradas más antiguas del intervalo.

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

### Depurar registros

`LogCommand` define un subcomando `purge` (`wp queuety log purge --older-than=<days>`), pero WP-CLI registra `wp queuety log` como un comando único, por lo que no se puede acceder al subcomando y falla con «Too many positional arguments: purge» ([#11](https://github.com/inline0/queuety/issues/11)). Depure las entradas de registro antiguas desde PHP:

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

## Comandos de webhook

### `wp queuety webhook add`

Registra un webhook URL para un evento.

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

| Opción | Descripción |
|---|---|
| `<event>` | Nombre del evento: `job.completed`, `job.failed`, `job.buried` o `workflow.failed` (obligatorio) |
| `<url>` | URL a la que se enviarán notificaciones mediante POST (obligatorio) |

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

### `wp queuety webhook list`

Enumera todos los webhooks registrados.

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

| Opción | Descripción |
|---|---|
| `--format=<format>` | Formato de salida: `table` (predeterminado), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Elimina un webhook por su ID.

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

| Opción | Descripción |
|---|---|
| `<id>` | ID del webhook que se va a eliminar (obligatorio) |