Flows 命令

流程（Flows）是你在 Flow & Paywall Builder 中构建的付费墙和用户引导。CLI 负责管理流程记录、其 Builder 配置以及发布操作。Builder 配置是一个大型 JSON 文档，通常由 Flow & Paywall Builder 生成，CLI 本身不会生成该文档。如需在终端中编写或编辑配置，请使用 flow-generator 技能，它会代你驱动这些命令。在发布之前，flow-audit 技能会检查流程是否已准备好投入生产。以下命令仅供参考。

adapty flows list

列出某个应用的所有流程。

adapty flows list --app <app-id>

标志	是否必填	描述
`--app`	是	应用 ID（UUID）

支持分页标志。

adapty flows get

获取指定流程的详细信息。

adapty flows get --app <app-id> <flow-id>

参数	描述
`flow-id`	流程 ID（UUID）

标志	必填	描述
`--app`	是	应用 ID（UUID）

响应包含 id、name、status 和 updated_at。status 的值为以下之一：

状态	含义
`draft`	流程从未发布过
`published`	当前版本已上线
`dirty`	流程曾经发布过，但当前版本有未发布的更改。用户看到的仍是上次发布的版本
`publishing`	正在发布中
`publication_failed`	上次发布失败。请修复配置后重新发布
`archived`	流程已归档

adapty flows create

创建一个流程。新流程只有名称，没有配置。如需添加配置，请使用 flows config update。

adapty flows create --app <app-id> --name "Onboarding"

参数	是否必填	说明
`--app`	是	App ID（UUID）
`--name`	是	流程名称

adapty flows update

重命名流程。

adapty flows update --app <app-id> <flow-id> --name "Onboarding v2"

参数	描述
`flow-id`	流程 ID（UUID）

标志	是否必填	描述
`--app`	是	应用 ID（UUID）
`--name`	是	新流程名称

adapty flows publish

将当前版本的流程发布给用户。

adapty flows publish --app <app-id> <flow-id>

参数	描述
`flow-id`	流程 ID（UUID）

标志	必填	描述
`--app`	是	应用 ID（UUID）
`--yes`, `-y`	否	发布时不要求确认。当输出被管道传输或使用 `--json` 时必填

由于发布操作会影响用户所看到的内容，该命令会打印流程名称并要求确认。除 y 以外的任何回答都会取消命令并以退出码 1 结束。在 --json 模式或管道中，命令会拒绝执行并以退出码 2 退出，而不是等待输入，因此在脚本和 Agent 会话中请传入 --yes。

发布操作是异步的：响应会返回 status: publishing，此时流程尚未上线。请轮询 flows get，直到状态变为 published 或 publication_failed。若状态为 publication_failed，可通过 flows config get 查看失败原因。

当流程没有配置、配置不可发布或当前版本已上线时，发布操作会返回 HTTP 400 错误。如需在发布前校验配置，请使用 flows config validate。

adapty flows config get

读取流程的编辑器配置。

adapty flows config get --app <app-id> <flow-id>

参数	描述
`flow-id`	流程 ID（UUID）

标志	是否必填	描述
`--app`	是	应用 ID（UUID）

响应包含 config、remote_configs、status 和 updated_at。updated_at 是最后一次配置变更的毫秒级时间戳。将其作为 --expected-updated-at 传入 flows config update，可避免覆盖并发编辑。如果某个流程的配置从未写入，则返回 404。

发布尝试完成后，响应还会包含三个描述发布结果的字段。当 flows get 报告 publication_failed 时，请读取这些字段：

字段	描述
`publication_status`	当前流程版本的发布进度：`transforming`、`transformed`、`uploading`、`uploaded`、`published` 或 `failed`
`transform_error`	原始转换失败信息——可以是列出问题的 JSON 负载，也可以是摘要字符串
`publication_error`	发布失败时的可读错误消息

adapty flows config update

写入流程的编辑工具配置。

adapty flows config update --app <app-id> <flow-id> --config-file config.json

参数	描述
`flow-id`	流程 ID（UUID）

参数	是否必填	描述
`--app`	是	App ID（UUID）
`--config`	二选一	编辑工具配置，以 JSON 字符串形式传入
`--config-file`	二选一	指向包含编辑工具配置的 JSON 文件路径，或传入 `-` 以从 stdin 读取
`--remote-configs`	否	`{locale, data}` 条目组成的 JSON 数组，其中 `data` 为字符串形式的远程配置
`--expected-updated-at`	否	上次执行 `flows config get` 时返回的 `updated_at` 值。若配置在该次读取之后发生了变更，命令将报错而不会覆盖更改。不传此参数则无条件覆盖

保存配置会创建草稿，而不会直接发布。对于已发布的流程，写入操作会创建新版本：流程状态变为 dirty，在你执行 flows publish 之前，用户看到的仍是已发布的版本。

adapty flows config validate

检查某个编辑器配置是否可发布，无需保存。

adapty flows config validate --app <app-id> <flow-id> --config-file config.json

参数	描述
`flow-id`	流程 ID（UUID）

标志	是否必填	描述
`--app`	是	应用 ID（UUID）
`--config`	二选一	JSON 字符串格式的编辑器配置
`--config-file`	二选一	包含编辑器配置的 JSON 文件路径，或使用 `-` 从标准输入读取

响应中包含 valid 字段和 issues 列表。当配置不可发布时，命令会以退出码 1 退出，因此脚本可以据此进行条件判断。

adapty flows config preview

在浏览器中渲染本地配置文件。此命令不发起任何 API 调用，也不接受 --app 标志。

adapty flows config preview ./config.json --screen <screen-id> --device iphone-14 --orientation portrait

参数	描述
`config-file`	本地构建器配置 JSON 文件的路径

标志	默认值	描述
`--screen`	流程的第一个屏幕	要渲染的屏幕 ID
`--device`	`iphone-14`	渲染所用的设备框架
`--orientation`	`portrait`	`portrait` 或 `landscape`

在终端中，该命令会在浏览器中打开预览。当通过管道传输或使用 --json 时，它会打印 URL 而非打开浏览器。该 URL 包含完整配置，因此较长：建议将其传入截图工具，而非直接打印。超过约 32 KB 的配置渲染速度会较慢。

adapty flows media upload

上传图片以用于流程配置。

adapty flows media upload --app <app-id> ./hero.png

参数	描述
`file`	图片文件路径

标志	是否必填	描述
`--app`	是	App ID（UUID）

支持的格式：GIF、HEIC、JPEG、PNG、SVG 和 WebP。响应中包含图片的 id、name 以及用于在配置中引用的 CDN url。

下一步

命令参考 — 所有 CLI 主题、全局标志和分页标志。