Docs

shotfleet documentation

shotfleet is a macOS command-line tool that takes your localized App Store and Google Play screenshots from one English Maestro flow, in every language your app has, and checks that each one is in the right language. This page covers how to install shotfleet, take your screenshots, check them and hand them to fastlane. If something here is wrong or unclear, email me at hello@shotfleet.com.

Last checked against version 0.1.12 on 2026-11-11.

Requirements

Install

curl -fsSL https://shotfleet.com/install.sh | sh   # then open a new Terminal window
shotfleet doctor --fix           # checks Maestro, Java, Xcode, Android SDK; shows what is missing, asks once, then fetches Maestro and Java

Make sure the right Xcode is selected (xcode-select -p shows which one). If your app is iOS only, you can ignore the Android part of doctor. The first doctor can take a minute while macOS gets its text recognition ready.

The installer downloads the Apple silicon archive, compares it with its published SHA-256 checksum, and puts a link to shotfleet on your PATH. shotfleet is free and open source (MIT license): every command and every language, with no key.

To update, run the install line again. It replaces the program. shotfleet doctor tells you when a newer version is out.

There is also an installer you can double-click. Each release is published as a signed, notarized package, https://shotfleet.com/download/shotfleet-macos-arm64.pkg. It puts the program in /usr/local/lib/shotfleet and links shotfleet into /usr/local/bin; macOS asks for your password. Use it if you can't use the curl line, or if a browser-downloaded copy shows "Apple could not verify ...".

Prefer Homebrew? brew install noloman/tap/shotfleet installs the same signed, notarized build from my own tap. Homebrew keeps it in its own folder and links shotfleet into /opt/homebrew/bin. Update with brew upgrade; doctor tells you the right command. Homebrew doesn't install Maestro or Java: shotfleet doctor --fix does that. The install line is still the main way. Pick one of the two: if the install line already put a shotfleet link in /opt/homebrew/bin, remove that link before you run brew install.

Quickstart

Build the app once for the simulator in Xcode (Debug) first, then, in your project folder:

shotfleet init
shotfleet init path/to/MyApp.app path/to/app-debug.apk   # or name a simulator build (Debug-iphonesimulator) and/or an APK yourself

shotfleet init without arguments only reads folders, never builds. For iOS it takes the newest Debug-iphonesimulator app in Xcode's default DerivedData folder (~/Library/Developer/Xcode/DerivedData) whose info.plist points at an Xcode project in this folder, up to two folders below it, or above it. For Android it takes the newest debug APK under build/outputs/apk/debug in this folder or up to two folders below it (app/build/outputs/apk/debug, <module>/build/outputs/apk/debug, android/app/build/outputs/apk/debug; a flavour folder such as apk/free/debug counts too). It prints which build it chose and how old it is. If it finds nothing it exits with the exact xcodebuild and ./gradlew assembleDebug commands to run; then run shotfleet init again.

  1. Edit the generated flow.yaml: Maestro steps in English. Navigate by the text users see and add a takeScreenshot: for each store image. No appId is needed: shotfleet uses each build's own id, so one flow serves iOS and Android.
  2. Try one language: shotfleet run --locales en
  3. Run it on every language your app ships: shotfleet run shotfleet.toml.
  4. Run them all: shotfleet run (finds ./shotfleet.toml; both platforms if the file has both, --platform ios for one).
  5. Review out/index.html (out-ios/ and out-android/ if the config has both platforms). It is a grid with a row per language and a column per screen, and problems are outlined in red and marked "problem" in words. Every screenshot has alt text (language, screen, verdict) for screen readers.
  6. Export to fastlane: shotfleet export out --fastlane fastlane/ (out-ios or out-android if the config has both). That writes deliver's screenshots/<locale>/ or supply's metadata/android/<locale>/images/phoneScreenshots/. Languages that failed a check are skipped, so a bad screenshot never reaches a listing.
shotfleet run --locales en
shotfleet run
shotfleet run --platform ios
shotfleet export out --fastlane fastlane/

Uploading

shotfleet stops at fastlane's folders, and fastlane does the upload. These commands upload the screenshots and leave everything else alone:

# App Store: replaces the screenshots of every language folder in fastlane/screenshots
fastlane deliver --skip_binary_upload --skip_metadata --overwrite_screenshots --force

