---
title: "Preview Locally"
description: "Run a release, and its patches, on a device, emulator or your computer to check them before your users get them."
---

Once you have [created a release](/code-push/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](/getting-started/#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](/code-push/release/#create-an-exportoptionsplist-file) 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](/getting-started/#ship-your-first-patch) walks through it, from the release to seeing the patch apply.

Tip

For programmatic checks or showing custom update prompts, see the [Update Strategies](/code-push/update-strategies) guide.

## What’s next

[Create a Patch](/code-push/patch)Push over-the-air updates to your published release.

[Staging Patches](/code-push/guides/staging-patches)Validate patches in a staging environment before promoting to production.