# Referência de CLI

Todas as operações de Queuety estão disponíveis por meio de WP-CLI no namespace `wp queuety` por padrão.

Defina `QUEUETY_CLI_COMMAND` antes que Queuety seja inicializado se quiser publicar a mesma árvore de comandos com outra raiz, como `wp themequeue`.

Para ambientes de teste de agentes e outras integrações de virtual-bash, use esta página como referência para pessoas e a ponte PHP como contrato para máquinas:

- `Queuety::cli_command_map()` expõe o catálogo serializável de comandos
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` transforma a entrada `wp queuety ...` analisada em um plano de execução normalizado que prioriza funções chamáveis PHP diretas

As máquinas de estados não têm comandos nesta árvore; inspecione-as por meio de PHP API descrito em [Máquinas de estados](https://queuety.inline0.dev/pt/docs/state-machines).

## Comandos de trabalhos

### `wp queuety work`

Inicia um worker que processa trabalhos.

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

| Opção | Descrição |
|---|---|
| `--queue=<queue>` | Queue(s) a processar, separados por vírgulas para ordenar por prioridade (padrão: `default`) |
| `--once` | Processa no máximo um trabalho e sai (também sai imediatamente quando não há nada disponível para reivindicar) |
| `--workers=<n>` | Cria N processos de worker (requer as extensões `pcntl` e `posix`, assim como `--min-workers` e `--max-workers`) |
| `--min-workers=<n>` | Número mínimo de workers para um pool adaptativo. Requer `--max-workers` |
| `--max-workers=<n>` | Número máximo de workers para um pool adaptativo |

```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 várias filas são especificadas, o worker tenta reivindicar trabalhos de cada fila na ordem listada. A primeira fila com um trabalho disponível prevalece. `--workers` mantém o pool fixo. `--min-workers` e `--max-workers` habilitam o dimensionamento adaptativo para a mesma interface de comandos. Consulte [Workers](https://queuety.inline0.dev/pt/docs/features/workers) para estratégias de implantação e [Gerenciamento de recursos](https://queuety.inline0.dev/pt/docs/features/resource-management) para conhecer o modelo de admissão por trás dos pools adaptativos.

### `wp queuety flush`

Processa todos os trabalhos pendentes e sai.

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

| Opção | Descrição |
|---|---|
| `--queue=<queue>` | Queue(s) a esvaziar, separados por vírgulas para ordenar por prioridade (padrão: `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`

Envia um trabalho pela linha de comando.

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

| Opção | Descrição |
|---|---|
| `<handler>` | Nome ou classe do manipulador (obrigatório) |
| `--payload=<json>` | Carga útil JSON (padrão: `{}`) |
| `--queue=<queue>` | Nome da fila (padrão: `default`) |
| `--priority=<priority>` | Nível de prioridade 0-3 (padrão: `0`) |
| `--delay=<seconds>` | Atraso em segundos (padrão: `0`) |

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

### `wp queuety status`

Exibe as estatísticas da fila.

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

| Opção | Descrição |
|---|---|
| `--queue=<queue>` | Filtra pelo nome da fila |

### `wp queuety list`

Lista os trabalhos.

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

| Opção | Descrição |
|---|---|
| `--queue=<queue>` | Filtra pela fila |
| `--status=<status>` | Filtra pelo status (`pending`, `processing`, `completed`, `failed`, `buried`) |
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

### `wp queuety inspect`

Exibe todos os detalhes de um trabalho, incluindo a carga útil e o histórico do registro.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do trabalho (obrigatório) |

### `wp queuety retry`

Tenta novamente um trabalho específico.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do trabalho para tentar novamente (obrigatório) |

### `wp queuety retry-buried`

Tenta novamente todos os trabalhos enterrados.

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

### `wp queuety bury`

Enterra um trabalho manualmente.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do trabalho a enterrar (obrigatório) |

### `wp queuety delete`

Exclui um trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do trabalho a excluir (obrigatório) |

### `wp queuety recover`

Recupera trabalhos obsoletos que estejam parados no status `processing`.

```bash
wp queuety recover
```

### `wp queuety purge`

Elimina trabalhos concluídos.

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

| Opção | Descrição |
|---|---|
| `--older-than=<days>` | Exclui trabalhos com mais de N dias (padrão: `QUEUETY_RETENTION_DAYS`) |

### `wp queuety pause`

Pausa uma fila para que os workers a ignorem.

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

| Opção | Descrição |
|---|---|
| `<queue>` | Nome da fila a pausar (obrigatório) |

### `wp queuety resume`

Retoma uma fila pausada.

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

| Opção | Descrição |
|---|---|
| `<queue>` | Nome da fila a retomar (obrigatório) |

### `wp queuety metrics`

Exibe métricas por manipulador.

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

| Opção | Descrição |
|---|---|
| `--minutes=<minutes>` | Janela de tempo em minutos (padrão: `60`) |
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

### `wp queuety discover`

Descobre classes de manipuladores em um diretório.

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

| Opção | Descrição |
|---|---|
| `<directory>` | Diretório para procurar classes de manipuladores (obrigatório) |
| `<namespace>` | Prefixo de namespace PSR-4 para o diretório (obrigatório) |
| `--register` | Registra de fato os manipuladores descobertos |

## Comandos de fluxo de trabalho

### `wp queuety workflow status`

Exibe o status e o progresso do fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |

`status` exibe a etapa atual, o nome opcional da etapa, metadados de versão/hash, o modo de espera, um resumo dos artefatos e um blob `WaitInfo` JSON quando o fluxo de trabalho está bloqueado por sinais ou dependências.

### `wp queuety workflow list`

Lista os fluxos de trabalho.

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

| Opção | Descrição |
|---|---|
| `--status=<status>` | Filtra por status: `running`, `completed`, `failed`, `paused`, `waiting_for_signal`, `waiting_for_workflows`, `cancelled` |
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

O comando retorna no máximo 50 fluxos de trabalho. Ele lê um valor `--limit`, mas WP-CLI rejeita a opção atualmente porque o comando não a declara ([#12](https://github.com/inline0/queuety/issues/12)); use `Queuety::list_workflows()` para definir outro limite.

A tabela padrão inclui `StepName` e `WaitMode` para facilitar a identificação dos fluxos de trabalho bloqueados.

### `wp queuety workflow retry`

Tenta novamente um fluxo de trabalho com falha a partir da etapa que falhou.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |

### `wp queuety workflow approve`

Envia um sinal de aprovação a um fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--data=<json>` | Payload de objeto JSON opcional |
| `--signal=<name>` | Substitui o nome do sinal de aprovação (padrão: `approval`, que corresponde a `wait_for_approval()`; uma etapa `wait_for_decision()` aguarda `approved` por padrão, então passe `--signal=approved` nesse caso) |

### `wp queuety workflow reject`

Envia um sinal de rejeição a um fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--data=<json>` | Payload de objeto JSON opcional |
| `--signal=<name>` | Substitui o nome do sinal de rejeição (padrão: `rejected`) |

### `wp queuety workflow input`

Envia dados estruturados a um fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--data=<json>` | Payload de objeto JSON opcional |
| `--signal=<name>` | Substitui o nome do sinal de entrada (padrão: `input`) |

### `wp queuety workflow artifacts`

Lista os artefatos armazenados de um fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--format=<format>` | Formato de saída: `table` (padrão) ou `json` |
| `--with-content` | Inclui o conteúdo dos artefatos na saída |

### `wp queuety workflow artifact`

Exibe um artefato armazenado de um fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `<key>` | Chave do artefato (obrigatória) |

### `wp queuety workflow pause`

Pausa um fluxo de trabalho em execução.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |

### `wp queuety workflow resume`

Retoma um fluxo de trabalho pausado.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |

### `wp queuety workflow cancel`

Cancela um fluxo de trabalho que ainda não esteja `completed` nem `cancelled`. Em uma única transação, Queuety define o status como `cancelled`, enterra os jobs pendentes e em processamento do fluxo de trabalho e registra `workflow_cancelled`; em seguida, executa as compensações e qualquer rotina de limpeza registrada.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho a cancelar (obrigatório) |

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

### `wp queuety workflow timeline`

Exibe a linha do tempo de eventos de um fluxo de trabalho. Mostra todos os eventos das etapas (iniciada, concluída, com falha), com horários, handlers e durações.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--limit=<limit>` | Número máximo de eventos a retornar (padrão: `100`) |
| `--offset=<offset>` | Número de eventos anteriores a ignorar (padrão: `0`) |
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

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

Colunas de saída: `ID`, `Step`, `Event`, `Handler`, `Duration_ms`, `Error`, `Created_at`.

### `wp queuety workflow state-at`

Exibe o estado público do fluxo de trabalho após a conclusão ou retomada de uma etapa específica.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `<step>` | Índice da etapa, começando em 0 (obrigatório) |

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

Consulte [Registro de eventos do fluxo de trabalho](https://queuety.inline0.dev/pt/docs/workflows/event-log) para ver detalhes sobre o que é registrado e os casos de uso.

### `wp queuety workflow rewind`

Retrocede um fluxo de trabalho a uma etapa anterior e continua a partir da etapa seguinte. O estado é restaurado a partir do registro de eventos `state_after` da etapa indicada, e a etapa seguinte (`<step> + 1`) é enfileirada; a etapa indicada não é executada novamente.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `<step>` | Índice da etapa para a qual retroceder, começando em 0 (obrigatório) |

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

Consulte [Viagem no tempo](https://queuety.inline0.dev/pt/docs/workflows/time-travel) para ver detalhes.

### `wp queuety workflow fork`

Cria uma ramificação de um fluxo de trabalho em execução, copiando seu estado atual para uma instância independente. O fluxo de trabalho ramificado recebe um novo ID e prossegue de forma independente.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho a ramificar (obrigatório) |

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

Consulte [Ramificações](https://queuety.inline0.dev/pt/docs/workflows/forking) para ver detalhes.

### `wp queuety workflow export`

Exporta o histórico completo de execução de um fluxo de trabalho para JSON. Inclui a linha do fluxo de trabalho, os jobs, os eventos do fluxo de trabalho, as entradas de registro, os sinais armazenados e as esperas por dependências do fluxo de trabalho.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--output=<file>` | Caminho do arquivo onde gravar o JSON. O padrão é stdout. |

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

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

Consulte [Exportação e reprodução](https://queuety.inline0.dev/pt/docs/workflows/export-replay) para ver detalhes sobre a estrutura JSON.

### `wp queuety workflow replay`

Reproduz um fluxo de trabalho exportado a partir de um arquivo JSON. Cria um novo fluxo de trabalho com o estado, os metadados e a linha do tempo histórica exportados.

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

| Opção | Descrição |
|---|---|
| `<file>` | Caminho para o arquivo JSON exportado (obrigatório) |

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

Consulte [Exportação e reprodução](https://queuety.inline0.dev/pt/docs/workflows/export-replay) para obter detalhes.

## Comandos de agendamento

### `wp queuety schedule list`

Lista todos os agendamentos recorrentes.

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

| Opção | Descrição |
|---|---|
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

### `wp queuety schedule add`

Adiciona um agendamento recorrente.

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

| Opção | Descrição |
|---|---|
| `<handler>` | Nome do handler ou classe (obrigatório) |
| `--every=<interval>` | Expressão de intervalo (e.g. `1 hour`, `30 minutes`) |
| `--cron=<expression>` | Expressão Cron (e.g. `0 3 * * *`) |
| `--payload=<json>` | Payload JSON (padrão: `{}`) |
| `--queue=<queue>` | Nome da fila (padrão: `default`) |

Você deve especificar `--every` ou `--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`

Remove um agendamento pelo nome do handler.

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

| Opção | Descrição |
|---|---|
| `<handler>` | Nome do handler a remover (obrigatório) |

### `wp queuety schedule run`

Dispara manualmente uma execução do agendador. Enfileira jobs para todos os agendamentos vencidos.

```bash
wp queuety schedule run
```

## Comandos de registro

### `wp queuety log`

Consulta entradas de registro.

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

| Opção | Descrição |
|---|---|
| `--job=<id>` | Filtra por ID do job |
| `--workflow=<id>` | Filtra por ID do fluxo de trabalho |
| `--handler=<name>` | Filtra por nome do handler |
| `--event=<event>` | Filtra 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>` | Mostra entradas desde esta data e hora |
| `--limit=<n>` | Número máximo de entradas a mostrar (padrão: `50`) |
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

Os filtros não são combinados: Queuety aplica o primeiro filtro presente, nesta ordem: `--job`, `--workflow`, `--handler`, `--event`, `--since`. `--job` e `--workflow` retornam todas as entradas, da mais antiga para a mais recente, e ignoram `--limit`. `--handler` e `--event` retornam primeiro as entradas mais recentes. Sem um filtro, o comando consulta as últimas 24 horas; essa consulta e `--since` listam as entradas da mais antiga para a mais recente, então `--limit` mantém as entradas mais antigas do período.

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

### Limpeza dos registros

`LogCommand` define um subcomando `purge` (`wp queuety log purge --older-than=<days>`), mas WP-CLI registra `wp queuety log` como um único comando, portanto não é possível acessar o subcomando, que falha com o erro "Too many positional arguments: purge" ([#11](https://github.com/inline0/queuety/issues/11)). Em vez disso, remova as entradas de registro antigas de PHP:

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

## Comandos de webhook

### `wp queuety webhook add`

Registra um webhook URL para um evento.

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

| Opção | Descrição |
|---|---|
| `<event>` | Nome do evento: `job.completed`, `job.failed`, `job.buried` ou `workflow.failed` (obrigatório) |
| `<url>` | URL para enviar notificações por POST (obrigatório) |

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

### `wp queuety webhook list`

Lista todos os webhooks registrados.

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

| Opção | Descrição |
|---|---|
| `--format=<format>` | Formato de saída: `table` (padrão), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

Remove um webhook pelo ID.

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do webhook a remover (obrigatório) |