CLI 参考手册

以 Markdown 格式查看在 GitHub 上编辑文档位置 2cc7b2b

默认情况下，所有 Queuety 操作都可通过 WP-CLI 在 wp queuety 命名空间下使用。

如果要以不同根命令发布相同的命令树（例如 wp themequeue），请在 Queuety 启动之前定义 QUEUETY_CLI_COMMAND。

对于代理测试框架和其他 virtual-bash 集成，请将此页面作为人工参考，并使用 PHP 桥接作为机器接口：

Queuety::cli_command_map() 提供可序列化的命令目录
Queuety::resolve_cli_command( $path, $args, $assoc_args ) 将解析后的 wp queuety ... 输入转换为规范化执行计划，并优先使用直接的 PHP 可调用对象

此命令树中没有状态机命令；请通过状态机中介绍的 PHP API 检查状态机。

作业命令

`wp queuety work`

启动一个处理作业的工作进程。

命令行

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>`	自适应池的最大工作进程数

命令行

# 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 会为相同的命令启用自适应扩缩容。有关部署策略，请参阅工作进程；有关自适应池背后的准入模型，请参阅资源管理。

`wp queuety flush`

处理所有待处理的作业后退出。

命令行

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

选项	说明
`--queue=<queue>`	要清空的 Queue(s)，多个队列以逗号分隔并按优先级排序（默认：`default`）

命令行

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

从命令行分发作业。

命令行

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

命令行

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

`wp queuety status`

显示队列统计信息。

命令行

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

选项	说明
`--queue=<queue>`	按队列名称筛选

`wp queuety list`

列出作业。

命令行

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`

显示作业的完整详情，包括负载和日志历史记录。

命令行

wp queuety inspect <id>

选项	说明
`<id>`	作业 ID（必填）

`wp queuety retry`

重试指定作业。

命令行

wp queuety retry <id>

选项	说明
`<id>`	要重试的作业 ID（必填）

`wp queuety retry-buried`

重试所有已搁置的作业。

命令行

wp queuety retry-buried

`wp queuety bury`

手动搁置作业。

命令行

wp queuety bury <id>

选项	说明
`<id>`	要搁置的作业 ID（必填）

`wp queuety delete`

删除作业。

命令行

wp queuety delete <id>

选项	说明
`<id>`	要删除的作业 ID（必填）

`wp queuety recover`

恢复卡在 processing 状态的过期作业。

命令行

wp queuety recover

`wp queuety purge`

清除已完成的作业。

命令行

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

选项	说明
`--older-than=<days>`	删除超过 N 天的作业（默认：`QUEUETY_RETENTION_DAYS`）

`wp queuety pause`

暂停队列，使工作器跳过该队列。

命令行

wp queuety pause <queue>

选项	说明
`<queue>`	要暂停的队列名称（必填）

`wp queuety resume`

恢复已暂停的队列。

命令行

wp queuety resume <queue>

选项	说明
`<queue>`	要恢复的队列名称（必填）

`wp queuety metrics`

显示各处理器的指标。

命令行

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

选项	说明
`--minutes=<minutes>`	时间窗口，单位为分钟（默认：`60`）
`--format=<format>`	输出格式：`table`（默认）、`json`、`csv`、`yaml`

`wp queuety discover`

发现目录中的处理器类。

命令行

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

选项	说明
`<directory>`	要扫描处理器类的目录（必填）
`<namespace>`	该目录的 PSR-4 命名空间前缀（必填）
`--register`	实际注册发现的处理器

工作流命令

`wp queuety workflow status`

显示工作流状态和进度。

命令行

wp queuety workflow status <id>

选项	说明
`<id>`	工作流 ID（必填）

status 会显示当前步骤、可选的步骤名称、版本/哈希元数据、等待模式、工件摘要；如果工作流当前因信号或依赖项而阻塞，还会显示 WaitInfo JSON 数据块。

`wp queuety workflow list`

列出工作流。

命令行

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）；如需使用其他限制值，请使用 Queuety::list_workflows()。

默认表格包含 StepName 和 WaitMode，让你更容易查看受阻的工作流。

`wp queuety workflow retry`

从失败的步骤重试失败的工作流。

命令行

wp queuety workflow retry <id>

选项	说明
`<id>`	工作流 ID（必填）

`wp queuety workflow approve`

向工作流发送批准信号。

