Adapty 开发者 CLI 命令参考

本文列出了用于配置账户的 Adapty CLI 命令，涵盖应用、访问等级、产品、付费墙、流程、版位和市场细分，并介绍了各命令的参数、标志及可接受值。关于 Apple Ads 广告系列，请参阅 Ads Manager 命令。

关于身份验证设置和令牌管理，请参阅身份验证。

全局标志

这些标志适用于所有命令。

标志	描述
`--json`	以 JSON 格式输出，而非格式化文本
`--help`	显示命令帮助

所有 list 命令还接受分页标志：

标志	默认值	描述
`--page`	`1`	页码
`--page-size`	`20`	每页条目数（最大：100）

应用

管理 Adapty 账户中的应用。有关基于看板的配置，请参阅 App settings。

adapty apps list

列出 Adapty 账户中的所有应用。

adapty apps list

接受分页标志。

adapty apps get

获取特定应用的详细信息。

adapty apps get <app-id>

参数	描述
`app-id`	应用 ID（UUID）

adapty apps create

创建新应用。

adapty apps create --title "My App" --platform ios --apple-bundle-id com.example.app

标志	是否必填	描述
`--title`	是	应用标题
`--platform`	是	平台：`ios` 或 `android`。重复使用以支持两者：`--platform ios --platform android`
`--apple-bundle-id`	与 `--platform ios` 一起使用时必填	Apple bundle ID
`--google-bundle-id`	与 `--platform android` 一起使用时必填	Google bundle ID

adapty apps update

更新现有应用。

adapty apps update <app-id> --title "New Name"

参数	描述
`app-id`	应用 ID（UUID）

标志	描述
`--title`	新的应用标题
`--apple-bundle-id`	新的 Apple bundle ID
`--google-bundle-id`	新的 Google bundle ID

至少需要一个标志。--platform 在创建后无法更改。

访问等级

adapty access-levels list

列出应用的所有访问等级。

adapty access-levels list --app <app-id>

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

接受分页标志。

adapty access-levels get

获取特定访问等级的详细信息。

adapty access-levels get --app <app-id> <access-level-id>

参数	描述
`access-level-id`	访问等级 ID（UUID）

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

adapty access-levels create

创建新的访问等级。

adapty access-levels create --app <app-id> --sdk-id "pro" --title "Pro"

标志	是否必填	描述
`--app`	是	应用 ID（UUID）
`--sdk-id`	是	应用代码中用于检查访问权限的标识符（例如 `"pro"` 或 `"premium"`）
`--title`	是	Adapty 看板中的显示标签

adapty access-levels update

更新现有访问等级。

adapty access-levels update --app <app-id> <access-level-id> --title "Pro Access"

参数	描述
`access-level-id`	访问等级 ID（UUID）

标志	是否必填	描述
`--app`	是	应用 ID（UUID）
`--title`	是	新的显示标签

--sdk-id 在创建后无法更改。

产品

adapty products list

列出应用的所有产品。

adapty products list --app <app-id>

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

接受分页标志。

adapty products get

获取特定产品的详细信息。

adapty products get --app <app-id> <product-id>

参数	描述
`product-id`	产品 ID（UUID）

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

adapty products create

创建新产品。

Important

商店产品和价格 ID 在创建后无法更改。如需使用不同的商店 ID，请创建新产品。

adapty products create --app <app-id> --title "Monthly" --access-level-id <access-level-id> --period monthly --ios-product-id com.example.monthly

参数	是否必填	描述
`--app`	是	应用 ID（UUID）
`--title`	是	产品标题
`--access-level-id`	是	此产品解锁的访问等级 ID（UUID）
`--period`	是	订阅周期：`weekly`、`monthly`、`two_months`、`trimonthly`、`semiannual`、`annual`、`lifetime`
`--ios-product-id`	至少需要一个应用商店	App Store Connect 中的产品 ID
`--android-product-id`	至少需要一个应用商店	Google Play Console 中的产品 ID
`--android-base-plan-id`	与 `--android-product-id` 一起使用时必填，`--period lifetime` 除外	Google Play Console 中的基础方案 ID
`--stripe-product-id`	至少需要一个应用商店	Stripe 中的产品 ID
`--stripe-price-id`	与 `--stripe-product-id` 一起使用时必填	Stripe 中的价格 ID
`--paddle-product-id`	至少需要一个应用商店	Paddle 中的产品 ID
`--paddle-price-id`	与 `--paddle-product-id` 一起使用时必填	Paddle 中的价格 ID

每个产品至少需要关联一个商店：--ios-product-id、--android-product-id、--stripe-product-id 或 --paddle-product-id。一个产品可以同时携带多个商店的 ID。

