--- title: "Quick Start" description: "Install Shorebird, create a release and see your first patch run on your own device." --- [Watch the video: Get started with Shorebird](/videos/getting-started.mp4) 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](https://docs.flutter.dev/get-started/install) 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?](/flutter-concepts/complete-introduction-flutter/) explains how it works, and [Flutter for Beginners](/flutter-concepts/flutter-for-beginners/) builds a first app with Shorebird step by step. ## Installation 1. **Sign up** for a free Shorebird account. [CREATE AN ACCOUNT](https://console.shorebird.dev) 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](/enterprise/saml/) instead. Use the same method every time: your account [signs in with the method you first used](/account/access-and-ownership/#change-how-you-sign-in). Your apps live in an [organization](/account/orgs/). 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](/account/orgs/#creating-an-organization) needs a paid plan. If your team already uses Shorebird, [accept their invitation](/account/orgs/#accept-an-invitation) before running `shorebird init`, so your app goes into their organization. Creating an app there needs the [Owner, Admin, or App Manager role](/account/orgs/#member-roles). 2. **Install Shorebird.** * Install with AI 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. ``` * Install script Run the install script for your platform: * Mac/Linux Mac/Linux ``` curl -fsSL https://shorebird.dev/install.sh | bash ``` * Windows Windows ``` Set-ExecutionPolicy RemoteSigned -scope CurrentUser irm https://shorebird.dev/install.ps1 | iex ``` 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. * Manual install Mac/Linux ``` curl -fsSL https://shorebird.dev/install.sh | bash ``` * Mac/Linux Windows ``` Set-ExecutionPolicy RemoteSigned -scope CurrentUser irm https://shorebird.dev/install.ps1 | iex ``` * Windows 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 Bash/Zsh ``` # Add to shell profile (e.g., ~/.zshrc or ~/.bashrc) export PATH="$PATH:/path/to/cloned/shorebird/bin" ``` * Windows PowerShell Windows PowerShell ``` # Add to User PATH variable [Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\path\to\cloned\shorebird\bin", "User") ``` * Bash/Zsh Bash/Zsh ``` # Add to shell profile (e.g., ~/.zshrc or ~/.bashrc) export PATH="$PATH:/path/to/cloned/shorebird/bin" ``` * Windows PowerShell Windows PowerShell ``` # Add to User PATH variable [Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\path\to\cloned\shorebird\bin", "User") ``` Run `shorebird --help` to see all available commands. 3. **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! ``` 4. **Log in** to your Shorebird account. `shorebird login` opens a browser window for authentication. Return to your terminal after logging in. ``` shorebird login ``` 5. **Integrate Shorebird** into your Flutter app. * New app Create a new Flutter app with Shorebird: ``` shorebird create my_shorebird_app cd my_shorebird_app ``` * Existing 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 Android ``` shorebird release android ``` * iOS iOS ``` 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](/code-push/release#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](/code-push/release#uploading-from-xcode). [Create a Release](/code-push/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](/code-push/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. 1. On this first launch, the app checks for a patch and downloads it in the background. You still see the old code. 2. 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](/code-push/troubleshooting#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](https://console.shorebird.dev), 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. Tip You can also see your current version at any time by running `shorebird --version`. ## Sample apps If you want to see Shorebird in action in a production-like application, check out the samples repository: [Shorebird Samples](https://github.com/shorebirdtech/samples)A collection of Shorebird samples and demos. ## Next steps [Create a Release](/code-push/release)Build and submit your app to Shorebird. [Create a Patch](/code-push/patch)Push over-the-air updates to your users. [Preview Locally](/code-push/preview)Test your release on a local device before publishing.