---
title: "Manage Retention Messaging from the CLI"
description: "Set up Apple Retention Messaging from the terminal with the Adapty CLI: connect the realtime URL, run the performance test, create, change, activate, and deactivate retention messages, and read their metrics."
---

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

The Adapty CLI sets up [Apple Retention Messaging](retention-messaging), the message that subscribers see on the **Cancel Subscription** screen, from the terminal, under the `adapty retention-messaging` topic. You can read the setup status of an app, connect Apple to the Adapty realtime URL that answers Apple's requests for a message, run Apple's performance test, create and change retention messages, activate and deactivate them, and read the metrics of each message.

Use it to let an AI agent set up Retention Messaging for you, to script messages across several apps, or to read the message metrics without opening the dashboard. The commands do the same actions as the **Retention Messaging** page of the dashboard, and the dashboard shows the same messages.

## Before you start

The `retention-messaging` topic uses the same installation and login as the rest of the CLI. If you have not set that up, follow steps 1 and 2 of the [quickstart guide](developer-cli-quickstart). To see whether your CLI has the topic, run:

```bash
adapty retention-messaging --help
```

Every command takes the app's UUID in `--app`. To find it, run:

```bash
adapty apps list
```

What your app needs for each step:

- **Read the setup status**: Nothing. Works for any app.
- **Read the realtime URL**: A complete [App Store setup](app-store-connection-configuration) in Adapty. You send this URL to Apple when you request access.
- **Configure the realtime URL and run the performance test**: Also the In-App Purchase key, and [access to the Retention Messaging API](retention-messaging-setup#request-access-from-apple), which you request from Apple. Apple's review can take up to a month, so request access early.
- **Show messages to subscribers**: Access from Apple, the realtime URL set to Adapty, at least one [product](create-product), and Apple's approval of each message.

Retention messages exist in two Apple environments: `sandbox` and `production`. The `--mode` flag selects the environment. Each environment has its own messages, as the **Sandbox mode** toggle of the dashboard shows.

To set up Retention Messaging from start to finish:

1. [Read the setup status](#read-the-setup-status).
2. [Read the realtime URL](#connect-the-realtime-url), and request access from Apple with it.
3. [Configure the realtime URL](#connect-the-realtime-url) for `sandbox`.
4. [Run the performance test](#run-the-performance-test), and read the setup status until the test has passed.
5. [Configure the realtime URL](#connect-the-realtime-url) for `production`.
6. [Create the default messages](#create-a-message), then the promo messages.
7. [List the messages](#list-and-read-messages) to follow Apple's review.

## Read the setup status

```bash
adapty retention-messaging setup-status --app <app-id>
```

The status shows the same setup steps as the dashboard:

| Field | Values |
|---|---|
| `credentials` | `present` or `missing`: whether the app has the App Store keys that Retention Messaging uses. |
| `registration_status` | `registered` or `not_registered`: whether Apple gave the app access to the Retention Messaging API. |
| `sandbox.realtime_url_status`, `production.realtime_url_status` | `not_configured`, `configured_to_other_url`, or `configured_to_adapty`: where Apple sends its requests in each environment. |
| `sandbox.performance_test_status` | `not_started`, `running`, `passed`, or `failed`. |

:::note
Some reads also update Adapty, as the dashboard does:
- While the performance test runs, `setup-status` asks Apple for the result of the test and saves it. `realtime-url configure` makes the same read before it asks for approval, so it saves the result even if you then decline.
- `messages list`, `messages get`, and the read that `messages update` makes before it writes ask Apple about the review of each message and save the new state. If Apple has approved a message, the read moves it to `live` right away. Adapty also checks Apple's review on its own, so an approved message goes live without a read too.
:::

## Connect the realtime URL

Apple sends a request to a realtime URL when a subscriber opens the **Cancel Subscription** screen. Adapty answers this request with your message. To read the Adapty URL, run:

```bash
adapty retention-messaging realtime-url get --app <app-id>
```

The same URL serves `sandbox` and `production`. You give this URL to Apple when you [request access](retention-messaging-setup#request-access-from-apple).

To set the Adapty URL in Apple for one environment, run:

```bash
adapty retention-messaging realtime-url configure --app <app-id> --mode sandbox
```

Configure `sandbox` first. Adapty refuses `production` until the [performance test](#run-the-performance-test) passes. When you configure `sandbox`, Adapty also creates a hidden test message for the performance test. This message isn't in the message list.

If Apple sends the requests of this environment to a different server (`configured_to_other_url`), the Adapty URL replaces that server's URL in Apple. From then on, that server gets no requests from the **Cancel Subscription** screen. The CLI shows a warning that names the environment. To approve the replacement:

- **In a terminal, without `--json`**: Read the warning and answer `y` at the `Apply? [y/N]` prompt. The prompt appears even when you pass `--yes`.
- **In a script, an agent, or with `--json`**: Pass `--replace-other-url --yes`. Without `--replace-other-url`, the CLI sends nothing and exits with code 6, even with `--yes`.

## Run the performance test

Apple tests how fast Adapty answers before Adapty allows the `production` realtime URL. Before you start the test, [configure the realtime URL](#connect-the-realtime-url) for `sandbox`. Then purchase your longest-duration product with a sandbox account or through TestFlight, keep the subscription active, and start the test right after the purchase:

```bash
adapty retention-messaging performance-test start --app <app-id>
```

The test always runs in `sandbox` and can take up to an hour. To see the result, read the [setup status](#read-the-setup-status) again: `sandbox.performance_test_status` changes from `running` to `passed` or `failed`. While the status is `running`, don't start the test again: Adapty refuses it. To learn why a test fails, see [Pass the performance test](retention-messaging-setup#pass-the-performance-test).

When the test passes, connect production:

```bash
adapty retention-messaging realtime-url configure --app <app-id> --mode production
```

## List and read messages

```bash
adapty retention-messaging messages list --app <app-id> --mode production --state live
```

`--mode` is required. The list shows each message with its name, type, state, number of products, start date, and these metrics for the whole life of the message:

| Field | Dashboard column | Value |
|---|---|---|
| `shown` | **Shown** | Count |
| `retained` | **Retained users** | Count |
| `saved_users` | **Saved users** | Count |
| `retention_rate` | **Retention rate** | Percent, one decimal place. `0.0` while no view has an outcome. |
| `save_rate` | **Save rate** | Percent, one decimal place. `0.0` while no view is older than 24 hours. |
| `saved_revenue` | **Saved revenue** | USD before Apple's commission, two decimal places |

For how Adapty calculates each metric, see [Track message performance](retention-messaging-analytics).

A message is in one of these states: `in_review`, `live`, `rejected`, or `inactive`. For what each state means, see [Message states](retention-messaging-create#message-states).

To read one message with its texts, image, bullet points, products, and locales, run:

```bash
adapty retention-messaging messages get <message-id> --app <app-id>
```

The message has no environment field. Its texts and bullet points are the `en-US` source. Each other locale shows its own review state.

## Create a message

A promo message needs a default message for the same product in the same environment. Create the default message first. You don't have to wait for Apple's review of it.

To find the product IDs, the promo offers, and the plan switches for the file, use the [suggest commands](#find-products-and-offers). To create a message, put its content in a JSON file:

```json title="message.json"
{
  "name": "Annual default",
  "type": "default",
  "title": "Before you go",
  "body": "Your plan keeps every feature you use today.",
  "alt_text": "App icon on a purple background",
  "header_position": "above_body",
  "products": [
    { "store_id": "com.example.annual" }
  ],
  "bullet_points": [
    { "image_path": "icons/sync.png", "text": "Sync on all your devices" },
    { "image_path": "icons/offline.png", "text": "Work offline" }
  ],
  "localizations": [
    {
      "locale": "de-DE",
      "title": "Bevor du gehst",
      "body": "Dein Abo behält alle Funktionen, die du heute nutzt.",
      "bullet_points": [
        { "text": "Auf allen Geräten synchronisieren" },
        { "text": "Offline arbeiten" }
      ]
    }
  ]
}
```

Then run:

```bash
adapty retention-messaging messages create --app <app-id> --mode sandbox \
  --file message.json --image header.png
```

The file takes these keys:

- **`name`, `type`, `title`, `body`**: Required. The title and body are the `en-US` source, up to 66 and 144 characters.
- **`type`**: The message type, `default` or `promo`. You can't change the type later.
- **`alt_text`**: The description of the image for screen readers, up to 150 characters.
- **`header_position`**: The position of the title in a default message with an image. `above_image` shows the title above the image. `above_body` shows it below the image, above the body. You can't change it later.
- **`products`**: The products whose subscribers see the message, by their App Store product ID in `store_id`. A default message has no `association`. A promo message needs at least one product, and each product needs an incentive in `association`: `{"type": "promo_offer", "store_id": "<offer-id>"}` or `{"type": "plan_switch", "store_id": "<product-id>"}`. All products of one promo message use the same incentive type: all `promo_offer` or all `plan_switch`.
- **`bullet_points`**: Up to five, for a default message only. Each has `text` (1–66 characters), an optional `alt_text`, and `image_path`: the path to its PNG icon, relative to the folder of the JSON file. The CLI refuses `image_index`.
- **`localizations`**: One entry for each locale other than `en-US`, with `locale`, `title`, `body`, and one `bullet_points` text for each bullet point of the message, in the same order.

`--image` adds the image of a default message. A promo message has no image and no bullet points.

Before it asks for your approval, the CLI validates each image file. The CLI then asks for approval, as described in [Confirmation in scripts and agents](#confirmation-in-scripts-and-agents). Adapty sends the texts and images of the new message to Apple for review, and the message state is `in_review`.

If a create fails with a network error or a server error, don't run it again. See [If a create or a change gets no answer](#if-a-create-or-a-change-gets-no-answer).

### Image requirements

| File | Requirements |
|---|---|
| Image (`--image`) | PNG, 3840 px wide and 160–2160 px tall, no transparency, up to 10 MB |
| Bullet point icon (`image_path`) | PNG, 1024 × 1024 px, no transparency, up to 10 MB |

The CLI validates each file before it sends anything. A PNG with an alpha channel passes if every pixel is fully opaque. A damaged PNG fails with the `must be a PNG` error. If a file fails, the CLI sends nothing and exits with code 2. The error names the file and the rule, for example `… must be 3840 px wide and 160–2160 px tall`.

## Change a message

:::warning
A change to an inactive message activates it again, even a change of the name only. After Apple approves the message, subscribers see it.
:::

`messages update` changes only what you name. Every locale, bullet point, icon, product, and the image that you don't name stay as they are:

```bash
adapty retention-messaging messages update <message-id> --app <app-id> --title "Wait, there's more"
```

Change the name, title, body, and alt text, and the image, with flags: `--name`, `--title`, `--body`, `--alt-text`, `--image`, and `--remove-image`. Change locales, bullet points, and products with a changes file in `--file`. The changes file also takes `name`, `title`, `body`, `alt_text`, and `remove_image`. The CLI refuses a key that the changes file doesn't know. This changes file works on the message from [Create a message](#create-a-message):

```json title="changes.json"
{
  "localizations": [
    { "locale": "de-DE", "title": "Warte kurz", "bullet_texts": { "<bullet-id>": "Auf jedem Gerät synchronisieren" } }
  ],
  "bullet_points": [
    { "bullet_id": "<bullet-id>", "text": "Sync on every device" },
    {
      "image_path": "icons/backup.png",
      "text": "Daily backups",
      "texts": { "de-DE": "Tägliche Backups" }
    }
  ],
  "remove_bullet_points": ["<other-bullet-id>"]
}
```

- **Locales**: Name each locale by its code in `locale`, with `title`, `body`, and the bullet point texts of the locale in `bullet_texts`, by `bullet_id`. A locale that the message doesn't have is added, and it needs `title`, `body`, and a text for each bullet point.
- **Bullet points**: To change a bullet point, name it by its `bullet_id` from `messages get`, with `text`, `alt_text`, or `image_path` for a new icon. A new bullet point has no `bullet_id`. It needs `image_path`, the `en-US` `text`, and a text in `texts` for each locale of the message.
- **Products**: By their App Store product ID in `store_id`. A product that the message doesn't have is added. In a promo message, each product needs an incentive: to change it, pass a new `association`. To stop offering an incentive on a product, remove the product with `remove_products`. A product that you add to a promo message needs an `association`.
- **Removals**: Use the remove fields: `remove_localizations` (locale codes), `remove_bullet_points` (bullet IDs), `remove_products` (App Store product IDs), and `remove_image: true` or `--remove-image`. A removed bullet point disappears from every locale. While a promo message uses a product, you can't remove that product from its default message.

You can't change the type, the `header_position`, or the incentive type of a promo message (`promo_offer` or `plan_switch`). To use a different one, create a new message.

The CLI validates your changes before it sends anything. If the input contradicts itself, changes nothing, or names or removes something that the message doesn't have, the CLI sends nothing, exits with code 2, and the error names the problem. Give the locale texts of an existing bullet point in `bullet_texts` of the locale, not in `texts`.

The CLI asks for approval, reads the message, merges your changes into it, and sends the full message to Adapty. Every update sends the whole message to Apple for review, and the message state becomes `in_review`. If someone changes the message in the dashboard while `messages update` runs, the update overwrites that change.

## Activate or deactivate a message

```bash
adapty retention-messaging messages set-status <message-id> --app <app-id> --action deactivate
```

- **`activate`**: Moves an `inactive` message to `in_review`. Apple reviews again only the locales it hasn't approved. After Apple approves the message, subscribers see it again.
- **`deactivate`**: Moves a `live` message to `inactive`. Subscribers no longer see it. Views that occurred stay in the metrics.

Adapty refuses `activate` for a message that isn't `inactive`, and `deactivate` for a message that isn't `live`. A message in `in_review` goes live when Apple approves it. To stop it, deactivate it after that. The CLI has no command to delete a message.

A product can have one default message and one promo message in each environment. Adapty refuses the activation in these cases:

- Another message of the same type was added to the product while this message was inactive.
- The message is a promo message, and one of its products has no default message in this environment.

While a promo message uses a product, Adapty refuses to deactivate the default message of that product. Deactivate the promo message, or remove the product from it, first.

## Find products and offers

To find the products that you can add to a message, run:

```bash
adapty retention-messaging products suggest --app <app-id> --mode production --type default
```

When you change a message, pass its ID in `--message-id`, so that the products of this message don't show as `used`. A product with a `disabled_reason` can't be added:

- **`used`**: Another message of the same type in this environment has the product.
- **`no_default_message`**: The product has no default message in this environment, so it can't get a promo message.

A promo message links one incentive to each product. To find the incentives for a product, pass the product `id` from `products suggest`. To list the promotional offers of the product, run:

```bash
adapty retention-messaging promo-offers suggest <product-id> --app <app-id>
```

To list the plans that a subscriber can switch to, run:

```bash
adapty retention-messaging plan-switches suggest <product-id> --app <app-id>
```

`plan-switches suggest` needs the [App Store Connect API key](app-store-connect-api-key) in the app settings. Put the `store_id` of the offer or the plan in the `association` of the product.

## Confirmation in scripts and agents

These commands change what subscribers see on the **Cancel Subscription** screen. Each one prints its effect and asks for approval before it sends the change, in `sandbox` and in `production`:

- `realtime-url configure`
- `messages create`
- `messages update`
- `messages set-status`

How it asks depends on how the command runs:

| How the command runs | What happens |
|---|---|
| In a terminal, without `--yes` and without `--json` | The CLI prints the effect and asks `Apply? [y/N]`. If you answer `y` or `yes`, the CLI sends the request. For any other answer, the CLI exits with code 1 and sends nothing. |
| With `--yes`, in a terminal or not | The CLI sends the request without asking, even in `production`. |
| Without `--yes`, with `--json`, in a pipe, or with no terminal | The CLI sends nothing and exits with code 6. The error describes the effect. |

Replacing a different realtime URL in Apple has its own rules. See [Connect the realtime URL](#connect-the-realtime-url).

So a script or an agent can read the effect of a command first: run it without `--yes`, read the effect in the output, and run it again with `--yes` only after someone approves that effect.

`setup-status`, `realtime-url get`, `performance-test start`, `messages list`, `messages get`, and the `suggest` commands run without asking.

## Errors

| Exit code | Cause | What to do |
|---|---|---|
| 1 | You answered something other than `y` at the prompt. Nothing was sent. | Run the command again if you meant to. |
| 2 | The CLI refused the input before it sent the change: a flag, an image file, a conflict in the input, a locale without a text for each bullet point, or a removal of something that the retention message doesn't have. | Fix what the error names. |
| 3 | You aren't logged in, or Adapty refused access to the app. | Log in with `adapty auth login`, and find the app ID in `adapty apps list`. |
| 4 | Adapty refused the request. The error gives the reason, and `--json` gives the HTTP status and `error_code`. A server error (5xx) on a create or a change also gives code 4, and the result is unknown. | See [Messages from Adapty](#messages-from-adapty). After a server error on a create or a change, see [If a create or a change gets no answer](#if-a-create-or-a-change-gets-no-answer). |
| 5 | The CLI couldn't reach Adapty. | Make sure you are online. After a create or a change, see [If a create or a change gets no answer](#if-a-create-or-a-change-gets-no-answer). |
| 6 | A command that asks for approval ran without `--yes` and with no one to answer, or a realtime URL replacement ran without `--replace-other-url`. Nothing was sent. | Read the effect in the error, then run the command again with `--yes`, and with `--replace-other-url` for a replacement. |
| 130 | You pressed Ctrl+C at the prompt. Nothing was sent. | — |

### Messages from Adapty

With `--json`, the error gives the `error_code`:

| `error_code` | Cause | What to do |
|---|---|---|
| `app_store_credentials_missing` | The app has no App Store keys in Adapty. | Complete the [App Store setup](app-store-connection-configuration). |
| `app_store_connect_credentials_missing` | `plan-switches suggest` needs the App Store Connect API key. | Add the [App Store Connect API key](app-store-connect-api-key). |
| `realtime_url_unavailable` | The app has no App Store server notifications setup in Adapty. | Complete the [App Store setup](app-store-connection-configuration). |
| `apple_rm_api_access_denied` | Apple hasn't given the app access to the Retention Messaging API. | [Request access from Apple](retention-messaging-setup#request-access-from-apple). |
| `performance_test_required` | You configured `production` before the performance test passed. | [Run the performance test](#run-the-performance-test) first. |
| `performance_test_already_running` | A performance test runs. | Wait, then read the setup status again. |
| `active_sandbox_transaction_missing` | No active sandbox subscription. | Purchase your longest-duration product in sandbox, then start the test again. |
| `performance_test_request_rejected` | Apple refused to start the test. | Make a new sandbox purchase, then start the test again. |
| `retention_product_claimed` | Another message of the same type has the product. | Pick another product, or deactivate the other message. |
| `retention_default_message_missing` | A promo message has a product with no default message. | Create or activate a default message for the product first. |
| `retention_dependent_promo_messages` | A promo message uses a product that the change takes away from a default message. | Deactivate the promo message, or remove the product from it, first. |
| `retention_promo_association_invalid` | A promo message has no product, a product without `association`, or both incentive types. | Give every product an `association` of the same type. |
| `retention_message_type_immutable` | The change gives a promo message a different incentive type. | Create a new message. |
| `retention_message_invalid_status_transition` | `activate` on a message that isn't `inactive`, or `deactivate` on a message that isn't `live`. | Read the state of the message with `messages get`. |
| `retention_message_not_found` | The app has no message with this ID. | Take the ID from `messages list`. |

### If a create or a change gets no answer

If the CLI gets no answer to a create or an update, because of a network error or a server error (exit code 4 or 5), it can't tell whether Adapty saved the change. The CLI doesn't send the request again. Don't run the command again yourself either.

- **After a create**: Run `messages list` for the same environment with `--search "<name>" --page-size 100`. The error prints the exact name on its own line (`message_name` in `--json`). Read every page up to `meta.pagination.pages`, and open each candidate with `messages get`. A second create can make a duplicate message and send it to Apple's review. Create the message again only if no candidate is your message.
- **After an update**: Run `messages get`, and read the state and the content of the message.

## Command reference

Every command takes `--app`, the app UUID from `adapty apps list`.

### `retention-messaging setup-status`

Returns the setup status. Takes no other flags.

### `retention-messaging realtime-url get`

Returns the Adapty realtime URL. Takes no other flags.

### `retention-messaging realtime-url configure`

| Flag | Required | Description |
|---|---|---|
| `--mode` | Yes | `sandbox` or `production`. |
| `--replace-other-url` | No | Approve the replacement of a different URL in Apple. |
| `--yes`, `-y` | No | Configure without asking. Required with `--json` or in a pipe. |

### `retention-messaging performance-test start`

Starts Apple's performance test in `sandbox`. Takes no other flags.

### `retention-messaging messages list`

| Flag | Required | Description |
|---|---|---|
| `--mode` | Yes | `sandbox` or `production`. |
| `--search` | No | Part of the name, any case, or the exact message ID. |
| `--type` | No | `default` or `promo`. |
| `--state` | No | `in_review`, `live`, `rejected`, or `inactive`. |
| `--ordering` | No | `name`, `type`, `state`, `products_count`, or `started_at`. Add `-` before the field for the reverse order. Default: `-started_at`. |
| `--page` | No | Page number. Default: 1. |
| `--page-size` | No | Messages per page, up to 100. Default: 20. |

### `retention-messaging messages get`

Takes the message ID as its argument. Returns the full message.

### `retention-messaging messages create`

| Flag | Required | Description |
|---|---|---|
| `--mode` | Yes | `sandbox` or `production`. |
| `--file` | Yes | The JSON file of the message, or `-` to read it from standard input. See [Create a message](#create-a-message). |
| `--image` | No | The PNG image of a default message. |
| `--yes`, `-y` | No | Create without asking. Required with `--json` or in a pipe. |

### `retention-messaging messages update`

Takes the message ID as its argument.

| Flag | Required | Description |
|---|---|---|
| `--name`, `--title`, `--body`, `--alt-text` | No | New value of the field. |
| `--image` | No | New PNG image. |
| `--remove-image` | No | Remove the image. |
| `--file` | No | The changes file, or `-` to read it from standard input. See [Change a message](#change-a-message). |
| `--yes`, `-y` | No | Change without asking. Required with `--json` or in a pipe. |

### `retention-messaging messages set-status`

Takes the message ID as its argument.

| Flag | Required | Description |
|---|---|---|
| `--action` | Yes | `activate` or `deactivate`. |
| `--yes`, `-y` | No | Change the status without asking. Required with `--json` or in a pipe. |

### `retention-messaging products suggest`

| Flag | Required | Description |
|---|---|---|
| `--mode` | Yes | `sandbox` or `production`. |
| `--type` | Yes | `default` or `promo`: the type of the message. |
| `--search` | No | Part of the product title, any case. |
| `--message-id` | No | The ID of the message that you change. |
| `--limit` | No | Products to return, up to 100. Default: 10. |

### `retention-messaging promo-offers suggest`

Takes the product ID from `products suggest` as its argument.

| Flag | Required | Description |
|---|---|---|
| `--search` | No | Part of the offer title, any case. |
| `--limit` | No | Offers to return, up to 100. Default: 10. |

### `retention-messaging plan-switches suggest`

Takes the product ID from `products suggest` as its argument.

| Flag | Required | Description |
|---|---|---|
| `--search` | No | Part of the plan title, any case. |
| `--limit` | No | Plans to return, up to 100. Default: 10. |

## Work from an AI assistant

The [Adapty MCP server](adapty-mcp) offers the same actions as `retention_messaging_*` tools, for example `retention_messaging_messages_list` for `messages list`. The tools take `message_type` in place of `--type`.

- **Approval**: The assistant asks before it configures the realtime URL, creates or changes a message, or changes its status, in `sandbox` and in `production`. Before it replaces another server's realtime URL, it asks a separate question. It also asks once in each conversation before its first setup status read, and once before its first message read, because [these reads can update Adapty](#read-the-setup-status).
- **Images and bullet points**: The MCP tools can't add an image, a bullet point icon, or a new bullet point. `retention_messaging_messages_create` creates a message without an image or bullet points. To add them, run `messages update` from the CLI, or use the dashboard.

## What's next

- [Agent skill for Retention Messaging](retention-messaging-skill) — let your agent set up Retention Messaging and write your messages, with your yes before each change.
- [Set up Retention Messaging](retention-messaging-setup) — the same setup steps in the dashboard.
- [Create a retention message](retention-messaging-create) — the message fields, locales, and states in the dashboard.
- [Track message performance](retention-messaging-analytics) — what each metric means.