# Google Play: uploads metadata/android/<locale>/images/phoneScreenshots
fastlane supply --skip_upload_apk --skip_upload_aab --skip_upload_metadata --skip_upload_changelogs --skip_upload_images

Run shotfleet check fastlane/ right before uploading: export already skips languages that failed, and the check also catches folders you edited by hand.

shotfleet export out --fastlane fastlane/ --print-upload prints that command with your folder in it. It only prints; shotfleet never uploads anything and never sees your Apple or Google credentials, fastlane uses its own. --force makes deliver skip the HTML preview it would otherwise wait on.

Prefer the asc CLI? Its README lists an asc screenshots upload command that takes one language and one device type at a time, for example asc screenshots upload --version-localization <id> --path fastlane/screenshots/en-US --device-type IPHONE_65 --replace --confirm (flags as listed there on 2026-10-07; asc screenshots upload --help has the current ones). The folders export writes are named by store locale, so the --path is one of them.

How it works

shotfleet reads the translations compiled into your app and rewrites every selector in the flow to match any translation of that English label. If "Next" has two keys, German matches (Nächste|Weiter). Selectors that use id: pass through untouched.

Fresh state: each language starts from a clean install. On iOS that is clearState; on Android shotfleet clears the app data itself, because clearState would also erase the app language.

Check screenshots you already have

run needs Maestro, or on iOS your own XCUITest tests (new in 0.1.6). check doesn't. Already use fastlane snapshot (XCUITest) or screengrab (Espresso)? check works on those screenshots, and it's free. Point it at your fastlane folder and your app build:

shotfleet check fastlane/screenshots                       # snapshot: screenshots/<locale>/
shotfleet check fastlane/metadata/android                  # screengrab: <locale>/images/phoneScreenshots/
shotfleet check fastlane/ --app path/to/MyApp.app          # a fastlane folder with both: the build picks its half
shotfleet check shots/ --locale en --app path/to/MyApp.app # a flat folder of one language's PNGs

Without --app, check looks for your app build the way init does, in the folder you run it from: the newest Debug simulator build of your Xcode project, or your Gradle debug APK. It says in one line which build it used, or that it found none.

screengrab puts a timestamp at the end of every file name (01Home_1773697012807.png), different in every language. check ignores it when it matches screens across languages, and the report keeps the real names. If one language has the same screen twice with two timestamps (say, left over from an earlier run), that's a problem.

You don't need export with fastlane: snapshot and screengrab already write into fastlane's folders. export is for screenshots from shotfleet run.

Store codes are mapped back to your app's languages (de-DE to de, no to nb, zh-CN to zh-Hans). The report (check.json and index.html) goes to ./shotfleet-check (change it with --report), and your fastlane folders are never touched. After capture or on an existing folder, every screenshot's text is compared against your app's own strings. On iOS, shotfleet reads the text straight from the app while each screenshot is on screen; otherwise, and for screenshots made by other tools, it uses macOS's built-in text recognition. It reports:

When check has no build (no --app, and none found where you run it), it relies on language detection, which cannot judge short screens; pass --app for the full check.

