---
title: "Flows 命令"
description: "Adapty CLI 命令，用于创建流程、读写构建器配置、验证和预览流程、上传媒体文件以及发布流程。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

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

## adapty flows list \{#adapty-flows-list\}

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

```bash
adapty flows list --app <app-id>
```

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

支持[分页标志](developer-cli-reference#global-flags)。

## adapty flows get

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

```bash
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 \{#adapty-flows-create\}

创建一个流程。新流程只有名称，没有配置。如需添加配置，请使用 [`flows config update`](#adapty-flows-config-update)。

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

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

## adapty flows update

重命名流程。

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

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

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

## adapty flows publish

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

```bash
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`](#adapty-flows-get)，直到状态变为 `published` 或 `publication_failed`。若状态为 `publication_failed`，可通过 [`flows config get`](#adapty-flows-config-get) 查看失败原因。

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

## adapty flows config get

读取流程的编辑器配置。

```bash
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`](#adapty-flows-config-update)，可避免覆盖并发编辑。如果某个流程的配置从未写入，则返回 404。

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

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

## adapty flows config update

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

```bash
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-publish) 之前，用户看到的仍是已发布的版本。

## adapty flows config validate

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

```bash
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 \{#adapty-flows-config-preview\}

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

```bash
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\}

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

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

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

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

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

## 下一步 \{#whats-next\}

- [命令参考](developer-cli-reference) — 所有 CLI 主题、全局标志和分页标志。