# CLI リファレンス

すべてのQueuety操作は、既定で`wp queuety`名前空間のWP-CLIから利用できます。

別のルート名（たとえば`wp themequeue`）で同じコマンドツリーを公開するには、Queuetyの起動前に`QUEUETY_CLI_COMMAND`を定義してください。

エージェント用テストハーネスやその他の仮想bash統合では、このページを人が読むためのリファレンスとして扱い、機械向けの契約にはPHPブリッジを使ってください。

- `Queuety::cli_command_map()`はシリアライズ可能なコマンドカタログを公開します
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )`は解析済みの`wp queuety ...`入力を、直接PHP呼び出し可能オブジェクトを優先する正規化済み実行プランに変換します

このツリーにはステートマシンのコマンドはありません。[State Machines](https://queuety.inline0.dev/ja/docs/state-machines)で説明されているPHP APIから確認してください。

## ジョブコマンド

### `wp queuety work`

ジョブを処理するワーカーを起動します。

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

| オプション | 説明 |
|---|---|
| `--queue=<queue>` | 処理するQueue(s)。優先順位を指定する場合はカンマ区切りで記述します（既定値: `default`） |
| `--once` | ジョブを最大1件処理して終了します（取得可能なジョブがない場合も直ちに終了） |
| `--workers=<n>` | N個のワーカープロセスをフォークします（`pcntl`および`posix`の拡張が必要です。`--min-workers`と`--max-workers`も同様です） |
| `--min-workers=<n>` | 適応型プールの最小ワーカー数。`--max-workers`が必要です |
| `--max-workers=<n>` | 適応型プールの最大ワーカー数 |

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

複数のキューを指定すると、ワーカーは記載された順に各キューからジョブを取得しようとします。取得可能なジョブがある最初のキューが選ばれます。`--workers`はプールの規模を固定します。`--min-workers`と`--max-workers`を使うと、同じコマンドで適応型スケーリングが有効になります。デプロイ方法は[Workers](https://queuety.inline0.dev/ja/docs/features/workers)を、適応型プールの受け入れモデルは[Resource Management](https://queuety.inline0.dev/ja/docs/features/resource-management)を参照してください。

### `wp queuety flush`

保留中のジョブをすべて処理して終了します。

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

| オプション | 説明 |
|---|---|
| `--queue=<queue>` | フラッシュするQueue(s)。優先順位を指定する場合はカンマ区切りで記述します（既定値: `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`

コマンドラインからジョブをディスパッチします。

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

| オプション | 説明 |
|---|---|
| `<handler>` | ハンドラー名またはクラス（必須） |
| `--payload=<json>` | JSONペイロード（既定値: `{}`） |
| `--queue=<queue>` | キュー名（既定値: `default`） |
| `--priority=<priority>` | 優先度レベル 0-3（既定値: `0`） |
| `--delay=<seconds>` | 遅延秒数（既定値: `0`） |

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

### `wp queuety status`

キューの統計情報を表示します。

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

| オプション | 説明 |
|---|---|
| `--queue=<queue>` | キュー名で絞り込みます |

### `wp queuety list`

ジョブを一覧表示します。

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

| オプション | 説明 |
|---|---|
| `--queue=<queue>` | キューで絞り込みます |
| `--status=<status>` | ステータス（`pending`、`processing`、`completed`、`failed`、`buried`）で絞り込みます |
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

### `wp queuety inspect`

ペイロードやログ履歴を含む、ジョブの詳細をすべて表示します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ジョブID（必須） |

### `wp queuety retry`

指定したジョブを再試行します。

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

| オプション | 説明 |
|---|---|
| `<id>` | 再試行するジョブID（必須） |

### `wp queuety retry-buried`

埋没したジョブをすべて再試行します。

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

### `wp queuety bury`

ジョブを手動で埋没状態にします。

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

| オプション | 説明 |
|---|---|
| `<id>` | 埋没させるジョブID（必須） |

### `wp queuety delete`

ジョブを削除します。

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

| オプション | 説明 |
|---|---|
| `<id>` | 削除するジョブID（必須） |

### `wp queuety recover`

`processing`ステータスで停止している古いジョブを復旧します。

```bash
wp queuety recover
```

### `wp queuety purge`

完了済みのジョブを削除します。

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

| オプション | 説明 |
|---|---|
| `--older-than=<days>` | N日より古いジョブを削除します（既定値: `QUEUETY_RETENTION_DAYS`） |

### `wp queuety pause`

キューを一時停止し、ワーカーが処理をスキップするようにします。

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

| オプション | 説明 |
|---|---|
| `<queue>` | 一時停止するキュー名（必須） |

### `wp queuety resume`

一時停止中のキューを再開します。

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

| オプション | 説明 |
|---|---|
| `<queue>` | 再開するキュー名（必須） |

### `wp queuety metrics`

ハンドラーごとのメトリクスを表示します。

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

| オプション | 説明 |
|---|---|
| `--minutes=<minutes>` | 時間範囲（分）（既定値: `60`） |
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

### `wp queuety discover`

ディレクトリ内のハンドラークラスを検出します。

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

| オプション | 説明 |
|---|---|
| `<directory>` | ハンドラークラスを検索するディレクトリ（必須） |
| `<namespace>` | ディレクトリのPSR-4名前空間プレフィックス（必須） |
| `--register` | 検出したハンドラーを実際に登録します |

## ワークフローコマンド

### `wp queuety workflow status`

ワークフローのステータスと進行状況を表示します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |

`status`は、現在のステップ、任意のステップ名、バージョンやハッシュのメタデータ、待機モード、成果物の概要を表示します。シグナルまたは依存関係待ちでワークフローがブロックされている場合は、`WaitInfo` JSONのデータも表示します。

### `wp queuety workflow list`

ワークフローを一覧表示します。

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

| オプション | 説明 |
|---|---|
| `--status=<status>` | ステータスで絞り込みます: `running`、`completed`、`failed`、`paused`、`waiting_for_signal`、`waiting_for_workflows`、`cancelled` |
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

このコマンドは最大50件のワークフローを返します。`--limit`の値を読み取りますが、コマンドでフラグが宣言されていないため、WP-CLIは現在これを拒否します（[#12](https://github.com/inline0/queuety/issues/12)）。別の上限を指定するには`Queuety::list_workflows()`を使ってください。

既定のテーブルには`StepName`と`WaitMode`が含まれ、ブロック中のワークフローを見つけやすくなっています。

### `wp queuety workflow retry`

失敗したステップから、失敗したワークフローを再試行します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |

### `wp queuety workflow approve`

ワークフローに承認シグナルを送信します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--data=<json>` | 任意のJSONオブジェクトペイロード |
| `--signal=<name>` | 承認シグナル名を上書きします（既定値: `approval`。`wait_for_approval()`と一致します。`wait_for_decision()`ステップは既定で`approved`を待ち受けるため、そこでは`--signal=approved`を渡してください） |

