# CLI 참조

모든 Queuety 작업은 기본적으로 `wp queuety` 네임스페이스 아래의 WP-CLI을 통해 사용할 수 있습니다.

다른 루트 아래에 동일한 명령 트리를 게시하려면 Queuety가 부팅되기 전에 `QUEUETY_CLI_COMMAND`을 정의하세요. 예를 들어 `wp themequeue`를 사용할 수 있습니다.

에이전트 하네스 및 기타 가상 bash 통합에서는 이 페이지를 사람이 참고하는 문서로 보고, PHP 브리지를 기계용 계약으로 사용하세요:

- `Queuety::cli_command_map()`은 직렬화 가능한 명령 카탈로그를 제공합니다
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )`은 파싱된 `wp queuety ...` 입력을 정규화된 실행 계획으로 변환하며, 직접 PHP 호출 가능 항목을 우선합니다

이 트리에는 상태 머신 명령이 없습니다. [상태 머신](https://queuety.inline0.dev/ko/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` | 작업을 최대 하나만 처리한 후 종료합니다(처리 가능한 작업이 없으면 즉시 종료) |
| `--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`를 사용하면 동일한 명령 표면에서 적응형 확장이 활성화됩니다. 배포 전략은 [워커](https://queuety.inline0.dev/ko/docs/features/workers)를, 적응형 풀의 승인 모델은 [리소스 관리](https://queuety.inline0.dev/ko/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`

워크플로의 저장된 아티팩트 하나를 표시합니다.

```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` 상태가 아닌 워크플로를 취소합니다. 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
```

기록되는 내용과 사용 사례는 [워크플로 이벤트 로그](https://queuety.inline0.dev/ko/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
```

자세한 내용은 [시간 되감기](https://queuety.inline0.dev/ko/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.
```

자세한 내용은 [분기](https://queuety.inline0.dev/ko/docs/workflows/forking)를 참조하세요.

### `wp queuety workflow export`

워크플로의 전체 실행 기록을 JSON으로 내보냅니다. 워크플로 행, 작업, 워크플로 이벤트, 로그 항목, 저장된 신호, 워크플로 종속성 대기를 포함합니다.

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

| 옵션 | 설명 |
|---|---|
| `<id>` | 워크플로 ID(필수) |
| `--output=<file>` | JSON을 쓸 파일 경로입니다. 기본값은 stdout입니다. |

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

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

JSON 구조에 관한 자세한 내용은 [내보내기 및 재생](https://queuety.inline0.dev/ko/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/ko/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`

스케줄러 틱을 수동으로 실행합니다. 기한이 된 모든 일정의 작업을 큐에 넣습니다.

```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 );'
```

## 웹훅 명령

### `wp queuety webhook add`

이벤트에 대한 웹훅 URL을 등록합니다.

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

등록된 모든 웹훅을 나열합니다.

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

| 옵션 | 설명 |
|---|---|
| `--format=<format>` | 출력 형식: `table`(기본값), `json`, `csv`, `yaml` |

### `wp queuety webhook remove`

ID로 웹훅을 삭제합니다.

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

| 옵션 | 설명 |
|---|---|
| `<id>` | 삭제할 웹훅 ID(필수) |