Workflow guides

Before you start

Connect your agent to AppScreens and have your app’s screenshots ready, for example from the simulator, Fastlane snapshot or your UI tests. Coding agents such as Claude Code, Codex and Cursor can read them straight from your repository.

AppScreens sends a short workflow to your agent at connection. Ask for the outcome, such as “update our screenshots for the new release”. The AppScreens skill has detailed steps for reference matching, asset imports and delivery.

Try asking

Tools your agent uses:get_account_setupget_account_capabilitiesget_account_usage

Connect your agent →Starter prompts for common jobs →

1. Create a project

Start with whatever you have: an App Store or Google Play link, a description of your app, a template, an existing project, a blank project or just your screenshots. If your agent finds a matching draft and you have not chosen a project, it asks whether to update it or start fresh.

Your agent uses your title, app brief and brand colours. For a new set, it checks the release build or listing when available, then plans required and recommended sizes from the editor catalogue. It asks about unresolved stores, devices and languages before choosing a template or starting blank. You can also add individual template pages to a project you already have.

If the layout is open, ask your agent to shortlist templates that fit the app, output sizes and captures. To keep an existing project as it is while you try another direction, ask for a separate copy.

For a close match, check a representative render against the reference before repeating the layout. Continue through the set unless the customer asked to review it early or a decision blocks progress.

Try asking

Tools your agent uses:create_appplan_screenshot_requirementslist_templatesget_templatecreate_projectset_project_settingsadd_project_screenshot

2. Add your app screenshots

Point your agent at the app captures you want to use. It reviews all supplied captures before suggesting a page count and explains any it would leave out. It matches each chosen file to an editable Device element, display size and language using the editor’s bulk upload rules. Photos, logos and artwork stay in separate Image elements.

Chat apps that can’t read your files, such as Claude.ai and ChatGPT, import images you attach or link to instead.

Try asking

Tools your agent uses:create_asset_uploadcomplete_asset_uploadimport_asset_filesplan_device_screenshot_importassign_device_screenshots

3. Review ASO Captions

Your agent shows the proposed titles and optional subtitles in page order. Review them against your app captures. AppScreens saves the approved copy into the existing text and keeps the design settings.

Try asking

Tools your agent uses:get_project_textreplace_project_text

4. Adjust the design

Ask your agent to match your app’s brand colours. It can read the project palette and use the editor’s Color replacer across the set. For changes to a specific page, it can inspect individual settings such as text decoration, text size or device position.

Ask for a template layout to copy its geometry, or ask to match the style of a page in your project while keeping each page’s own copy and captures. For project-wide sizes or languages, tell your agent which outputs to add or change.

Colour inputs accept hex with or without alpha, rgb(), rgba() and numeric RGBA arrays. Partial shadow edits keep existing settings. The design reference includes examples for formatted captions, removing subtitles and using the project shadow.

Try asking

Tools your agent uses:get_project_designget_project_elementget_design_contractapply_project_changes

Copy, edit or restyle a project →

5. Preview and review

Choose how to review your design. To see the screenshot pages in chat, ask your agent to render them and check for text that doesn’t fit.

To see the design in App Store or Google Play search and on a product page, ask for the browser listing preview. Your agent gets the link from get_project. It opens the Preview tab in Preview & Export for projects with a matching store target. Choose Preview a listing there to add a feature graphic or other artwork in the standalone tool. This uses the selected previews without a download. The standalone tool also takes a link or local files.

Try asking

Tools your agent uses:get_projectrender_project_previewwait_for_operationget_preview_image

6. Translate

Add the languages you need, then run the project’s built-in automatic translation or ask your agent to apply reviewed translations. Automatic translation requires a paid plan and preserves reviewed translations. Add localized app captures as in step 2, then preview each language to check text fit and imagery.

Try asking

Tools your agent uses:list_languagesset_project_settingstranslate_projectset_project_translationsrender_project_preview

7. Export

Before a new export, your agent checks the selected pages, languages and output sizes. It flags issues that affect delivery, such as an applicable size missing from the selection or translations that need refreshing.

An export renders the selected pages at full resolution. Your agent waits for it to finish and gives you the download links. The same files appear in Export History in AppScreens.

For a release, your agent can flag any artwork still needed and offer to make a matching Google Play feature graphic or Apple Universal Creative Asset after delivery.

Try asking

Tools your agent uses:validate_exportstart_project_exportwait_for_operationget_artifact_linklist_exports

Wait efficiently for previews and exports

