Quick Start

Watch the video: Get started with Shorebird

This guide installs Shorebird, adds it to your Flutter app, and takes you through the whole Code Push loop on your own device: create a release, install it, change some Dart code, publish a patch and watch it apply. You don’t need to submit anything to a store to try it.

Prerequisites

A computer that can already build your app for the platform you want to try, with that platform’s tools installed:
- Android: the Android SDK and a JDK (Android Studio installs both).
- iOS and macOS: a Mac with Xcode. To run an iOS release you also need a physical iPhone or iPad and an Apple Developer account to sign the app; shorebird preview doesn’t support the iOS simulator.
- Windows: Visual Studio with the “Desktop development with C++” workload.
- Linux: the packages Flutter’s Linux setup lists.
Flutter’s install guide covers each platform’s tools. You don’t need Flutter itself: Shorebird installs and builds with its own copy.
git 2.25.1 or newer.
About 3 GB of free disk space where Shorebird installs. The install script stops if there’s less.

New to Flutter? What is Flutter? explains how it works, and Flutter for Beginners builds a first app with Shorebird step by step.

Installation

Sign up for a free Shorebird account.

CREATE AN ACCOUNT

Sign up with a Google or Microsoft account, personal or work. Shorebird has no email-and-password sign-in. Teams on the Enterprise plan can sign in through their company’s SAML SSO instead. Use the same method every time: your account signs in with the method you first used.

Your apps live in an organization. A new account usually has none, so the first time you sign in, the console asks you to name one or to join one you’ve been invited to. If you go straight to the CLI instead, shorebird init creates one named after your email address. Your first organization is free and you can rename it at any time, but creating another needs a paid plan.

If your team already uses Shorebird, accept their invitation before running shorebird init, so your app goes into their organization. Creating an app there needs the Owner, Admin, or App Manager role.
Install Shorebird.
Paste the following into any AI assistant (Claude, ChatGPT, etc.) for guided installation:
```
Install Shorebird on my machine. Shorebird is a Flutter code push tool.

Mac/Linux:
curl -fsSL https://shorebird.dev/install.sh | bash

Windows:
Set-ExecutionPolicy RemoteSigned -scope CurrentUser
irm https://shorebird.dev/install.ps1 | iex

After installing, run `shorebird doctor` to verify and help me fix any issues.
```
Run the install script for your platform:
Mac/Linux
Windows
Mac/Linux
curl -fsSL https://shorebird.dev/install.sh | bash
This installs shorebird into ~/.shorebird/bin and adds it to your PATH. It also installs a bundled copy of Flutter at ~/.shorebird/bin/cache/flutter — modified to support code push and separate from your existing Flutter install.
Clone the repository into the directory where you want Shorebird installed:
```
git clone -b stable https://github.com/shorebirdtech/shorebird.git
```
Add the bin folder to your PATH, for example:
Bash/Zsh
Windows PowerShell
Bash/Zsh
# Add to shell profile (e.g., ~/.zshrc or ~/.bashrc) export PATH="$PATH:/path/to/cloned/shorebird/bin"
Run shorebird --help to see all available commands.

Verify your setup.

Restart your terminal to reload your PATH, then verify your setup by running the following command:

shorebird doctor

Example output:

$ shorebird doctor
Shorebird 1.6.136 • git@github.com:shorebirdtech/shorebird.git
Flutter 3.47.9 • revision 8352242a910a1f79747cb1c6d2aa02edc5f3fc12
Engine • revision eaeb4bdcae57b971d6dd7507a3b53e61676b8330

URL Reachability
✓ https://api.shorebird.dev OK (0.1s)
✓ https://auth.shorebird.dev OK (0.1s)
✓ https://console.shorebird.dev OK (0.1s)
✓ https://download.shorebird.dev OK (0.1s)
✓ https://storage.googleapis.com OK (0.2s)
✓ https://cdn.shorebird.cloud OK (0.1s)

✓ Shorebird is up-to-date (1.4s)
✓ Xcode project does not override FLUTTER_ build settings (1ms)