### `wp queuety workflow reject`

ワークフローに拒否シグナルを送信します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--data=<json>` | 任意のJSONオブジェクトペイロード |
| `--signal=<name>` | 拒否シグナル名を上書きします（既定値: `rejected`） |

### `wp queuety workflow input`

ワークフローに構造化入力を送信します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--data=<json>` | 任意のJSONオブジェクトペイロード |
| `--signal=<name>` | 入力シグナル名を上書きします（既定値: `input`） |

### `wp queuety workflow artifacts`

ワークフローに保存された成果物を一覧表示します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--format=<format>` | 出力形式: `table`（既定値）または`json` |
| `--with-content` | 成果物の内容を出力に含めます |

### `wp queuety workflow artifact`

ワークフローに保存された成果物を1件表示します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `<key>` | 成果物キー（必須） |

### `wp queuety workflow pause`

実行中のワークフローを一時停止します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |

### `wp queuety workflow resume`

一時停止中のワークフローを再開します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |

### `wp queuety workflow cancel`

すでに`completed`または`cancelled`の状態でないワークフローをキャンセルします。1つのトランザクションで、Queuetyはステータスを`cancelled`に設定し、保留中および処理中のワークフロージョブを埋没させて`workflow_cancelled`を記録します。その後、補償処理と登録済みのクリーンアップハンドラーを実行します。

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

| オプション | 説明 |
|---|---|
| `<id>` | キャンセルするワークフローID（必須） |

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

### `wp queuety workflow timeline`

ワークフローのイベントタイムラインを表示します。開始、完了、失敗など、各ステップのイベントをタイムスタンプ、ハンドラー、所要時間とともに表示します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--limit=<limit>` | 返すイベントの最大数（既定値: `100`） |
| `--offset=<offset>` | 先行するイベントのスキップ数（既定値: `0`） |
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

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

出力列: `ID`、`Step`、`Event`、`Handler`、`Duration_ms`、`Error`、`Created_at`。

### `wp queuety workflow state-at`

特定のワークフローステップが完了または再開した後の、公開ワークフロー状態を表示します。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `<step>` | ステップインデックス、0始まり（必須） |

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