命令行

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`

向工作流发送拒绝信号。

命令行

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

选项	说明
`<id>`	工作流 ID（必填）
`--data=<json>`	可选的 JSON 对象负载
`--signal=<name>`	覆盖拒绝信号名称（默认：`rejected`）

`wp queuety workflow input`

向工作流发送结构化输入。

命令行

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

选项	说明
`<id>`	工作流 ID（必填）
`--data=<json>`	可选的 JSON 对象负载
`--signal=<name>`	覆盖输入信号名称（默认：`input`）

`wp queuety workflow artifacts`

列出工作流中存储的工件。

命令行

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

选项	说明
`<id>`	工作流 ID（必填）
`--format=<format>`	输出格式：`table`（默认）或 `json`
`--with-content`	在输出中包含工件内容

`wp queuety workflow artifact`

显示工作流中存储的某个工件。

命令行

wp queuety workflow artifact <id> <key>

选项	说明
`<id>`	工作流 ID（必填）
`<key>`	工件键（必填）

`wp queuety workflow pause`

暂停正在运行的工作流。

命令行

wp queuety workflow pause <id>

选项	说明
`<id>`	工作流 ID（必填）

`wp queuety workflow resume`

恢复已暂停的工作流。

命令行

wp queuety workflow resume <id>

选项	说明
`<id>`	工作流 ID（必填）

`wp queuety workflow cancel`

取消尚未处于 completed 或 cancelled 状态的工作流。Queuety 会在同一事务中将状态设为 cancelled，将该工作流待处理和正在处理的作业移入搁置状态，并记录日志 workflow_cancelled；随后运行补偿逻辑和任何已注册的清理处理器。

命令行

wp queuety workflow cancel <id>

选项	说明
`<id>`	要取消的工作流 ID（必填）

命令行

wp queuety workflow cancel 42

`wp queuety workflow timeline`

显示工作流的事件时间线。展示所有步骤事件（已启动、已完成、已失败），以及时间戳、处理器和持续时间。

命令行

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`

命令行

wp queuety workflow timeline 42

输出列：ID、Step、Event、Handler、Duration_ms、Error、Created_at。

`wp queuety workflow state-at`

显示特定工作流步骤完成或恢复后的公开工作流状态。

命令行

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

选项	说明
`<id>`	工作流 ID（必填）
`<step>`	步骤索引，从 0 开始（必填）

命令行

wp queuety workflow state-at 42 0

有关记录内容和适用场景的详情，请参阅工作流事件日志。

`wp queuety workflow rewind`

将工作流回退到之前的步骤，并从该步骤之后继续执行。状态会从指定步骤的事件日志 state_after 中恢复，并将下一步骤（<step> + 1）加入队列；指定步骤本身不会重新运行。

命令行

wp queuety workflow rewind <id> <step>

选项	说明
`<id>`	工作流 ID（必填）
`<step>`	要回退到的步骤索引，从 0 开始（必填）

命令行

wp queuety workflow rewind 42 1

详情请参阅时间旅行。

`wp queuety workflow fork`

将正在运行的工作流分叉为一个基于当前状态的独立副本。分叉后的工作流会获得新的 ID，并独立继续运行。

命令行

wp queuety workflow fork <id>

选项	说明
`<id>`	要分叉的工作流 ID（必填）

命令行

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

详情请参阅分叉。

`wp queuety workflow export`

将工作流的完整执行历史导出到 JSON。包括工作流行、作业、工作流事件、日志条目、存储的信号以及工作流依赖项等待记录。

命令行

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

选项	说明
`<id>`	工作流 ID（必填）
`--output=<file>`	写入 JSON 的文件路径。默认为标准输出。

命令行

# Print to stdout
wp queuety workflow export 42

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

有关 JSON 结构的详情，请参阅导出和重放。

`wp queuety workflow replay`

从 JSON 文件重放已导出的工作流。创建一个具有已导出状态、元数据和历史时间线的新工作流。

命令行

wp queuety workflow replay <file>

选项	说明
`<file>`	已导出的 JSON 文件路径（必填）

命令行

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

详情请参阅导出与重放。

调度命令

`wp queuety schedule list`

列出所有定期计划。

命令行

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

选项	说明
`--format=<format>`	输出格式：`table`（默认）、`json`、`csv`、`yaml`

`wp queuety schedule add`

添加定期计划。

命令行

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。

命令行

wp queuety schedule add cleanup_handler --every="1 hour"
wp queuety schedule add nightly_report --cron="0 3 * * *" --queue=reports

`wp queuety schedule remove`

按处理器名称移除计划。

命令行

wp queuety schedule remove <handler>

选项	说明
`<handler>`	要移除的处理器名称（必填）

`wp queuety schedule run`

手动触发一次调度器运行。为所有到期计划加入作业队列。

命令行

wp queuety schedule run

日志命令

`wp queuety log`

查询日志条目。

命令行

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 会保留时间窗口中最早的条目。

命令行

# 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）。改用 PHP 清除旧日志条目：

命令行

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

Webhook 命令

`wp queuety webhook add`

为某个事件注册一个 webhook URL。

命令行

wp queuety webhook add <event> <url>

选项	说明
`<event>`	事件名称：`job.completed`、`job.failed`、`job.buried` 或 `workflow.failed`（必填）
`<url>`	用于 POST 通知的 URL（必填）

命令行

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

`wp queuety webhook list`

列出所有已注册的 webhook。

命令行

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

选项	说明
`--format=<format>`	输出格式：`table`（默认）、`json`、`csv`、`yaml`

`wp queuety webhook remove`

按 ID 移除 webhook。

命令行

wp queuety webhook remove <id>

选项	说明
`<id>`	要移除的 Webhook ID（必填）