如需通过 Stripe 或 Paddle 在网页端销售产品，请先将支付提供商连接到 Adapty：参见 Stripe 和 Paddle。对于这两个商店，需要同时传入产品 ID 和价格 ID，缺少其中任意一个命令都会失败。

adapty products create --app <app-id> --title "Monthly" --access-level-id <access-level-id> --period monthly --stripe-product-id prod_xxx --stripe-price-id price_xxx

仅限 Web 的产品是有效的：你可以创建一个只有 Stripe 或 Paddle ID、没有 App Store 或 Google Play ID 的产品。

adapty products update

更新现有产品。

商店产品 ID 和价格 ID 在创建后无法更改，且在此命令中不可用。如需使用不同的商店 ID，请创建新产品。

adapty products update --app <app-id> <product-id> --title "Monthly" --access-level-id <access-level-id>

参数	描述
`product-id`	产品 ID（UUID）

参数	是否必填	说明
`--app`	是	应用 ID（UUID）
`--title`	否	产品标题
`--access-level-id`	否	该产品解锁的访问等级 ID（UUID）

付费墙

adapty paywalls list

列出应用的所有付费墙。

adapty paywalls list --app <app-id>

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

接受分页标志。

adapty paywalls get

获取特定付费墙的详细信息。

adapty paywalls get --app <app-id> <paywall-id>

参数	描述
`paywall-id`	付费墙 ID（UUID）

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

adapty paywalls create

创建新付费墙。

adapty paywalls create --app <app-id> --title "Default Paywall" --product-id <product-id>

标志	是否必填	描述
`--app`	是	应用 ID（UUID）
`--title`	是	付费墙标题
`--product-id`	是	产品 ID（UUID）。重复使用以支持多个产品：`--product-id <id1> --product-id <id2>`

adapty paywalls update

替换现有付费墙的所有字段。

Important

付费墙一旦与版位关联，其产品便无法更改。如需在已上线的付费墙中使用不同的产品，请创建新的付费墙并更新版位指向该付费墙。

adapty paywalls update --app <app-id> <paywall-id> --title "Default Paywall" --product-id <product-id>

该命令会替换付费墙的所有字段，包括完整的产品列表。

参数	说明
`paywall-id`	付费墙 ID（UUID）

标志	是否必填	描述
`--app`	是	应用 ID（UUID）
`--title`	是	付费墙标题
`--product-id`	是	产品 ID（UUID）。多个产品时重复使用：`--product-id <id1> --product-id <id2>`

adapty paywalls placements

列出当前使用指定付费墙的所有版位。

adapty paywalls placements --app <app-id> <paywall-id>

参数	描述
`paywall-id`	付费墙 ID（UUID）

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

在替换付费墙之前使用此命令，可以查看哪些版位会受到影响。

此列表中的条目不包含 is_active 字段。如需读取版位的激活状态，请使用 placements list 或 placements get。

流程

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

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。状态值为以下之一：