記録される内容と使用例については、[Workflow Event Log](https://queuety.inline0.dev/ja/docs/workflows/event-log)を参照してください。

### `wp queuety workflow rewind`

ワークフローを前のステップまで巻き戻し、その次のステップから再開します。指定したステップのイベントログ`state_after`から状態が復元され、次のステップ（`<step> + 1`）がキューに追加されます。指定したステップ自体は再実行されません。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `<step>` | 巻き戻し先のステップインデックス、0始まり（必須） |

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

詳しくは[Time Travel](https://queuety.inline0.dev/ja/docs/workflows/time-travel)を参照してください。

### `wp queuety workflow fork`

実行中のワークフローを現在の状態で独立したコピーに分岐します。分岐したワークフローには新しいIDが割り当てられ、独立して進行します。

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

| オプション | 説明 |
|---|---|
| `<id>` | 分岐元のワークフローID（必須） |

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

詳しくは[Forking](https://queuety.inline0.dev/ja/docs/workflows/forking)を参照してください。

### `wp queuety workflow export`

ワークフローの実行履歴全体をJSONにエクスポートします。ワークフロー行、ジョブ、ワークフローイベント、ログエントリ、保存済みシグナル、ワークフローの依存関係待ちが含まれます。

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--output=<file>` | JSONを書き込むファイルパス。既定では標準出力に出力します |

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

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

JSONの構造については[Export and Replay](https://queuety.inline0.dev/ja/docs/workflows/export-replay)を参照してください。

### `wp queuety workflow replay`

エクスポートしたワークフローをJSONファイルから再生します。エクスポート時の状態、メタデータ、過去のタイムラインを持つ新しいワークフローを作成します。

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

| オプション | 説明 |
|---|---|
| `<file>` | エクスポートしたJSONファイルのパス（必須） |

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

詳しくは[エクスポートとリプレイ](https://queuety.inline0.dev/ja/docs/workflows/export-replay)を参照してください。

## スケジュールコマンド

### `wp queuety schedule list`

すべての定期スケジュールを一覧表示します。

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

| オプション | 説明 |
|---|---|
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

### `wp queuety schedule add`

定期スケジュールを追加します。

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

| オプション | 説明 |
|---|---|
| `<handler>` | ハンドラー名またはクラス（必須） |
| `--every=<interval>` | 間隔の式（e.g、`1 hour`、`30 minutes`） |
| `--cron=<expression>` | Cron式（e.g、`0 3 * * *`） |
| `--payload=<json>` | JSONペイロード（既定値：`{}`） |
| `--queue=<queue>` | キュー名（既定値：`default`） |

`--every`または`--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`

ハンドラー名でスケジュールを削除します。

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

| オプション | 説明 |
|---|---|
| `<handler>` | 削除するハンドラー名（必須） |

### `wp queuety schedule run`

スケジューラーの処理を手動で1回実行します。期限が来たすべてのスケジュールのジョブをキューに追加します。

```bash
wp queuety schedule run
```

## ログコマンド

### `wp queuety log`

ログエントリを検索します。

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

| オプション | 説明 |
|---|---|
| `--job=<id>` | ジョブIDで絞り込みます |
| `--workflow=<id>` | ワークフローIDで絞り込みます |
| `--handler=<name>` | ハンドラー名で絞り込みます |
| `--event=<event>` | イベント種別（`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>` | 指定日時以降のエントリを表示します |
| `--limit=<n>` | 表示するエントリの最大数（既定値: `50`） |
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

フィルターは組み合わせられません。Queuetyは、`--job`、`--workflow`、`--handler`、`--event`、`--since`の順で最初に指定されたものを適用します。`--job`と`--workflow`はすべてのエントリを古い順に返し、`--limit`を無視します。`--handler`と`--event`は新しい順に返します。フィルターを指定しない場合、コマンドは過去24時間分のログを読み取ります。このクエリと`--since`は古い順にエントリを並べるため、`--limit`を指定すると対象期間内の古いエントリが残ります。

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

### ログの削除

`LogCommand`は`purge`サブコマンド（`wp queuety log purge --older-than=<days>`）を定義していますが、WP-CLIは`wp queuety log`を単独コマンドとして登録します。そのためサブコマンドを実行できず、"Too many positional arguments: purge"エラーになります（[#11](https://github.com/inline0/queuety/issues/11)）。代わりにPHPから古いログエントリを削除してください。

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

## Webhookコマンド

### `wp queuety webhook add`

イベントに対するWebhookURLを登録します。

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

| オプション | 説明 |
|---|---|
| `<event>` | イベント名: `job.completed`、`job.failed`、`job.buried`、`workflow.failed`のいずれか（必須） |
| `<url>` | 通知のPOST先となるURL（必須） |

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

### `wp queuety webhook list`

登録済みのWebhookをすべて一覧表示します。

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

| オプション | 説明 |
|---|---|
| `--format=<format>` | 出力形式: `table`（既定値）、`json`、`csv`、`yaml` |

### `wp queuety webhook remove`

IDでWebhookを削除します。

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

| オプション | 説明 |
|---|---|
| `<id>` | 削除するWebhook ID（必須） |