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>
FlagRequiredDescription
--appYesApp ID (UUID)

Accepts pagination flags.

adapty flows get

Get details for a specific flow.

adapty flows get --app <app-id> <flow-id>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp 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:

StatusMeaning
draftThe flow has never been published
publishedThe current version is live
dirtyThe flow was published before, and the current version has unpublished changes. Users keep seeing the last published version
publishingPublication is in progress
publication_failedThe last publication failed. Fix the config and publish again
archivedThe 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"
FlagRequiredDescription
--appYesApp ID (UUID)
--nameYesFlow name

adapty flows update

Rename a flow.

adapty flows update --app <app-id> <flow-id> --name "Onboarding v2"
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--nameYesNew flow name

adapty flows publish

Publish the current version of a flow to your users.

adapty flows publish --app <app-id> <flow-id>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--yes, -yNoPublish 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>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp 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:

FieldDescription
publication_statusHow far publication of this flow version got: transforming, transformed, uploading, uploaded, published, or failed
transform_errorThe raw transform failure — either a JSON payload listing the issues or a summary string
publication_errorA 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
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--fileInstead of --config, --config-file, and --remote-configsPath 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
--configWithout --file: one of --config and --config-fileBuilder config as a JSON string
--config-fileWithout --file: one of --config and --config-filePath to a JSON file with the builder config, or - to read from stdin
--remote-configsWithout --fileJSON array of {locale, data} entries, where data is the remote config as a string. [] deletes all remote configs
--expected-updated-atNoThe 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
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--configOne of the twoBuilder config as a JSON string
--config-fileOne of the twoPath 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
ArgumentDescription
config-filePath to a local builder config JSON file
FlagDefaultDescription
--screenThe flow’s first screenScreen ID to render
--deviceiphone-14Device frame to render in
--orientationportraitportrait 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
ArgumentDescription
filePath to the image file
FlagRequiredDescription
--appYesApp 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
ArgumentDescription
filePath to the video file
FlagRequiredDescription
--appYesApp 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>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--searchNoShow 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:

StateMeaning
draftThe 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
liveThe version your users see
previousAn 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
ArgumentDescription
flow-idFlow ID (UUID)
version-idVersion ID (UUID), from flows versions list
FlagRequiredDescription
--appYesApp ID (UUID)
--outputNoWrite the full content of the version to this file as JSON
--yes, -yNoReplace 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>
ArgumentDescription
flow-idFlow ID (UUID)
version-idVersion ID (UUID)
FlagRequiredDescription
--appYesApp 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"
ArgumentDescription
flow-idFlow ID (UUID)
version-idVersion ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--nameYesNew 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.

Tip

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>
ArgumentDescription
flow-idFlow ID (UUID)
version-idVersion ID (UUID) of a live or previous version
FlagRequiredDescription
--appYesApp ID (UUID)
--expected-updated-atWith --yes, when the flow has a draftThe 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, -yNoReplace 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., then Apply? [y/N]. If you answer y, 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:

MessageWhat 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>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--versionNoVersion 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>
FlagRequiredDescription
--appYesApp ID (UUID)
--idsYesFlow IDs (UUIDs). Separate them with commas, or repeat the flag
--csvNoPrint 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>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp 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
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--based-onYesWhat 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-typeYesWhich date the period applies to: purchase_date, or profile_install_date to filter by install date
--date-fromNoFirst day of the period, inclusive (YYYY-MM-DD). Pass it together with --date-to
--date-toNoLast day of the period, inclusive (YYYY-MM-DD). Pass it together with --date-from
--granularityNoSplit the period into points: day, week, month, quarter, or year
--filterNoKeep only data with these values of a filter key. Repeatable. See Filter the metrics
--timezoneNoIANA time zone of the period points, for example Europe/Berlin. Without it, Adapty uses the app time zone
--depthNoHow many levels of the tree to print under Total. Default: 1
--csvNoPrint 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:

  • --json prints the answer of the server unchanged.
  • --csv prints one row for each node, period points included. The columns are path (the titles from Total down 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>
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp 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
ArgumentDescription
flow-idFlow ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--date-fromYesFirst day of the period, inclusive (YYYY-MM-DD), in the --timezone zone or the app time zone
--date-toYesLast day of the period, inclusive (YYYY-MM-DD), in the --timezone zone or the app time zone
--date-typeYesWhich date the period applies to: purchase_date or profile_install_date
--flow-version-idNoFlow version ID (UUID) to read. Without it, the CLI reads the published version
--filterNoKeep 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
--timezoneNoIANA time zone of the days, for example Europe/Berlin. Without it, Adapty uses the app time zone
--csvNoPrint 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