Flows 命令

流程是您在 Flow & Paywall Builder 中构建的付费墙和用户引导。CLI 负责管理流程记录、其编辑工具配置、发布状态以及版本历史。编辑工具配置是一个大型 JSON 文档,通常由 Flow & Paywall Builder 生成,CLI 本身不会自动创建。如需通过终端编写或修改配置,请使用 flow-generator 技能,它会替您驱动这些命令。在发布前,flow-audit 技能会检查流程是否已准备好上线。flows metrics 命令用于读取流程数据图表页面上的数据,需要 CLI 0.15.0 或更高版本。flows funnel 命令用于读取流程漏斗,需要 CLI 0.19.0 或更高版本。以下命令仅供参考。

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、published_flow_version_id 和 updated_at。published_flow_version_id 是当前上线版本的 ID,若该流程从未发布则为 null。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 get --app <app-id> <flow-id> --json > flow.json
adapty flows config update --app <app-id> <flow-id> --file flow.json
参数描述
flow-id流程 ID(UUID)
参数是否必填描述
--app是应用 ID(UUID)
--file代替 --config、--config-file 和 --remote-configs包含 config 和 remote_configs 的 JSON 文件路径,或 - 表示从 stdin 读取。flows config get --json 的输出可直接使用,其他键将被忽略
--config不使用 --file 时:--config 和 --config-file 二选一以 JSON 字符串形式提供的编辑工具配置
--config-file不使用 --file 时:--config 和 --config-file 二选一包含编辑工具配置的 JSON 文件路径,或 - 表示从 stdin 读取
--remote-configs不使用 --file 时由 {locale, data} 条目组成的 JSON 数组,其中 data 为字符串形式的远程配置。传入 [] 将删除所有远程配置
--expected-updated-at否先前执行 flows config get 时获取的 updated_at 值。若在该次读取之后配置已发生变更,命令将报错而非覆盖变更。省略此参数则无条件覆盖

写入操作会替换配置及全部远程配置列表。若要保留现有远程配置,请从 flows config get --json 的输出中取出 remote_configs 字段一并传入。不使用 --file 时,命令需要同时提供 config 和 --remote-configs:缺少其中任一项,命令将以退出码 2 终止,且不会发送任何请求。--file 标志及必填的 --remote-configs 需要 CLI 0.20.0 或更高版本。

如需为新流程写入第一个配置,请传入空的远程配置列表:

adapty flows config update --app <app-id> <flow-id> --config-file config.json --remote-configs '[]'

保存配置会创建草稿,而不会直接发布。对于已发布的流程,写入操作会创建新版本:流程状态变为 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
--deviceiphone-14渲染所用的设备框架
--orientationportraitportrait 或 landscape

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

adapty flows media upload

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

adapty flows media upload --app <app-id> ./hero.png
参数说明
file图片文件路径
标志必填说明
--app是App ID(UUID)

支持的格式:PNG、JPEG、WebP 和 SVG。响应中包含图片的 id、name 以及可在配置中引用的 CDN url。如需上传视频,请使用 flows media upload-video。

adapty flows media upload-video

上传视频以在流程配置中使用。

adapty flows media upload-video --app <app-id> ./intro.mp4
参数说明
file视频文件路径
标志是否必填说明
--app是App ID(UUID)

支持的格式:MP4 和 WebM。视频时长不得超过 30 秒,文件大小不得超过 50 MB,宽度和高度均不得小于 640 像素。不支持 GIF,该命令也不会将动图转换为视频。

响应中包含视频 URL(HLS 播放列表)、预览图片 URL,以及视频的 width 和 height。在配置中,视频元素通过 videoUrl、previewUrl、width 和 height 来接收这些值。

adapty flows versions list

列出某个流程的所有版本,按从新到旧排序。这些版本来自 Flow & Paywall Builder 中的版本历史。

adapty flows versions list --app <app-id> <flow-id>
参数说明
flow-id流程 ID(UUID)
标志是否必填说明
--app是App ID(UUID)
--search否仅显示标题包含指定文本的版本。不区分大小写,支持部分匹配:friday 可匹配 Black Friday

每行显示版本的标题、状态、日期和 ID。标题是版本名称,若版本无名称则显示为 Version N。状态的含义如下:

状态含义
draft正在编辑的版本。一个流程只有一个草稿,也可能没有草稿。草稿发布过程中,该行末尾会显示 Publishing…;发布失败后则显示 Publish failed
live用户当前看到的版本
previous较早的版本。它之前曾是正式版本,或在发布前被更新的版本所替代

live 或 previous 版本的日期是其发布开始的日期。对于草稿,以及从未发布过的 previous 版本,日期为该版本的创建日期。

