Preview Locally

Once you have created a release, you can preview your release with the shorebird preview command: on an Android device or emulator, on a physical iPhone or iPad, or, for a macOS, Linux or Windows release, on the computer you run it on.

shorebird preview

This will download the release artifacts for the selected app release version, install the app on the selected device, and start the application.

On Android, Shorebird 1.6.135 and newer uninstall the app before installing the release, which deletes its data and any files in its app-specific storage. Older versions clear the app’s data instead.

Tip

shorebird preview can be used on any computer that is configured for Flutter development, not just the computer that was used to create the release. This is useful for verifying releases that were created on a CI/CD server.

Options

Without options, shorebird preview asks which release and which device to use. The options you’re most likely to need:

• --release-version 1.0.0+1 picks the release, and --device-id (-d) the device or Android emulator. iOS simulators aren’t supported.
• --track staging previews the release with patches from that track instead of stable. See Test the patch on your device.

Run shorebird preview --help for every option.

Android keystore options

To sign an Android preview with your deployment keystore instead of a debug key, pass it with --ks and the key’s alias with --ks-key-alias. --ks-pass takes the keystore password prefixed with pass: (the password itself) or file: (a file that holds it). Add --ks-key-pass if the key’s password differs from the keystore’s.

shorebird preview \
  --platform android \
  --release-version 1.0.0+1 \
  --ks /path/to/keystore.jks \
  --ks-pass pass:my_keystore_password \
  --ks-key-alias my_key_alias

iOS signing

On iOS, shorebird preview installs the app from the .xcarchive that shorebird release ios built, not the IPA you upload to App Store Connect. A device only installs that app if the provisioning profile it was signed with allows it:

• A development or ad hoc profile that includes the device: the preview installs.
• An App Store distribution profile: no device installs it, and shorebird preview fails with an error about the provisioning profile. TestFlight builds are signed the same way, so they don’t help either.

The archive is signed with the Release configuration’s settings in Xcode’s Signing & Capabilities tab. --export-options-plist and --export-method don’t change it: they only decide how the IPA is signed when Xcode exports it from the archive.

Preview and ship the same release

Sign the archive for development and export the IPA for the App Store. One release then installs on your test devices and is the build you upload:

1. In Xcode, select the Runner target, open Signing & Capabilities, and check Automatically manage signing. Xcode signs the archive with your Apple Development certificate and a development profile. If you sign manually, choose a development or ad hoc profile for the Release configuration instead.
2. Run shorebird release ios. Without --export-method or --export-options-plist, Xcode exports the IPA for the App Store, re-signing it with your distribution certificate. If you sign manually, pass an ExportOptions.plist that names your App Store profile.
3. Upload the IPA from build/ios/ipa as usual, and preview the release with shorebird preview.

The device has to be in the profile when you release. A device added to the profile later can’t install that release, so create a new release to preview on it.

Add-to-app

Because Flutter modules (.aars and .xcframeworks, created with shorebird release aar and shorebird release ios-framework, respectively) are embedded in apps that Shorebird does not know about, shorebird preview does not support them.

To test these releases, you can use your normal development flow with the artifacts that Shorebird creates. For example, if you launch your app normally from Xcode or Android Studio with a Release configuration, you will see Shorebird logs in its output. If you have published a patch, it should be downloaded on the first run of your app and visible on subsequent runs.

Previewing patches

To try a patch on your device before your users get it, publish it to the staging track and preview the release with --track staging. The Quick Start walks through it, from the release to seeing the patch apply.

Tip

For programmatic checks or showing custom update prompts, see the Update Strategies guide.

What’s next

Create a PatchPush over-the-air updates to your published release.

Staging PatchesValidate patches in a staging environment before promoting to production.