No issues detected!

Log in to your Shorebird account.

shorebird login opens a browser window for authentication. Return to your terminal after logging in.
```
shorebird login
```
Integrate Shorebird into your Flutter app.
- New app
- Existing app
Create a new Flutter app with Shorebird:
```
shorebird create my_shorebird_app
cd my_shorebird_app
```
In your Flutter app’s root directory, run:
```
shorebird init
```
This creates a shorebird.yaml file containing your app_id. Your app_id is not secret and can be committed to source control.

Ship your first patch

These steps take your app from a release to a patch running on your own device. The commands use Android; for iOS, replace android with ios. macOS, Linux and Windows releases work the same way on a computer running that OS.

Create a release

A release is the build you ship to your users. Shorebird keeps a copy of its compiled Dart code, and every patch is built against it.

Android
iOS

shorebird release android

shorebird release ios

The release version is your app’s version and build number, such as 1.0.0+1, which shorebird release reads from the build (by default, from the version in pubspec.yaml). When it finishes, it prints ✅ Published Release 1.0.0+1! and where to find what it built.

shorebird release builds with the newest Flutter your Shorebird version supports (3.47.9 today), not with the flutter on your PATH, and every patch to the release uses that same Flutter version. If your app uses a different version, see Choose the Flutter version.

A version can be released only once per platform. If you run shorebird release again without changing the version, it stops with:

It looks like you have an existing android release for version 1.0.0+1.
Please bump your version number and try again.

Increase the build number (for example, version: 1.0.0+2 in pubspec.yaml) and run it again.

You don’t need to upload this build to a store to try a patch. When you do ship it, upload the exact file shorebird release built, since patches only install on that build. On iOS, if you upload with Xcode, see Uploading from Xcode. Create a Release covers each platform, signing and store uploads.

Install the release on your device

Connect a device (or start an Android emulator) and run:

shorebird preview

shorebird preview downloads the release from Shorebird, installs it on the device you pick and starts it. This is a release build of the same code your users get, not a debug build. On Android, it replaces the app on the device, which deletes the app’s data.

Change some Dart code

Make a change you’ll recognize on screen, such as the text of a Text widget in lib/main.dart. Keep it to Dart: changes to native code, such as Kotlin, Swift or the files under android/ and ios/, need a new release instead.

Publish a patch to the staging track

shorebird patch android --track=staging

shorebird patch builds your app with the release’s Flutter version, compares it with the release, and uploads the patch. If your app has more than one release, it asks which one to patch. The staging track keeps the patch away from your users: only devices that ask for staging get it. See Tracks.

Test the patch on your device

shorebird preview --track=staging

This installs the release again, set to get patches from the staging track, and starts it.

On this first launch, the app checks for a patch and downloads it in the background. You still see the old code.
Close the app completely (swipe it away in the app switcher) and open it again. This launch runs the patch, and you see your change.

If you don’t see the change, close and open the app once more, since the first launch may have closed before the download finished. If it still doesn’t show, see Patch not showing up.

Promote the patch to stable

Once you’re happy with the patch, move it to the stable track, which devices get by default. In the Shorebird console, open your app and the release, open the patch’s menu, choose Change track and pick stable. Or from the CLI:

shorebird patches promote --release-version 1.0.0+1 --patch-number 1

Devices on that release get the patch the same way you just saw: they download it on one launch and run it on the next. A patch only reaches devices running the release it was made for, so your users get it once they have that release from the store.

Keeping Shorebird up to date

To update your local Shorebird CLI to the latest version, run:

shorebird upgrade

This checks for new commits on the stable branch of Shorebird and updates your local installation if a newer version is available. If you are already up to date, it will tell you so.

Sample apps

If you want to see Shorebird in action in a production-like application, check out the samples repository:

Shorebird SamplesA collection of Shorebird samples and demos.

Next steps

Create a ReleaseBuild and submit your app to Shorebird.

Create a PatchPush over-the-air updates to your users.

Preview LocallyTest your release on a local device before publishing.