对于从未发布过的流程,该命令会打印 History will appear after the first publish.,并在其下方显示草稿行。看板中的版本历史不会为此类流程显示任何行。当没有版本与 --search 匹配时,该命令会打印 No versions match the search.

该命令始终列出所有版本,不支持分页参数。

使用 --json 时,命令将原样输出 Adapty 返回的 {data, meta},其中 data 包含各行数据。每行包含以下字段:flow_version_id、version、name、title、state、is_current、publication_status、published_at、created_at、updated_at 和 last_edited_by。updated_at 是该版本最后一次内容变更的毫秒级时间戳:将草稿的 updated_at 值作为 --expected-updated-at 参数传入 flows versions restore。last_edited_by 表示最后修改该版本的用户名,若 Adapty 无法识别该用户,则值为 null。

adapty flows versions get

读取某个流程的指定版本。读取操作不会更改任何内容:草稿和上线版本均保持不变。

该命令会输出版本的标题、ID、编号、状态、日期、最后修改人以及 Test on device 链接。版本的完整内容(包含所有布局的编辑器配置、远程配置和付费墙)可通过 --json 输出,或保存到 --output 指定的文件中。

adapty flows versions get --app <app-id> <flow-id> <version-id> --output version.json
参数描述
flow-id流程 ID(UUID)
version-id版本 ID(UUID),来自 flows versions list
标志是否必填描述
--app是应用 ID(UUID)
--output否将该版本的完整内容以 JSON 格式写入此文件
--yes, -y否覆盖已存在的 --output 文件时无需确认。在使用 --json 或通过管道传输时,若文件已存在则必须指定此标志

如果 CLI 无法写入 --output 文件(例如目标文件夹不存在),命令会打印 Could not write <path> (<errno>). 并以退出码 1 退出。

adapty flows versions preview

打印某个版本的 Test on device 链接。在测试设备上打开该链接,即可在 Adapty 移动应用中预览该版本。草稿版本、线上版本或历史版本均可使用。

adapty flows versions preview --app <app-id> <flow-id> <version-id>
参数描述
flow-id流程 ID(UUID)
version-id版本 ID(UUID)
标志是否必填描述
--app是应用 ID(UUID)

adapty flows versions rename

重命名某个版本。你可以重命名草稿版本、线上版本以及历史版本。

adapty flows versions rename --app <app-id> <flow-id> <version-id> --name "Black Friday"
参数描述
flow-id流程 ID(UUID)
version-id版本 ID(UUID)
标志是否必填描述
--app是应用 ID(UUID)
--name是新版本名称。传入 --name "" 可移除名称,版本将重新显示为 Version N。仅包含空格的名称同样会移除名称

该命令会输出版本 ID 和新标题。Adapty 会自动去除名称两端的空格。两个版本可以拥有相同的名称。重命名不会更改版本内容或其 updated_at 时间戳,因此不会与后续保存草稿的操作产生冲突。

adapty flows versions restore

将某个版本恢复为同一流程的草稿,即版本历史中的 Duplicate as draft 功能。恢复后的版本在你发布之前不会对用户生效。

Tip

恢复操作会替换当前草稿。如需保留草稿,请先通过 flows duplicate 将其复制为新流程。

adapty flows versions restore --app <app-id> <flow-id> <version-id>
参数描述
flow-id流程 ID(UUID)
version-idlive 或 previous 版本的版本 ID(UUID)
标志是否必填描述
--app是应用 ID(UUID)
--expected-updated-at使用 --yes 且流程存在草稿时草稿的 updated_at 值,来自 flows versions list --json。若在读取之后草稿发生了变更,命令将报错而非覆盖该变更
--yes, -y否直接替换草稿,不询问确认。在流程存在草稿时,使用 --json 或通过管道运行时为必填

该命令首先读取流程的版本:

  • 流程没有草稿:该命令不会询问任何内容。Adapty 会使用下一个版本号创建一个新草稿,不含名称,内容与该版本完全相同。正式版本和您要恢复的版本保持不变。
  • 流程已有草稿:该命令会提示 Replace the draft '<draft>' (last change <time> by <user>) with '<version>'? To keep the draft, duplicate it to a new flow first.,然后提示 Apply? [y/N]。如果您输入 y,草稿将保留其 ID、编号和名称,并获取该版本的内容。不会新增任何版本。输入其他任何内容则以退出码 1 退出,不发送任何内容。