Use wait_for_operation with timeoutSeconds: 25 for pending previews and exports. It returns early when finished, or the latest state after the maximum wait. Await the call before checking again. In Codex, use yield_time_ms: 35000 for both execution and runner waits, or the longest window the client supports. Resume the same pending execution without one-second checks or overlapping calls. If still running, wait on the same operation ID within a bounded period (about 60 seconds), then report its latest status. A wait expiring does not cancel the operation or justify starting another render.

• Give a brief progress update before waiting. These are maximum windows, not fixed delays: a finished result returns sooner.
• Stop waiting when the operation succeeds, fails or is cancelled. If the bounded period expires, keep its ID for the next check; a running operation is not a failed render.
• The runner setting belongs to your agent client, not the AppScreens API. Repeated short runner waits can wake the model with the same conversation context.

8. Connect App Store Connect or Google Play

To upload for you, AppScreens needs a store connection for your app. Store keys never go through your agent: it gives you a secure AppScreens link, and you add the key there yourself.

1. Your agent creates the app in AppScreens, or uses one you already have, with its App Store ID or Google Play package name.
2. It opens credential setup and gives you a link to AppScreens.
3. For App Store Connect, add an API key from Users and Access > Integrations: the .p8 file, its Key ID and the Issuer ID. For Google Play, add a service account JSON key that has access to your app in Play Console.
4. Your agent links the saved key to the app and checks that it works.

Try asking

Tools your agent uses:create_appstart_app_credential_setuplink_app_credentialvalidate_app_credentials

9. Upload to the store

Your agent previews a store-ready export and asks you to approve the app, listing, languages, sizes or artwork slots, and whether to replace or append images. If you haven’t picked a listing, it proposes the main listing. Choose a custom product page or test treatment explicitly when that is where the new files should go.

Your agent tracks the upload and tells you when AppScreens has sent the files or the store is still processing them. Submit the app for review and publish it in App Store Connect or Play Console.

Try asking

Tools your agent uses:start_project_exportpreview_store_screenshot_deploymentdeploy_store_screenshotsget_deployment

10. Update your listing text

With the same connection, your agent can update store text such as the subtitle, keywords, description and release notes. It checks the store’s length limits and shows you the change before saving it.

Try asking

Tools your agent uses:get_store_metadataget_store_metadata_guidancepreview_store_metadataapply_store_metadata

Release prep skill →

Test a new version

For an A/B test, your agent duplicates your current project as a clearly named variant, changes one idea, such as the first headline, the screenshot order or the colours, and shows you both versions side by side, as screenshots or in the store listing preview.

Upload an approved variant to an App Store product page optimization treatment or custom product page. If you don’t have one yet, your agent can create the test or page in App Store Connect after you approve it. Google Play store listing experiments are set up in Play Console, so export the variant and attach it there. Apple and Google run the test and report the results; AppScreens makes the screenshots.

Try asking

Tools your agent uses:duplicate_projectreplace_project_textrender_project_previewlist_store_listingspreview_store_listing_creationcreate_store_listingpreview_store_screenshot_deploymentdeploy_store_screenshots

A/B test skill →

Undo a change

Every change saves a new version of the project. Your agent can show you the history and restore an earlier version. Restoring adds a new version, so nothing is lost, but it doesn’t undo anything already uploaded to a store.

Try asking

Tools your agent uses:list_project_versionsget_project_versionrestore_project_version

Test a complete first run

For developers building an integration: run these steps once on a test project before relying on it in a release.

1. Read your account, capabilities and usage.
2. Create one test project and check the IDs and revision it returns.
3. Upload one screenshot, complete the upload and read back its details.
4. Apply one screenshot assignment and one caption change, then read the new revision.
5. Render a preview, review it, export the same selection and download the ZIP.
6. Restore an earlier version of the test project and check that it creates a newer revision.
7. Test store actions separately, on a test app. A project test does not check store credentials or publishing.

Automate releases with the REST API

Add a screenshot export to your CI release job. This script exports the latest saved version, waits for the render and downloads each ZIP. Rerunning the job while that export is still running picks up the same one.

• Create a “Projects only” key in Account > API Access and save it as the APPSCREENS_API_KEY secret.
• Use the project ID returned by the API or your agent. You can also find it in the project’s editor URL.
• Need fresh captures or captions first? Every step above has a REST equivalent, listed under each step and in the reference.

Export and download in CI

# Needs APPSCREENS_API_KEY (a Projects only key, stored as a CI secret) and APPSCREENS_PROJECT_ID.
set -euo pipefail
API=https://api.appscreens.com/v1
api() { curl --fail-with-body -sS -H "Authorization: Bearer $APPSCREENS_API_KEY" -H 'Content-Type: application/json' "$@"; }

