--- title: "Initialize Shorebird" description: "Add Code Push to an existing Flutter project: what Shorebird init creates and changes in your app." --- Note If you are starting a new project, you can use [`shorebird create`](/code-push/create) to generate a new Flutter app with Shorebird. [Watch the video: Initialize Shorebird in an existing Flutter project](/videos/initialize-shorebird.mp4) To configure an existing Flutter project to use Shorebird, use `shorebird init` at the root of a Flutter project: ``` shorebird init ``` This does three things: 1. Tells Shorebird to create a unique `app_id` for your app. This `app_id` is how Shorebird identifies your app and knows which updates to send to it. It does not need to be kept secret. 2. Creates a `shorebird.yaml` file in your project’s root directory. `shorebird.yaml` contains the `app_id` mentioned above. 3. Adds the `shorebird.yaml` to the assets section of your `pubspec.yaml` file, ensuring `shorebird.yaml` is bundled with your app’s assets and is available to the Shorebird updater at runtime. You can safely commit these changes; they will have no effect on your app when not using Shorebird. Example output for an app named `shorebird_test`: ``` $ shorebird init ✓ Initializing gradlew (1.2s) ✓ No product flavors detected. (0.6s) ? How should we refer to this app? (shorebird_test) shorebird_test 🐦 Shorebird initialized successfully! ✅ A shorebird app has been created. ✅ A "shorebird.yaml" has been created. ✅ The "pubspec.yaml" has been updated to include "shorebird.yaml" as an asset. Reference the following commands to get started: 📦 To create a new release use: "shorebird release". 🚀 To push an update use: "shorebird patch". 👀 To preview a release use: "shorebird preview". For more information about Shorebird, visit https://shorebird.dev ✓ Shorebird is up-to-date (0.6s) ✓ AndroidManifest.xml files contain INTERNET permission (23ms) ✓ android/app/build.gradle(.kts) does not contain a legacy keepDebugSymbols line for libapp.so (2ms) ✓ Xcode project does not override FLUTTER_ build settings (3ms) ✓ shorebird.yaml found in pubspec.yaml assets (1ms) ✓ Lock files are tracked in source control (41ms) No issues detected! ``` Note You can supply a display name directly via the command line by passing the `--display-name` flag: ``` shorebird init --display-name "My App" ``` Note If your account belongs to multiple organizations, `shorebird init` will prompt you to choose one interactively. In non-interactive environments (e.g., CI), you can skip the prompt by passing `--org-id`: ``` shorebird init --org-id 42 ``` `--org-id` needs Shorebird 1.6.128 or newer. On an older CLI, use `--organization-id` instead, or run `shorebird upgrade` first. Run `shorebird orgs list` to list your organization IDs (`shorebird account orgs` before 1.6.135). The generated `shorebird.yaml` should look similar to: ``` # This file is used to configure the Shorebird updater used by your application. # Learn more at https://shorebird.dev # This file should be checked into version control. # This is the unique identifier assigned to your app. # It is used by your app to request the correct patches from Shorebird servers. app_id: 8c846e87-1461-4b09-8708-170d78331aca ``` If your application contains flavors, `shorebird init` will create an app per flavor and `shorebird.yaml` will include all flavors and their corresponding `app_ids`: ``` # This file is used to configure the Shorebird updater used by your application. # Learn more at https://shorebird.dev # This file should be checked into version control. # This is the unique identifier assigned to your app. # It is used by your app to request the correct patches from Shorebird servers. app_id: 864ab1b0-ba78-4b15-990a-a63cec35a41b flavors: development: 864ab1b0-ba78-4b15-990a-a63cec35a41b production: 6b6e6631-4fbe-4645-8d9d-d5247656d975 ``` Note The `app_id` is a required field in every `shorebird.yaml`. In the case of flavors, `app_id` will default to the first flavor and will be overwritten at build time to the corresponding flavor’s `app_id`. Disabling automatic updates By default, Shorebird checks for and downloads patches automatically in the background at app launch. To disable this and control updates programmatically (e.g., show a prompt before updating), add [`auto_update: false`](/code-push/shorebird-yaml/#auto_update) to `shorebird.yaml`: ``` app_id: 8c846e87-1461-4b09-8708-170d78331aca auto_update: false ``` You can then use [package:shorebird\_code\_push](https://pub.dev/packages/shorebird_code_push) to check for updates and trigger them at a time of your choosing. See [Update Strategies](/code-push/update-strategies) for examples. Note Shorebird Code Push requires the internet permission to be added to your `AndroidManifest.xml` file (located in `android/app/src/main/AndroidManifest.xml`). This is required for the app to be able to communicate with the Shorebird servers to download patches. `shorebird init` will add this permission if it is not already present. ``` ... ``` Caution If your project already has a `shorebird.yaml` and no new flavors to add, `shorebird init` stops with: ``` A "shorebird.yaml" file already exists and seems up-to-date. ``` Running `shorebird init --force` instead creates new apps and writes their IDs to `app_id` (and `flavors`), even when the old apps already have releases. The old apps stay in the console, but builds already installed on devices keep checking the old app IDs, so patches you make for the new apps never reach them. If you ran it by mistake and haven’t released since, restore the old `shorebird.yaml` from version control to keep patching those builds. Otherwise, those users get patches again only after they update from the store to a build you released after re-initializing. Use `--force` only on a project that has no releases yet. To add flavors to a project you’ve already released, run `shorebird init` without `--force`; see [Add Shorebird to the flavors](/code-push/guides/flavors/#add-shorebird-to-the-flavors). Whenever `shorebird init` writes `shorebird.yaml`, both with `--force` and when it adds new flavors, it rewrites the file from its template with only `app_id` and `flavors`. Your other [settings](/code-push/shorebird-yaml/), such as `auto_update`, `base_url` or `patch_verification`, and your comments are dropped, so check the diff and put them back before you commit. ## What’s next [Create a Release](/code-push/release)Build and submit your app to Shorebird. [Preview Locally](/code-push/preview)Test your release on a local device before publishing.