使用 --json、在管道中运行或无终端时,命令无法交互询问。当流程存在草稿时,除非传入 --yes,否则命令不发送任何内容并以退出码 6 退出。其提示信息会抛出问题,并附上 To replace it, re-run with --yes --expected-updated-at <ms> (the draft's updated_at).,其中 <ms> 替换为该草稿的 updated_at 值。使用 --yes 时,还需同时传入 --expected-updated-at:若未传入,命令将以退出码 6 退出且不发送任何内容。在终端中若未传入 --expected-updated-at,命令会从它在问题中展示给你的草稿中自动取用 updated_at 值。

恢复操作完成后,命令会打印 Restored '<version>' as the draft '<draft>' (<draft-id>). Nothing is published.

在以下情况下,Adapty 会拒绝恢复操作,不做任何更改。命令会打印 Adapty 的提示信息,对部分情况给出处理建议,并以退出码 4 退出:

消息处理方式
This flow version is already the current draft.请选择其他版本。
Flow version does not exist.该版本 ID 不在此流程的版本列表中。请从 flows versions list 获取 ID。
Flow version is already being published.等待发布完成后再执行恢复操作。
This flow version uses deleted products: …请选择未使用已删除产品的版本。
This flow configuration was already updated by …有团队成员在你读取草稿后对其进行了修改。请重新列出版本并重试。
Flow is deleted.该流程已归档。请先在看板中从归档中恢复。

adapty flows duplicate

复制一个流程或其某个版本,生成新流程。对应付费墙编辑工具顶部操作按钮中的 Duplicate flow(详见复制流程),以及版本历史中的 Duplicate as new flow。

adapty flows duplicate --app <app-id> <flow-id> --version <version-id>
参数说明
flow-id流程 ID(UUID)
标志是否必填描述
--app是应用 ID(UUID)
--version否要复制的版本 ID(UUID),可从 flows versions list 获取。任意版本均可复制,包括草稿。若不指定,则复制草稿;如果该流程没有草稿,则复制线上版本

该命令会输出 New flow '<name>' (<flow-id>), not published.。新流程以源流程命名,末尾附加 _copy。新流程处于未发布状态,包含一个以该版本内容为基础的草稿。源流程、其草稿及历史记录保持不变。在流程发布过程中也可进行复制操作。

如果版本使用了已删除的产品,或源流程已归档,Adapty 将拒绝复制。错误提示与 flows versions restore 的提示相同。

adapty flows metrics list

显示多个流程的生命周期数据,每个流程占一行。这是看板中流程表格的数据。

adapty flows metrics list --app <app-id> --ids <flow-id>,<flow-id>
参数是否必填描述
--app是App ID(UUID)
--ids是流程 ID(UUID)。多个 ID 用逗号分隔,或重复使用该参数
--csv否以 CSV 格式输出:每个流程占一行,包含流程 ID 和全部 27 个数据指标。不能与 --json 同时使用

每行显示流程 ID 及其浏览量、购买量、试用量和收入。--json 和 --csv 包含 流程数据图表 页面中全部 27 个数据指标,例如 unique_profiles_views、net_revenue 和 conversion_rate_purchases。若某项指标无数据,则显示 0,而非 null。对于从未发布过的流程,该命令会在表格下方打印 <flow-id>: No data: the flow was never published.。使用 --json 时,会在该流程的行中添加 note: "never_published";使用 --csv 时,提示信息会输出到 stderr,以保持 CSV 文件的整洁。

adapty flows metrics values

列出流程的筛选键和值:即 flows metrics get --filter 所接受的内容。

adapty flows metrics values --app <app-id> <flow-id>
参数说明
flow-id流程 ID(UUID)
标志是否必填说明
--app是应用 ID(UUID)

每行显示一个标签,括号内为实际传入的值。值的层级结构与看板筛选器的嵌套结构一致:

Country (country)
  Americas (Americas)
    United States (US)
  Europe (Europe)
    Germany (DE)
Store (store)
  App Store (app_store)
  Google Play (play_store)

每个分组的顶部值是筛选键,最内层的值是该键接受的参数。例如,--filter country=US 保留美国数据,--filter store=play_store 保留 Google Play 数据。

adapty flows metrics get

显示某个流程在指定时间段内的数据指标,以流程数据图表页面的树状结构呈现。

adapty flows metrics get --app <app-id> <flow-id> --date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --based-on placement
参数描述
flow-id流程 ID(UUID)
参数是否必填描述
--app是应用 ID(UUID)
--based-on是树状结构第一层的分组依据:placement 或 audience。对应流程数据图表页面中基于版位和基于目标受众的视图
--date-type是时间段所应用的日期类型:purchase_date 或 profile_install_date(按安装日期筛选)
--date-from否时间段起始日期(含当天,格式 YYYY-MM-DD)。需与 --date-to 一起使用
--date-to否时间段结束日期(含当天,格式 YYYY-MM-DD)。需与 --date-from 一起使用
--granularity否将时间段拆分为时间点:day、week、month、quarter 或 year
--filter否仅保留指定筛选键值的数据,可重复使用。详见筛选数据图表
--timezone否时间段所用的 IANA 时区,例如 Europe/Berlin。若不指定,Adapty 将使用应用所设时区
--depth否在 Total 下打印的树状层级数,默认值为 1
--csv否以 CSV 格式输出:树中每个节点对应一行。不可与 --json 同时使用

对于从未发布过的流程,该命令会在数据上方打印提示信息 No data: the flow was never published.,--json 模式下会附加 note: "never_published"。使用 --csv 时,提示信息会输出到 stderr,以保持 CSV 数据的整洁。

如需查看某个流程的收入,请运行 adapty analytics chart --app <app-id> --chart revenue --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --filter flow_id=<flow-id>。详见分析命令。

当 --based-on 或 --date-type 缺失,或仅提供了时间范围的一端时,CLI 以退出码 2 退出且不发送任何请求。Adapty 会验证 --based-on、--date-type 和 --granularity 的值:值有误时以退出码 4 退出,并在错误信息中列出可接受的值。

读取输出

该命令会先打印一行 Total,然后在其下显示树形结构的第一层。每行包含浏览量、购买数、试用数和收入。使用 --granularity 后,各时间周期的数据点会直接显示在对应节点下方:

Total           views 19  purchases 7  trials 4  revenue 241.93
  Onboarding    views 10  purchases 7  trials 0  revenue 241.93
    2026-09-01  views  0  purchases 0  trials 0  revenue   0.00
    2026-10-01  views 10  purchases 0  trials 0  revenue 241.93
  Settings      views  0  purchases 0  trials 0  revenue   0.00

树的层级与看板层级一致:版位、目标受众、A/B 测试、流程变体、屏幕和产品。使用 --based-on audience 时,版位层级会被省略。要显示更多层级,请传入 --depth 参数,例如 --depth 3。

要获取包含全部 27 个数据图表的完整树,请使用以下标志之一:

  • --json 原样输出服务器的响应内容。
  • --csv 为每个节点输出一行(包含各时间段的数据点)。各列依次为 path(从 Total 到该节点的标题,以 > 分隔)、level、title,以及各数据图表。

筛选数据图表

每个 --filter 的格式为 key=value,键和值的具体内容请参见 flows metrics values。若需保留多个值,可用逗号分隔,或使用相同的键多次传入该标志。不同键的筛选条件会组合生效,数据必须满足所有条件:

adapty flows metrics get --app <app-id> <flow-id> --date-from 2026-09-01 --date-to 2026-10-21 \
  --date-type purchase_date --based-on placement --filter country=US,DE --filter store=app_store

CLI 会将每个值按原样发送。若要在值中包含逗号,请使用 \,。空值也是有效值:attribution_channel= 会保留不含渠道的数据,在 flows metrics values 中显示为 No Data。

adapty flows funnel values

列出流程漏斗的筛选键和值:即 flows funnel get --filter 所接受的参数。

adapty flows funnel values --app <app-id> <flow-id>
参数描述
flow-id流程 ID(UUID)
标志是否必填描述
--app是应用 ID(UUID)

输出格式与 flows metrics values 相同。

adapty flows funnel get

显示用户离开流程的页面:某一流程版本的漏斗数据,按步骤和页面逐一展示,与流程的漏斗标签页内容一致。

adapty flows funnel get --app <app-id> <flow-id> --date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date
参数描述
flow-id流程 ID(UUID)
参数必填说明
--app是应用 ID(UUID)
--date-from是时间段的起始日期(含)(YYYY-MM-DD),基于 --timezone 指定的时区或应用时区
--date-to是时间段的结束日期(含)(YYYY-MM-DD),基于 --timezone 指定的时区或应用时区
--date-type是时间段所对应的日期类型:purchase_date 或 profile_install_date
--flow-version-id否要读取的流程版本 ID(UUID)。若不指定,CLI 将读取已发布的版本
--filter否仅保留指定过滤键值的用户,格式为 key=value,可重复使用。键和值来自 flows funnel values,用法与筛选数据图表一致
--timezone否日期所使用的 IANA 时区,例如 Europe/Berlin。若不指定,Adapty 将使用应用时区
--csv否输出看板下载格式的 CSV 文件,总计行排在最前。不可与 --json 同时使用

该命令会输出流程版本和时间段、一行摘要以及一张数据表。摘要显示进入流程的用户数、完成流程的用户数、流失率和收入。数据表中每个步骤占一行,列名分别为 Step、Type、Reached、Completed、Drop rate 和 Revenue。包含多个屏幕的步骤还会为每个屏幕单独列一行。不适用的值(例如用户引导屏幕的收入)显示为 —。

当所选时间段内没有用户进入该流程时,表格会以零值列出该版本的各个屏幕。对于答案的每个字段,请使用 --json。

接下来

  • 命令参考 — 每个 CLI 主题、全局标志和分页标志。
  • 流程版本历史 — 在流程与付费墙编辑工具中查看相同的版本记录。