Flows commands
Flows are the paywalls and onboardings you build in the Flow & Paywall Builder. The CLI manages the flow record, its builder config, publication, and the version history. A builder config is a large JSON document that the Flow & Paywall Builder normally produces, and the CLI doesn’t generate one. To author or edit a config from the terminal, use the flow-generator skill, which drives these commands for you. Before publishing, the flow-audit skill checks whether the flow is ready for production. The flows metrics commands read the numbers of the flow metrics page and need CLI version 0.15.0 or later. The flows funnel commands read the flow funnel and need CLI version 0.19.0 or later. The commands are listed here as a reference.
adapty flows list
List all flows for an app.
adapty flows list --app <app-id>
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
Accepts pagination flags.
adapty flows get
Get details for a specific flow.
adapty flows get --app <app-id> <flow-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
The response contains id, name, status, published_flow_version_id, and updated_at. published_flow_version_id is the ID of the live version, or null when the flow has never been published. The status is one of:
| Status | Meaning |
|---|---|
draft | The flow has never been published |
published | The current version is live |
dirty | The flow was published before, and the current version has unpublished changes. Users keep seeing the last published version |
publishing | Publication is in progress |
publication_failed | The last publication failed. Fix the config and publish again |
archived | The flow is archived |
adapty flows create
Create a flow. The new flow has a name and no config. To add a config, use flows config update.
adapty flows create --app <app-id> --name "Onboarding"
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--name | Yes | Flow name |
adapty flows update
Rename a flow.
adapty flows update --app <app-id> <flow-id> --name "Onboarding v2"
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--name | Yes | New flow name |
adapty flows publish
Publish the current version of a flow to your users.
adapty flows publish --app <app-id> <flow-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--yes, -y | No | Publish without asking for confirmation. Required when the output is piped or --json is used |
Because publishing changes what your users see, the command prints the flow name and asks for confirmation. Any answer other than y cancels the command with exit code 1. Under --json or in a pipe, the command refuses with exit code 2 instead of waiting for an answer, so pass --yes in scripts and agent sessions.
Publication is asynchronous: the response reports status: publishing, and the flow isn’t live yet. Poll flows get until the status becomes published or publication_failed. On publication_failed, flows config get reports why.
Publishing fails with HTTP 400 when the flow has no config, when the config isn’t publishable, or when the current version is already live. To check a config before publishing, use flows config validate.
adapty flows config get
Read the builder config of a flow.
adapty flows config get --app <app-id> <flow-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
The response contains config, remote_configs, status, and updated_at. updated_at is a millisecond timestamp of the last config change. Pass it to flows config update as --expected-updated-at to avoid overwriting a concurrent edit. A flow whose config has never been written returns 404.
After a publication attempt, the response also carries three fields describing how it went. Read them when flows get reports publication_failed:
| Field | Description |
|---|---|
publication_status | How far publication of this flow version got: transforming, transformed, uploading, uploaded, published, or failed |
transform_error | The raw transform failure — either a JSON payload listing the issues or a summary string |
publication_error | A readable message for a failed publication |
adapty flows config update
Write the builder config of a flow and its remote configs.
adapty flows config get --app <app-id> <flow-id> --json > flow.json
adapty flows config update --app <app-id> <flow-id> --file flow.json
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--file | Instead of --config, --config-file, and --remote-configs | Path to a JSON file with config and remote_configs, or - to read from stdin. The output of flows config get --json works as is. Other keys are ignored |
--config | Without --file: one of --config and --config-file | Builder config as a JSON string |
--config-file | Without --file: one of --config and --config-file | Path to a JSON file with the builder config, or - to read from stdin |
--remote-configs | Without --file | JSON array of {locale, data} entries, where data is the remote config as a string. [] deletes all remote configs |
--expected-updated-at | No | The updated_at value from a prior flows config get. If the config changed after that read, the command fails instead of overwriting the change. Omit it to overwrite unconditionally |
A write replaces the config and the whole list of remote configs. To keep the remote configs, send the remote_configs from flows config get --json. Without --file, the command needs both the config and --remote-configs: when one is missing, it exits with code 2 and sends no request. The --file flag and the required --remote-configs need CLI version 0.20.0 or later.
To write the first config of a new flow, pass an empty list of remote configs:
adapty flows config update --app <app-id> <flow-id> --config-file config.json --remote-configs '[]'
Writing the config saves a draft and doesn’t publish it. On a published flow, the write creates a new version: the flow’s status becomes dirty, and users keep seeing the published version until you run flows publish.
adapty flows config validate
Check whether a builder config is publishable, without saving it.
adapty flows config validate --app <app-id> <flow-id> --config-file config.json
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--config | One of the two | Builder config as a JSON string |
--config-file | One of the two | Path to a JSON file with the builder config, or - to read from stdin |
The response contains valid and a list of issues. When the config isn’t publishable, the command exits with code 1, so scripts can gate on it.
adapty flows config preview
Render a local config file in the browser. This command makes no API call and takes no --app flag.
adapty flows config preview ./config.json --screen <screen-id> --device iphone-14 --orientation portrait
| Argument | Description |
|---|---|
config-file | Path to a local builder config JSON file |
| Flag | Default | Description |
|---|---|---|
--screen | The flow’s first screen | Screen ID to render |
--device | iphone-14 | Device frame to render in |
--orientation | portrait | portrait or landscape |
In a terminal, the command opens the preview in your browser. When piped or with --json, it prints the URL instead. The URL contains the whole config and is long: pipe it into a screenshot tool rather than printing it. Configs over roughly 32 KB render slowly.
adapty flows media upload
Upload an image to use in a flow config.
adapty flows media upload --app <app-id> ./hero.png
| Argument | Description |
|---|---|
file | Path to the image file |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
Accepted formats: PNG, JPEG, WebP, and SVG. The response contains the image id, name, and the CDN url to reference from the config. To upload a video, use flows media upload-video.
adapty flows media upload-video
Upload a video to use in a flow config.
adapty flows media upload-video --app <app-id> ./intro.mp4
| Argument | Description |
|---|---|
file | Path to the video file |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
Accepted formats: MP4 and WebM. The video must be at most 30 seconds long and at most 50 MB, and its width and height must each be at least 640 pixels. GIF isn’t supported, and the command doesn’t convert an animated image to a video.
The response contains the video URL (an HLS playlist), the preview image URL, and the video width and height. In the config, a video element takes them as videoUrl, previewUrl, width, and height.
adapty flows versions list
List the versions of a flow, newest first. These are the versions of the version history in the Flow & Paywall Builder.
adapty flows versions list --app <app-id> <flow-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--search | No | Show only the versions whose title contains this text. Case doesn’t matter, and part of a word matches: friday finds Black Friday |
Each line shows the title, the state, the date, and the ID of a version. The title is the version name, or Version N when the version has no name. The state is one of:
| State | Meaning |
|---|---|
draft | The version you edit. A flow has one draft or none. While the draft is being published, its line ends with Publishing…, and after a failed publish it ends with Publish failed |
live | The version your users see |
previous | An earlier version. It was live before, or a newer version replaced it before it was published |
The date of a live or previous version is the date its publish started. For the draft, and for a previous version that was never published, it’s the date the version was created.
For a flow that has never been published, the command prints History will appear after the first publish. and the draft line under it. The version history in the dashboard shows no line for such a flow. When no version matches --search, the command prints No versions match the search.
The command always lists all versions and takes no pagination flags.
With --json, the command prints {data, meta} from Adapty unchanged, with the rows in data. Each row has flow_version_id, version, name, title, state, is_current, publication_status, published_at, created_at, updated_at, and last_edited_by. updated_at is a millisecond timestamp of the last content change of the version: pass the updated_at of the draft to flows versions restore as --expected-updated-at. last_edited_by names the user who last changed the version, or is null when Adapty doesn’t know the user.
adapty flows versions get
Read one version of a flow. Reading a version changes nothing: the draft and the live version stay as they are.
The command prints the title, ID, number, state, and date of the version, the user who last changed it, and its Test on device link. The full content of the version — its builder config with every layout, its remote configs, and its paywalls — is in the output of --json, and in the file of --output.
adapty flows versions get --app <app-id> <flow-id> <version-id> --output version.json
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
version-id | Version ID (UUID), from flows versions list |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--output | No | Write the full content of the version to this file as JSON |
--yes, -y | No | Replace an existing --output file without asking. Required with --json or in a pipe when the file exists |
If the CLI can’t write the --output file, for example because its folder doesn’t exist, the command prints Could not write <path> (<errno>). and exits with code 1.
adapty flows versions preview
Print the Test on device link of a version. Open the link on your test device to see the version in the Adapty mobile app. Any version works: the draft, the live version, or an earlier one.
adapty flows versions preview --app <app-id> <flow-id> <version-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
version-id | Version ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
adapty flows versions rename
Rename a version. You can rename the draft, the live version, and earlier versions.
adapty flows versions rename --app <app-id> <flow-id> <version-id> --name "Black Friday"
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
version-id | Version ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--name | Yes | New version name. Pass --name "" to remove the name, so the version shows Version N again. A name of spaces only also removes it |
The command prints the version ID and the new title. Adapty trims the spaces at the ends of the name. Two versions can have the same name. A rename doesn’t change the content or the updated_at of the version, so it doesn’t conflict with a later save of the draft.
adapty flows versions restore
Restore a version as the draft of the same flow. This is Duplicate as draft in the version history. The restored version doesn’t reach your users until you publish it.
A restore replaces the current draft. To keep the draft, duplicate it to a new flow first with flows duplicate.
adapty flows versions restore --app <app-id> <flow-id> <version-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
version-id | Version ID (UUID) of a live or previous version |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--expected-updated-at | With --yes, when the flow has a draft | The updated_at of the draft, from flows versions list --json. If the draft changed after that read, the command fails instead of replacing the change |
--yes, -y | No | Replace the draft without asking. Required with --json or in a pipe when the flow has a draft |
The command reads the versions of the flow first:
- The flow has no draft: The command asks nothing. Adapty creates a new draft with the next version number, no name, and all the content of the version. The live version and the version you restore stay as they are.
- The flow has a draft: The command asks
Replace the draft '<draft>' (last change <time> by <user>) with '<version>'? To keep the draft, duplicate it to a new flow first., thenApply? [y/N]. If you answery, the draft keeps its ID, number, and name, and gets the content of the version. No version is added. Any other answer exits with code 1 and sends nothing.
With --json, in a pipe, or with no terminal, the command can’t ask. When the flow has a draft, it sends nothing and exits with code 6 unless you pass --yes. Its message asks the question and adds To replace it, re-run with --yes --expected-updated-at <ms> (the draft's updated_at)., with the updated_at of the draft in place of <ms>. With --yes, also pass --expected-updated-at: without it, the command exits with code 6 and sends nothing. In a terminal without --expected-updated-at, the command takes the updated_at of the draft it shows you in the question.
After a restore, the command prints Restored '<version>' as the draft '<draft>' (<draft-id>). Nothing is published.
Adapty refuses the restore and changes nothing in these cases. The command prints Adapty’s message, adds what to do for some of them, and exits with code 4:
| Message | What to do |
|---|---|
This flow version is already the current draft. | Pick another version. |
Flow version does not exist. | The version ID isn’t in the list of versions of this flow. Take the ID from flows versions list. |
Flow version is already being published. | Wait until the publish ends, then restore again. |
This flow version uses deleted products: … | Pick a version that doesn’t use them. |
This flow configuration was already updated by … | A teammate changed the draft after you read it. List the versions again and retry. |
Flow is deleted. | The flow is archived. Restore it from the archive in the dashboard first. |
adapty flows duplicate
Copy a flow, or one of its versions, to a new flow. This is Duplicate flow under the flow actions button in the top bar of the Flow & Paywall Builder (see Copy flows), and Duplicate as new flow in the version history.
adapty flows duplicate --app <app-id> <flow-id> --version <version-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--version | No | Version ID (UUID) to copy, from flows versions list. Any version works, the draft included. Without it, the command copies the draft, or the live version when the flow has no draft |
The command prints New flow '<name>' (<flow-id>), not published. The new flow is named after the source flow with _copy at the end. It isn’t published, and it has one draft with the content of the version. The source flow, its draft, and its history stay as they are. You can duplicate a flow while it’s being published.
Adapty refuses to copy a version that uses a deleted product, and to copy an archived flow. The messages are the same as for flows versions restore.
adapty flows metrics list
Show the lifetime metrics of several flows, one line for each flow. This is the data of the flows table in the dashboard.
adapty flows metrics list --app <app-id> --ids <flow-id>,<flow-id>
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--ids | Yes | Flow IDs (UUIDs). Separate them with commas, or repeat the flag |
--csv | No | Print CSV: one row for each flow, with the flow ID and all 27 metrics. Can’t be used with --json |
Each line shows the flow ID with its views, purchases, trials, and revenue. --json and --csv carry all 27 metrics of the flow metrics page, such as unique_profiles_views, net_revenue, and conversion_rate_purchases. A metric with no data is 0, never null. For each flow that has never been published, the command prints <flow-id>: No data: the flow was never published. under the table. --json adds note: "never_published" to the row of that flow, and with --csv the notes go to stderr, so the CSV stays clean.
adapty flows metrics values
List the filter keys and values of a flow: what flows metrics get --filter takes.
adapty flows metrics values --app <app-id> <flow-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
Each line shows a label and, in parentheses, the value to pass. Values are nested as the dashboard filters nest them:
Country (country)
Americas (Americas)
United States (US)
Europe (Europe)
Germany (DE)
Store (store)
App Store (app_store)
Google Play (play_store)
The top value of each group is the filter key, and the innermost values are what the key takes. In the example, --filter country=US keeps the United States, and --filter store=play_store keeps Google Play.
adapty flows metrics get
Show the metrics of one flow for a period, as the tree of the flow metrics page.
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
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--based-on | Yes | What the first level of the tree splits by: placement or audience. These are the placement-based and audience-based views of the flow metrics page |
--date-type | Yes | Which date the period applies to: purchase_date, or profile_install_date to filter by install date |
--date-from | No | First day of the period, inclusive (YYYY-MM-DD). Pass it together with --date-to |
--date-to | No | Last day of the period, inclusive (YYYY-MM-DD). Pass it together with --date-from |
--granularity | No | Split the period into points: day, week, month, quarter, or year |
--filter | No | Keep only data with these values of a filter key. Repeatable. See Filter the metrics |
--timezone | No | IANA time zone of the period points, for example Europe/Berlin. Without it, Adapty uses the app time zone |
--depth | No | How many levels of the tree to print under Total. Default: 1 |
--csv | No | Print CSV: one row for each node of the whole tree. Can’t be used with --json |
For a flow that has never been published, the command prints the note No data: the flow was never published. above the numbers, and --json adds note: "never_published". With --csv, the note goes to stderr, so the CSV stays clean.
For the revenue of one flow, run adapty analytics chart --app <app-id> --chart revenue --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --filter flow_id=<flow-id>. See Analytics commands.
The CLI exits with code 2 and sends no request when --based-on or --date-type is missing, or when only one end of the period is given. Adapty validates the values of --based-on, --date-type, and --granularity: a wrong value exits with code 4, and the error lists the accepted values.
Read the output
The command prints a Total line, then the first level of the tree under it. Each line shows views, purchases, trials, and revenue. With --granularity, the points of the period come right under their node:
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
The levels of the tree are the levels of the dashboard: placement, audience, A/B test, flow variation, screen, and product. With --based-on audience, the placement level is left out. To print more levels, pass --depth, for example --depth 3.
For the whole tree with all 27 metrics, use one of these flags:
--jsonprints the answer of the server unchanged.--csvprints one row for each node, period points included. The columns arepath(the titles fromTotaldown to the node, separated by>),level,title, and then the metrics.
Filter the metrics
Write each --filter as key=value, with the keys and values that flows metrics values lists. To keep any of several values, separate them with commas or repeat the flag with the same key. Filters with different keys combine, so data must match all of them:
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
The CLI sends each value exactly as written. To put a comma inside a value, write \,. An empty value is a value too: attribution_channel= keeps the data with no channel, which flows metrics values lists as No Data.
adapty flows funnel values
List the filter keys and values of a flow funnel: what flows funnel get --filter takes.
adapty flows funnel values --app <app-id> <flow-id>
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
The output has the same form as flows metrics values.
adapty flows funnel get
Show the screen on which users leave a flow: the funnel of one flow version, step by step and screen by screen, as on the Funnel tab of the flow.
adapty flows funnel get --app <app-id> <flow-id> --date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date
| Argument | Description |
|---|---|
flow-id | Flow ID (UUID) |
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--date-from | Yes | First day of the period, inclusive (YYYY-MM-DD), in the --timezone zone or the app time zone |
--date-to | Yes | Last day of the period, inclusive (YYYY-MM-DD), in the --timezone zone or the app time zone |
--date-type | Yes | Which date the period applies to: purchase_date or profile_install_date |
--flow-version-id | No | Flow version ID (UUID) to read. Without it, the CLI reads the published version |
--filter | No | Keep only users with these values of a filter key, as key=value. Repeatable. The keys and values come from flows funnel values and work as in Filter the metrics |
--timezone | No | IANA time zone of the days, for example Europe/Berlin. Without it, Adapty uses the app time zone |
--csv | No | Print the CSV file that the dashboard downloads, with the total row first. Can’t be used with --json |
The command prints the flow version and the period, a summary line, and a table. The summary shows how many users entered the flow, how many completed it, the drop rate, and the revenue. The table has one row for each step, with the columns Step, Type, Reached, Completed, Drop rate, and Revenue. A step with more than one screen also gets one row for each of its screens. A value that doesn’t apply, such as the revenue of an onboarding screen, is shown as —.
When no users entered the flow in the period, the table lists the screens of the version with zeros. For every field of the answer, use --json.
What’s next
- Command reference — every CLI topic, the global flags, and the pagination flags.
- Flow version history — the same versions in the Flow & Paywall Builder.