export also takes a plain <locale>/*.png folder of such a set (Apple Watch, Mac, Apple TV, Vision Pro) once shotfleet check <folder> --report <folder> has written its check.json there; it copies the set into screenshots/<locale>/ next to your iPhone and iPad sets. Size and count rules only: shotfleet captures iPhone, iPad and Android screens, not these.

Use your existing XCUITest screenshot tests (iOS)

Already have XCUITest tests that take your screenshots, with XCTAttachment or fastlane's SnapshotHelper? run can run those instead of a Maestro flow. It builds your test bundle once, then runs it on several simulators at the same time, one language each, collects what your tests saved and checks it. In most cases you don't change your test code (an XCTAttachment needs a name and lifetime = .keepAlways, see below), and you don't need Maestro or Java for this (new in 0.1.6; tested on iOS 26.4 simulators).

[ios]
locales = ["de", "ja", "ar"]      # default: every language the app ships

[capture]                         # instead of flow = "flow.yaml": a config has one or the other
build = "xcodebuild build-for-testing -scheme MyApp -destination 'generic/platform=iOS Simulator' -derivedDataPath .shotfleet/build"
xctestrun = ".shotfleet/build/Build/Products/*.xctestrun"   # has to match exactly one file after the build
only_testing = ["MyAppUITests/ScreenshotTests"]             # optional
screenshots = "auto"              # "attachments" (XCTAttachment), "fastlane" (SnapshotHelper) or "auto" (both)
timeout = 900                     # seconds per language

shotfleet init --capture writes this for you, with the shared scheme that has your UI tests. Then shotfleet run as usual. run --no-build skips the build and uses the .xctestrun that's already there. shotfleet doctor (run in the config's folder, or shotfleet doctor path/to/shotfleet.toml) sees the [capture] table and stops asking for Maestro for iOS.

How it works, and what your tests need:

iOS only for now: on Android, run still needs a Maestro flow. I tried this by hand first, on my fixture app (2 simulators at once, German and Japanese) and on a real app's SnapshotHelper test, where check found a real bug. The device test for the finished feature (tools/fixture-byoc-e2e.sh) passed on 2026-10-07, on iOS 26.4 simulators: your tests with XCTAttachment and with SnapshotHelper, German and Japanese on two simulators at once, and the missing-.keepAlways case, which is reported as a failed language.

A fastlane lane that stops on wrong screenshots

Put this in fastlane/Fastfile. fastlane runs sh from the fastlane/ folder, hence the cd ... Any problem makes check exit with 1, which fails the lane, so nothing is uploaded:

platform :ios do
  lane :screenshots do
    snapshot
    sh("cd .. && shotfleet check fastlane/screenshots")
    deliver(skip_binary_upload: true, skip_metadata: true, overwrite_screenshots: true, force: true)
  end
end

platform :android do
  lane :screenshots do
    screengrab
    sh("cd .. && shotfleet check fastlane/metadata/android")
    supply(skip_upload_apk: true, skip_upload_aab: true, skip_upload_metadata: true, skip_upload_changelogs: true, skip_upload_images: true)
  end
end

Paparazzi, Roborazzi and Compose preview tests

Their file names don't carry the language unless you put it there (Paparazzi writes <package>_<Class>_<test>.png, plus a name you can add), so check can't sort one flat folder into languages. Give each language's images their own folder, with the same names in every language, and check the parent folder. If your test names end in the language (..._home_de.png):

for lp in en de ja; do
  mkdir -p shots/$lp
  for f in src/test/snapshots/images/*_$lp.png; do b=$(basename "$f"); cp "$f" "shots/$lp/${b%_$lp.png}.png"; done
done
shotfleet check shots/ --app app/build/outputs/apk/debug/app-debug.apk

For one language, shotfleet check <folder> --locale de works on the flat folder as it is, but then there's nothing to compare it with, so copies and missing screens aren't checked. These tools draw your screens without a device, so there's no real status bar. Neither store asks for a device, only for screens that show your app. check reads the text, the sizes and the alpha channel, but it can't tell you whether a drawn screen looks like your app on a phone (fonts can differ, mostly in Chinese, Japanese, Arabic and Indic scripts). I haven't tried it on a real Paparazzi folder yet.

Config

The whole config can be this (shotfleet init writes it):

[ios]
app = "path/to/MyApp.app"

[android]                 # optional: the same file and flow serve both platforms
apk = "path/to/app-debug.apk"

Everything else is read from the build or has a default; set it only to change it. A typo or a wrong type is refused with a one-line message before anything runs.

Config keys, the section they go in and their defaults
KeySectionDefaultWhat it does
appiosnoneThe simulator build (Debug-iphonesimulator).
apkandroidnoneThe debug APK.
flowios, androidflow.yamlThe English Maestro flow, shared by both platforms (an appId: header is set for you).
outios, androidout, or out-ios and out-android when the file has both platformsOutput folder.
parallelios, android4Simulators (emulators on Android).
localesios, androidevery language the app hasLanguages to capture, for example ["de", "ja"].
capacityios, androidwarnwarn prints a note when the Mac is short of memory or swapping. off turns the note off. The run itself is never changed.
settle_msios, android1000Before each screenshot, wait up to this many milliseconds for the screen to stop moving. 0 turns it off.
clockios, androidnoneA fixed date and time such as "2026-10-27 10:00". On Android it sets the emulator clock (Google APIs images only) and the status bar; on iOS only the status bar time. Without it the status bar shows 9:41.
base_localeios, androidenThe language your flow is written in.
stringsios, androidread from the buildTranslation files as globs, relative to the config (see below).
bundle_idiosread from the appThe bundle id. On Android the package is read from the APK.
device_typeiosthe 6.9" iPhone (com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro-Max)The simulator device type.
runtimeiosnewest installedThe simulator runtime. Default: the newest one installed, except iOS 27.0. Those simulators froze at boot in some of my runs, so run skips them, uses the newest other runtime and says which one in a line. If 27.0 is the only runtime installed, run uses it and warns. doctor names the runtime run will use and why, or the one your config sets. A runtime you set here is always used: runtime = "com.apple.CoreSimulator.SimRuntime.iOS-26-4" (xcrun simctl list runtimes shows the ids). Installing a newer runtime can still change what run uses, so pin the one you have tested.
device_typesiosnoneSeveral sizes from one flow, for example ["iPhone 17 Pro Max", "iPad Pro 13-inch (M5)"]; output goes to out/<device>/, check out and export out handle both, and the App Store takes both in one folder.
rootandroidfalseRun adb root after boot, before shell commands. Google APIs emulator images only.
devicesandroidphone["phone", "tablet"]: phone 1080x1920 and tablet 1440x2560 (both 9:16, so Play can recommend the listing); output goes to out/<device>/, exported to phoneScreenshots and tenInchScreenshots. "tablet-7" adds a 7" tablet, 1080x1920 at 280 dpi, exported to sevenInchScreenshots. Entries can also be tables with your own size, for example {name = "tablet-landscape", base = "tablet", size = "2560x1440", density = 320, orientation = "landscape"}, exported to the Play folder of base. "fold", "fold-book" and "fold-tabletop" run on one foldable emulator (unfolded, half open like a book, half open like a laptop), one language at a time, exported to tenInchScreenshots; set its name with avd_fold. The inner display is captured through the emulator console because adb screencap is black there; not yet verified on a device.
[ios]
flow = "flow.yaml"
out = "out"
parallel = 4
stall_s = 900   # seconds without a new screenshot before a hung simulator or flow is stopped and retried
settle_ms = 1000   # before each screenshot, wait up to this many milliseconds for the screen to stop moving (0 turns it off)
locales = ["de", "ja"]
base_locale = "de"
device_types = ["iPhone 17 Pro Max", "iPad Pro 13-inch (M5)"]

[android]
devices = ["phone", "tablet"]

Flutter, React Native, .NET MAUI, Unity and translation-platform exports

These frameworks do not keep their translations in a form shotfleet can read inside the built app, so point it at the source files instead. Add strings to either section (globs, relative to the config):

strings = "lib/l10n/*.arb"                      # Flutter
strings = "src/locales/*/translation.json"      # React Native / Expo with i18next
strings = ["Resources/Strings/*.resx"]          # .NET MAUI

