Getting started

Install the CLI, connect a Flutter project, ship a release, then publish a patch. This takes about 15 minutes, plus however long your normal release build takes.

Before you start

  1. Install the CLI

    $ curl -fsSL https://overpush.in/install.sh | bash

    In PowerShell:

    > irm https://overpush.in/install.ps1 | iex

    iOS releases and patches need a Mac; use the macOS tab there.

    The installer picks the right build for your computer, checks it downloaded correctly, and puts overpush on your PATH. You don't need a Dart SDK to run it. Open a new terminal, then check it worked:

    $ overpush --version

  2. Log in

    $ overpush login

    This opens your browser so you can sign in. You only do this once per computer. Run overpush whoami to see which account you're using.

  3. Create the app in the dashboard

    In the dashboard, click New app and copy its app id. It looks like cp_7Kq9xZ2mWv4TnR8bL3sYd6HfJp1cXa5E.

    Working with others? Create a team organization first and add them under Members. See Console & team.

  4. Connect your project

    From the root of your Flutter project (the folder with pubspec.yaml):

    $ overpush init
$ flutter pub add overpush

    init asks for the app id and writes overpush.yaml. Commit both that file and the pubspec.yaml change.

    app_id: cp_7Kq9xZ2mWv4TnR8bL3sYd6HfJp1cXa5E

  5. Build a release

    $ overpush release android

    Builds an app bundle at build/app/outputs/bundle/release/app-release.aab, signed with your release key, and records it. Upload that file in Play Console: Test and release → pick a track → Create new release → upload → roll out.

    The full flow, including trying the release on your own phone first, is in Android.

    $ overpush release ios
$ overpush releases archive

    The first command builds the IPA and records it. The first run downloads build tools for your Flutter version, once; iOS currently needs Flutter 3.41.4, 3.47.5, 3.47.6, 3.47.7, 3.47.8 or 3.47.9. The second opens the build in Xcode's Organizer: click Distribute App, then App Store Connect and Upload.

    The full flow, including trying the release on your own iPhone first, is in iOS.

    Only OverPush release builds can be patched. A build made with plain flutter build doesn't include the release record that patches are checked against.

  6. Change some Dart and patch

    Edit any Dart code, for example some text on a screen, then run:

    $ overpush patch android --dry-run  # optional: build + check, don't publish
$ overpush patch android
    $ overpush patch ios --dry-run      # optional: build + check, don't publish
$ overpush patch ios

    The CLI builds the change against the release, checks that nothing outside Dart changed, and publishes it. OverPush signs it on publish.

  7. See it on a device

    Open the app on a device that has the release installed. It downloads the patch in the background. Close the app fully and open it again, and the patched code runs.

    Patches take effect on the next cold start. Sending the app to the background and back isn't enough. Swipe it away in the app switcher and reopen it.

Next steps

Roll out graduallySend the next patch to 10% of devices first. Automate itRun releases and patches from CI.