# Export every enabled language and device at the latest saved version
operation=$(api -X POST "$API/exports" -d "{\"projectId\": \"$APPSCREENS_PROJECT_ID\"}")
id=$(jq -r .id <<<"$operation")

# Wait for the render (up to about 20 minutes)
for attempt in $(seq 60); do
  case $(jq -r .state <<<"$operation") in
    succeeded) break ;;
    failed|cancelled) echo "$operation" >&2; exit 1 ;;
  esac
  operation=$(api "$API/operations/$id:wait?timeoutSeconds=20")
done

if [ "$(jq -r .state <<<"$operation")" != succeeded ]; then
  echo "Export $id did not succeed within the wait period. Check its status before retrying." >&2
  echo "$operation" >&2
  exit 1
fi

# Download each ZIP
for artifact in $(jq -r '.artifacts[] | select(.kind == "export_zip") | .id' <<<"$operation"); do
  url=$(api -X POST "$API/operations/$id/artifacts/$artifact:link" -d '{}' | jq -r .url)
  curl --fail -sS "$url" -o "appscreens-$artifact.zip"
done

API reference →Tips and troubleshooting →

Show a listing preview from your own tools

Your agent opens the listing preview for a saved project on its own. This section is for screenshots that are not in AppScreens. The free App Store screenshot preview at appscreens.com/app-store-screenshot-preview (or /google-play-screenshot-preview) shows screenshots, an icon, listing text and creative assets in App Store and Google Play search results and on the product page. It needs no AppScreens account or MCP connection, and files from your device are never uploaded to AppScreens.

To use it from an agent, download the skill ZIP below and extract it. The extracted appscreens folder, the one containing SKILL.md and scripts/, is the skill directory. In the command, --root is the repository that holds your screenshots, and each --file is a path inside it, in listing order. The script writes a small launcher page to your temp folder and opens it; the launcher sends the images to the preview tab in your browser.

To preview an Apple Universal Creative Asset, add the original PNG once with --universal-artwork for a file or --universal-artwork-url for an HTTPS image. --universal-placement accepts both, header or search, and defaults to both. For a saved project, use the Universal Creative Asset slot in the tab that already has its screenshots.

Add --platform google for Google Play, --search-artwork for App Store search results artwork or the Google Play feature graphic, --header-artwork for the App Store product page header and --ad to show an App Store search ad. --no-open only writes the launcher and prints its file URL. For images that are already on the web, link prints a shareable preview link instead.

Your own tools can use a #preview= link or send image Blobs or HTTPS URLs with postMessage after the page says it is ready. In a message, send universalArtwork alongside screenshots and put appleUniversalPlacement inside preview. Up to 10 screenshots of 20 MB each.

Try asking

Open local screenshots and universal artwork

node ~/Downloads/appscreens/scripts/listing-preview.mjs open --root ~/code/cookbook \
  --file fastlane/screenshots/en-US/01.png \
  --file fastlane/screenshots/en-US/02.png \
  --file fastlane/screenshots/en-US/03.png \
  --icon assets/icon.png --name "CookBook" --subtitle "Save recipes. Plan meals." \
  --universal-artwork assets/universal.png --universal-placement both

Link to web images

node ~/Downloads/appscreens/scripts/listing-preview.mjs link --platform google \
  --name "CookBook" --subtitle "Save recipes, plan meals and shop" \
  --screenshot-url https://example.com/play/01.png \
  --screenshot-url https://example.com/play/02.png

Link format

https://appscreens.com/app-store-screenshot-preview#preview=<base64url JSON>

{
  "platform": "apple",
  "view": "search",
  "appName": "CookBook",
  "subtitle": "Save recipes. Plan meals.",
  "icon": "https://example.com/icon.png",
  "universalArtwork": "https://example.com/universal.png",
  "appleUniversalPlacement": "both",
  "screenshots": ["https://example.com/01.png", "https://example.com/02.png"]
}

Send images with postMessage

const origin = 'https://appscreens.com';
const preview = window.open(origin + '/app-store-screenshot-preview');
window.addEventListener('message', event => {
  if (event.origin !== origin || event.source !== preview || event.data?.type !== 'appscreens.listing-preview.ready') return;
  preview.postMessage({
    type: 'appscreens.listing-preview',
    preview: {platform: 'apple', appName: 'CookBook', appleUniversalPlacement: 'both'},
    icon: iconBlob,
    universalArtwork: universalPngBlob,
    screenshots: [firstBlob, secondBlob]
  }, origin);
});

Skill ZIP →Skill instructions →