Supported: .arb, i18next and react-intl .json (nested keys, _one and _other plurals), .xcstrings, .strings, .stringsdict, Android and Compose strings.xml, XLIFF (.xlf, .xliff), .resx, gettext .po, .properties, and CSV with one column per language (Unity Localization, spreadsheets). ICU plurals and placeholders (%d, %1$@, {name}, {{name}}) are understood. The language comes from @@locale, the file name (app_de.arb, Resources.de.resx) or the folder (locales/de/, values-de/). check takes the same files:

shotfleet check fastlane/ --strings 'lib/l10n/*.arb'

Hooks

Nothing here is on by default: a config without these tables behaves exactly as above. Hooks run your own commands (/bin/sh, in the config's folder, output on stderr) around a run and an export:

[hooks]
before_run   = "make build-sim"                 # a string, or a list of commands run in order
after_run    = 'curl -sS -X POST -H "Content-type: application/json" "$SLACK_WEBHOOK_URL" --data "{\"text\":\"shotfleet $SHOTFLEET_PLATFORM: $SHOTFLEET_PROBLEMS problem(s)\"}"'
before_export = "git diff --quiet"              # a non-zero exit stops the export
after_export  = 'fastlane deliver --skip_binary_upload --skip_metadata --overwrite_screenshots --screenshots_path "$SHOTFLEET_FASTLANE/screenshots"'
# hook_timeout_s = 1800                         # default 600 per command

A failing before_* hook stops the command (exit 2); a failing after_* hook makes the exit code 1, so CI notices. Variables on every event: SHOTFLEET_EVENT, _VERSION, _CONFIG, _PLATFORM, _OUT; before_run and after_run also get _BUNDLE_ID and _LOCALES (empty unless restricted); after_run gets _EXIT, _PROBLEMS, _REPORT (<out>/check.json); the export hooks get _FASTLANE, _REPORT (and _EXIT after the export). --no-hooks skips them for a dry run.

Overrides

Overrides replace what shotfleet would tap for one language. They are the fix for a collision warning ('Next' -> 'İleri' also means 'Advanced') and for labels that are not in your app's strings:

[overrides.tr]                         # the language as shotfleet names it: tr, pt-BR, zh-Hans...
"Next" = "İleri"                       # literal text
"Advanced" = "re:Gelişmiş.*"           # "re:" = a regular expression
"Search" = "Ara"

Inputs

Inputs set the text a flow types, per language. Write inputText: ${name} in the flow and give the values in the config:

[inputs]                               # typed in every language that has no value of its own
name = "Alex"
[inputs.ja]                            # the language as shotfleet names it; pt covers pt-BR too
name = "田中"

The value goes into that language's flow as a Maestro env: entry. This works on iOS. Maestro hands any flow to any emulator, so on Android a name that has a per-language value is read from a small script (shotfleet_vars.js) that picks the emulator's row by MAESTRO_DEVICE_UDID. Maestro 2.11.0 sets that variable to the emulator's serial: German and Japanese values showed up as typed in screenshots (device run 2026-10-04, one emulator, one language after the other; two emulators at once and Arabic not run). Maestro 2.0.10 does not define it, so on 2.0.10 Android runs type the [inputs] defaults only. Check the first screenshots in a script like Japanese or Arabic. Text you type is not translated by itself: it stays the same in every language unless you set [inputs] (iOS; on Android it needs a Maestro that sets MAESTRO_DEVICE_UDID, which 2.11.0 does and 2.0.10 does not).

Flow tips for every language

A flow that works in English can still break in Turkish or Chinese. These tips come from runs on my own apps. They are about Maestro; shotfleet only translates the texts you write in selectors. I read Maestro's docs for every snippet on 2026-10-08. Where I say "ran", I ran it on Maestro 2.0.10, the version of all the runs in this section. Where I say "not run", the snippet comes from Maestro's docs and I have not tried it on a device.

Tap by id where you can

An id has no language. shotfleet leaves id: selectors alone, so the step taps the same view in German, Arabic and Japanese. Use ids for icons and tabs, and for any button your app lets you name (an accessibility identifier on iOS, a resource id on Android).

- tapOn:
    id: "login-button"

Ran on iOS and Android (Maestro 2.0.10, the obytes Expo template, 2026-10-03). Maestro reads text and id as regular expressions, so keep an id specific.

A regex can't be translated

A step like assertVisible: 'Interviewing on.*' passes in English because the app builds that line from %@ on %@. shotfleet has no way to turn a regex into German, so it keeps the English words and the step fails in every other language. In one of my runs it passed in English and failed in all 17 others. Before the first device starts, run now matches each selector that isn't an app text against the app's English texts, where %@, %d, %1$s and {name} stand for any text. If it fits one, you get a warning with the selector's name: 'Interviewing on.*' matches '%@ on %@' in the base language only. Use an id:, or pin the step to a nearby label that is in your app's strings, which shotfleet does translate. Unit tested, not run on a device.

When two texts are the same word

Two real cases from my runs. In Turkish, "İleri" means both "Next" and "Advanced". An onboarding page had an "Advanced" option and a "Next" button, and the tap on "Next" hit the option, so Turkish failed on every screenshot on Android (0 of 6). shotfleet warned about it before the run (tr: 'Next' -> 'İleri' also means 'Advanced'). In Chinese, a small pill on a card read "基准" and so did the Benchmarks row below it. A scroll that waits for the text stopped at the pill, and the tap on the row found nothing.

Pin the step to a neighbour with below: or above:. shotfleet translates the anchor text too:

- tapOn:
    text: "Next"
    below:
      text: "3+ years of dedicated training"

Ran on iOS and Android, Turkish included (Maestro 2.0.10, WOD Tracker, 2026-10-07). Or pick the nth match with index:. Maestro counts from 0, so index: 1 is the second match. Not run, and the order of matches is Maestro's, so look at the frame:

- tapOn:
    text: "Next"
    index: 1

Or skip the text and swipe a fixed distance. Where the list is longer than the screen, a few swipes to the end leave only one of the two texts on screen:

- repeat:
    times: 4
    commands:
      - swipe:
          start: "50%,80%"
          end: "50%,15%"
      - waitForAnimationToEnd:
          timeout: 1500
- tapOn: "Benchmarks"

Ran on an iPhone simulator in Chinese, Polish, Dutch and Portuguese (Maestro 2.0.10, WOD Tracker, 2026-10-07). Maestro's docs write the pair with a space, start: 90%, 50%; the form without a space is the one I ran.

scrollUntilVisible has two forms

Maestro takes the element as a plain string or as a selector object. Both are valid:

- scrollUntilVisible:
    element: "Benchmarks"

- scrollUntilVisible:
    element:
      text: "Benchmarks"
    direction: DOWN
    timeout: 30000

The object form with text: ran on iOS and Android (Maestro 2.0.10, WOD Tracker). Use it on 0.1.7 and older: those versions translate the text in the object form and leave the plain string in English, so on an iPhone run in Hindi and Turkish the plain string failed both languages (0 of 2). From 0.1.8 both forms are translated. Maestro's defaults are direction: DOWN and a timeout of 20000 ms, and the step fails when the timeout runs out. If the row ends up behind a tab bar, centerElement: true keeps scrolling until the element is more than 30% away from the edge of the screen (not run). In my Hindi run the row stopped behind the tab bar and the tap hit the Train tab instead.

Wait for a stable screen before the first screenshot

A screenshot taken while the screen is still drawing can show a blank frame or a half-loaded one. Wait for a text that only that screen has, then let the animation finish:

- extendedWaitUntil:
    visible: "Start here"
    timeout: 60000
- waitForAnimationToEnd:
    timeout: 4000
- takeScreenshot: 01_train

Ran on iOS (Maestro 2.0.10, WOD Tracker). extendedWaitUntil takes its timeout in milliseconds. waitForAnimationToEnd does not fail: Maestro's docs say it carries on when its timeout (15000 ms by default) runs out, so on its own it is not proof that the screen is still. The text goes first for that reason. A Flutter debug build can take 30 s to draw on a fresh emulator, so give that wait a long timeout.

Wait for a web view's own text

In one of my apps a detail page is a web view, and its screenshot came out blank. The flow took the picture before the page had loaded. Wait for a text from the page, then let the animation finish. shotfleet's own wait before a screenshot helps with animations, not with late network or web content, so the flow has to wait for that content itself:

- extendedWaitUntil:
    visible: "A text from the page"
    timeout: 30000
- waitForAnimationToEnd:
    timeout: 3000
- takeScreenshot: 03_detail

Seen once, on 2026-10-08 (shotfleet 0.1.6); I did not write down the Maestro version for this one. "A text from the page" stands for a text from your own page.

back may not leave a screen on iOS

On Maestro 2.0.10 with an iOS 26.4 simulator, the back step did not pop the navigation stack in one of my apps, and the next screenshot showed the same screen. Tapping the back chevron in the navigation bar did work, either with a point tap on its spot or by its id:

- tapOn:
    id: "nav-back"

Ran on iOS (Maestro 2.0.10, 2026-10-08). I saw this on 2.0.10 only, and I have not checked it on 2.11.0, so it may be fixed there. "nav-back" stands for the id your app gives the chevron.

Two Android emulators at once: one lost its Wi-Fi icon

With two emulators running in parallel, the screenshots from one of them had no Wi-Fi status icon. Putting svc wifi enable in the shell list under [android] fixed it. shotfleet runs those commands on every emulator after it boots, on every run (see Device setup):

[android]
shell = ["svc wifi enable"]

Seen once, in one of my apps on 2026-10-08, and I do not know why the icon went missing.

check does not prove that a tap hit the right button

check reads pictures. It sees a wrong language, a copy of another language's image, a missing screen, a blank frame and a wrong size. It cannot know which screen you meant to reach. In one WOD Tracker iPhone attempt the run exited 0 with 8 of 8 screenshots and check said 0 problems, but the Hindi "Benchmarks" frame showed the Train screen. The row sat behind the tab bar and my tap hit the Train tab. A Train screen in Hindi is a perfectly good screen. I found it by looking at every frame.

A guard in the flow fails the language when the tap went wrong. Put an assertVisible on a text that only the target screen has (not one the tab bar shows too) between the tap and the screenshot, and shotfleet translates it for each language:

- tapOn: "Benchmarks"
- assertVisible: "Benchmark results"
- takeScreenshot: 02_benchmarks

Not run; I had no such guard in that attempt, which is the point. "Benchmark results" stands for a text from your own screen. Expected content can do the same job after the run, with a literal text per language. And look at the frames of a new flow once before you trust it.

Device setup

Device setup runs your own commands once per simulator or emulator, right after it boots (iOS: after the status bar is set), so an app with a screenshot switch, dark mode, a location or a granted permission looks the way you want:

[ios]
simctl = ["ui $UDID appearance dark", "location $UDID set 52.3676,4.9041"]   # xcrun simctl <args>; $UDID is the simulator's id
[android]
shell = ["setprop debug.myapp.demo 1", "settings put system font_scale 1.0"]  # adb -s <serial> shell <command>

A command that fails stops the run before anything is captured (exit 2) and prints the command. iOS commands apply to every language: one Maestro process serves all simulators, so a different command per language is not possible. The Android commands are unit-tested as command lines; whether a given setprop or settings command takes effect on your emulator image has not been tried on a real one.

Expected content

Expected content checks that what you seeded is really on screen, per language. Name the screenshot as in the flow (takeScreenshot: 01_home):

[expect.01_home]
any = ["Senior iOS Engineer"]          # at least one of these is on screen
[expect.01_home.de]                    # only for the German screenshot (pt covers pt-BR)
all = ["Steinmännchen"]                # every one of these is on screen
[expect.03_log]
not = ["No workouts yet", "Keine Workouts"]   # the empty state must not show
[expect.02_benchmarks]
key = "benchmarks_title"               # the text of this string key of your app, in each language, is on screen

run checks these automatically; for screenshots you already have, use shotfleet check out/ --content shotfleet.toml (no key or account). A missing or forbidden text is a problem line, and a table for a screenshot that does not exist is reported too. Case, accents and spacing are ignored. On iOS the text is the app's own, so a match is exact in any script. On Android it is read from the picture: a text in a script macOS cannot read (Greek, Hebrew, most Indic) is reported as a note, could not verify, never as a pass. This proves the strings you list are present, not that the data looks right.

key names a string of your app (its key in your .strings, .arb or strings.xml). check looks for that string's text in the screenshot's own language, so you do not type the translations, and a green run that captured the wrong screen gets a problem line. It needs the app's strings (run has them; for check pass --app or --strings). A wrong key, or a text with a placeholder in it, is reported. Like the other expectations it does nothing until you add an [expect...] table.

Plugins and the rest

shotfleet foo runs shotfleet-foo from your PATH (like git and gh), when foo is not a built-in command. run, check and export take --json and use stable exit codes, so they script like any other tool; SHOTFLEET_OCR or --ocr-command swaps the text reader; strings = "glob" swaps the translation source.

License

shotfleet is free and open source under the MIT license. There is no key, no activation and no license server, and every command works in every language. The source is on GitHub. If shotfleet saves you time, you can sponsor it on GitHub. See the license page for the terms.

In CI

run, check and export take --json: the result goes to stdout as JSON (exit, screenshots, problems, notes and unverified for run and check, plus coverage when check can tell the store and compare with --compare, merged over every device or platform checked, plus reports (one {report, problems} each) when there are several; exit, exported, skipped for export) and progress goes to stderr. Exit codes: 0 all good, 1 problems found, 2 setup error (the message says what to fix), 130 interrupted.

Checking needs only a Mac (it uses macOS text recognition), with no simulators, so it fits a pull-request job on GitHub's macOS runners. check needs no key or account. The recipe as written (the build step, then check with --app) has not been run on GitHub yet. The installer, shotfleet --version, doctor and check on sample screenshots did run on GitHub's macos-14 and macos-15 runners (version 0.1.1 on 2026-10-05, version 0.1.6 on 2026-10-08).

# .github/workflows/screenshots.yml
on: pull_request
jobs:
  check-screenshots:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - run: xcodebuild -scheme MyApp -sdk iphonesimulator -configuration Debug -derivedDataPath build build
      - run: curl -fsSL https://shotfleet.com/install.sh | sh   # Apple silicon runner
      - run: shotfleet check fastlane/ --app build/Build/Products/Debug-iphonesimulator/MyApp.app --json > check.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: screenshot-check
          path: |
            check.json
            shotfleet-check/

In CI, run and export work like on a Mac: there is no key or license server to reach.

With AI agents

shotfleet mcp is an MCP server with check, run and doctor tools. Add it to Claude Code with claude mcp add shotfleet -- shotfleet mcp, or to any MCP client as the command shotfleet mcp.

Over MCP, no command written in your config runs unless you pass hooks: true to run. Without it, run skips the [hooks] and refuses a config that has a [capture] build, [ios] simctl or [android] shell commands. check takes no ocr_command over MCP; use --ocr-command in your terminal. A config from a repo you just cloned can hold any shell command, so read it first.

There are also three agent skills that ship with the program: shotfleet (install, set up, run, check and troubleshoot), shotfleet-ci (add shotfleet check to CI) and shotfleet-review (turn a check report into a fix list). Claude Code, Cursor, Codex, Gemini CLI and GitHub Copilot all load skills from a folder. One command puts them in the right folders:

shotfleet skill install
shotfleet skill install --project
shotfleet skill install --dir <folder>

shotfleet skill install copies them into ~/.claude/skills (Claude Code and Cursor read it) and ~/.agents/skills (Codex, Gemini CLI, GitHub Copilot and Cursor read it). With --project they go into ./.claude/skills and ./.agents/skills in your project, so you can commit them for your team. --dir <folder> copies them into one folder you choose. Skills that are already there are kept unless you pass --force. Start a new agent session after you install them.

The skills are also in a public repo, so you can install them without shotfleet first. In Claude Code: /plugin marketplace add noloman/shotfleet-skills, then /plugin install shotfleet@shotfleet (the skills plus the MCP server). For other agents: gh skill install noloman/shotfleet-skills --all --scope user. More in the repo's README.

Nothing to sign in to: your agent uses the same free CLI you do.

Limits

Common questions

Does shotfleet upload my screenshots to App Store Connect or Google Play?

No. export copies the languages that passed into fastlane's folders, and fastlane does the upload (deliver for the App Store, supply for Google Play).

Do I need Maestro?

Only for run, which drives your app with Maestro 2.x (on iOS, run can use your own XCUITest tests instead, new in 0.1.6). check doesn't need Maestro: it works on the folders fastlane snapshot and screengrab write, and on a plain folder per language.

I already use fastlane snapshot. Do I have to switch?

No. Keep your UI tests and point check at the folder they write (see Check screenshots you already have). With --app it finds screenshots that came out in the wrong language, copies, missing screens and store-rule problems.

Does it work with Flutter or React Native?

Yes, from your translation files (the strings key), in the cases I ran: I ran it end to end on one real Flutter app (wger) and one real Expo app (the obytes template), on iOS and Android, on 2026-10-03. Other apps and bare React Native are not run yet.

Does it work on an Intel Mac?

No. It needs an Apple silicon Mac, and the installer refuses Intel Macs.

Does it add device frames or marketing captions?

No. It takes and checks the raw screenshots of your app. For frames and captions, look at ButterKit or AppScreens (how they compare).

Is it free?

Yes. shotfleet is free and open source (MIT license): every command and every language, no key and no account. See the license page.

Is shotfleet or this site in my language?

No, the site, the docs and the tool's messages are in English. What it captures is whatever languages your app ships.

Manuel Lorenzo Parejo · License · Privacy