状态	含义
`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 结束，而不是等待用户输入，因此在脚本和自动化会话中请传入 --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

Argument	Description
`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`	是	应用 ID（UUID）

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

版位

版位是您的流程、付费墙和用户引导触达用户的入口。版位的内容类型在创建时即已固定，因此若要将应用从付费墙迁移至流程，需要创建新版位而非更新现有版位——migrate-placements 技能通过这些命令来批量完成该操作。

adapty placements list

列出某个应用的所有版位。

adapty placements list --app <app-id>

参数	是否必填	说明
`--app`	是	应用 ID（UUID）

支持分页参数。

每条记录包含 id、developer_id、title 和 is_active。is_active 为 true 表示该版位已上线，为 false 表示未激活。

adapty placements get

获取特定版位的详细信息。

adapty placements get --app <app-id> <placement-id>

参数	描述
`placement-id`	版位 ID（UUID）

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

响应包含 id、developer_id、title、is_active 以及一个 audiences 数组。is_active 为 true 表示版位处于上线状态，false 表示未激活。每个受众条目包含 content_type（paywall 或 flow）、segment_ids、priority，以及 paywall_id 或 flow_id 之一。默认目标受众的 segment_ids: []，且具有最高的优先级值（最后被评估）。详见受众结构。

adapty placements create

创建新的版位。

adapty placements create --app <app-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'

参数	是否必填	说明
`--app`	是	App ID（UUID）
`--title`	是	版位标题
`--developer-id`	是	在应用代码中用于请求该版位的字符串标识符
`--audiences`	二选一	目标受众条目的 JSON 数组，每条需包含显式 `content_type`。详见目标受众格式
`--paywall-id`	二选一	已弃用。付费墙 ID（UUID）。客户端侧会将其包装为单个默认目标受众

--audiences 和 --paywall-id 必须二选一传入。两者同时传入或都不传入均会报错。

Warning

--paywall-id 已弃用，将在未来版本中移除。传入该参数时，CLI 会在 stderr 打印警告，并将该值转换为默认目标受众。新的自动化流程请使用 --audiences。

adapty placements update

替换现有版位的所有字段。

adapty placements update --app <app-id> <placement-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'

此命令会替换版位的所有字段，包括完整的目标受众列表。

参数	说明
`placement-id`	版位 ID（UUID）

参数	是否必填	描述
`--app`	是	应用 ID（UUID）
`--title`	是	版位标题
`--developer-id`	是	在应用代码中用于请求此版位的字符串标识符
`--audiences`	二选一	目标受众条目的 JSON 数组，每个条目均带有显式的 `content_type`。详见目标受众结构
`--paywall-id`	二选一	已废弃。付费墙 ID（UUID）。将所有目标受众替换为单个默认目标受众

Warning

传入 --paywall-id 会覆盖版位上的所有目标受众，特定市场细分的目标受众将被删除。若要保留它们，请使用 --audiences 并将所有需要保留的条目一并传入。

目标受众结构

--audiences 标志接受一个 JSON 数组，每个条目包含：

字段	类型	描述
`content_type`	`string`	`"paywall"` 或 `"flow"`。每条条目必填。同一版位中所有条目的值必须相同
`segment_ids`	`string[]`	此目标受众所针对的市场细分 ID。长度为 0 或 1。空数组表示默认目标受众——用于未匹配任何其他市场细分的用户的兜底选项
`paywall_id`	`string`	展示给此目标受众用户的付费墙 ID（UUID）。当 `content_type` 为 `"paywall"` 时必填
`flow_id`	`string`	展示给此目标受众用户的流程 ID（UUID）。当 `content_type` 为 `"flow"` 时必填
`priority`	`number`	从 0 开始，在版位内唯一。目标受众按从低到高的顺序依次评估；默认目标受众必须具有最高值

每个版位必须有且仅有一个默认目标受众。

版位的内容类型在创建时即已固定，因此 placements update 无法将付费墙版位切换为流程，反之亦然。请为流程单独创建一个版位——详见为流程创建新版位。

CLI 在发送请求前会逐条校验每个条目。若某条目的 content_type 缺失或未知，或者缺少 content_type 所需的 ID，CLI 将以退出码 2 终止，且不会发送任何请求。

流程只有在发布后才能被关联。处于 draft 状态的流程，或首次发布仍在进行中的流程，会被服务器拒绝；CLI 识别到该拒绝后将以代码 2 退出，并打印该流程对应的 flows publish 命令。要发布流程，请使用 flows publish 或流程与付费墙编辑工具，然后等待其状态变为 published。

以下是包含一个目标受众和一个默认受众的示例：

adapty placements update <placement-id> --app <app-id> --title "Main" --developer-id "main" \
  --audiences '[{"content_type":"paywall","segment_ids":["<vip-segment-id>"],"paywall_id":"<vip-paywall-id>","priority":0},{"content_type":"paywall","segment_ids":[],"paywall_id":"<default-paywall-id>","priority":1}]'

向所有用户提供已发布流程的版位示例：

adapty placements create --app <app-id> --title "Onboarding" --developer-id "onboarding" \
  --audiences '[{"content_type":"flow","segment_ids":[],"flow_id":"<flow-id>","priority":0}]'

要在多个版位之间替换付费墙而不丢失特定市场细分的路由配置：

找到受影响的版位：

adapty paywalls placements --app <app-id> <old-paywall-id>

对每个版位，读取完整的 audiences 数组：

adapty placements get --app <app-id> <placement-id> --json

在客户端替换匹配的 paywall_id 值。

将修改后的 payload 写回：

adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'

市场细分

市场细分通过 CLI 只读访问。请在 Adapty 看板中创建和编辑它们。使用以下命令在配置版位目标受众时查找市场细分 ID。

adapty 市场细分列表

列出某个应用的所有市场细分。

adapty segments list --app <app-id>

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

支持分页标志。

adapty segments get

获取指定市场细分的详细信息。

adapty segments get --app <app-id> <segment-id>

参数	说明
`segment-id`	市场细分 ID（UUID）

标志	必填	说明
`--app`	是	应用 ID（UUID）

响应包含 id、title 和 description。过滤规则不通过此 API 暴露。

身份验证

命令	描述
`adapty auth login`	通过浏览器使用设备流进行身份验证
`adapty auth logout`	清除本地存储的凭据
`adapty auth whoami`	向服务器验证令牌并显示用户信息
`adapty auth status`	不发起服务器调用，显示本地身份验证状态
`adapty auth revoke`	在服务器端撤销令牌并在本地清除

有关每个命令的完整详情，请参阅身份验证。