Quick Start

Welcome to Shorebird! 👋

In this guide, we’ll walk you through setting up Shorebird and integrating it into your app in just a few minutes.

The first thing you’ll need to do is sign up for a Shorebird account. It’s free to do and you can sign up in a matter of seconds.

Create an Account

Install

While a full install may not be required to access and use all of our product offerings, we recommend installing everything locally to make debugging easier as you continue using our services.

Using install script

To install the Shorebird command line interface (CLI):

Mac/Linux
Windows

curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

Set-ExecutionPolicy RemoteSigned -scope CurrentUser # Needed to execute remote scripts
iwr -UseBasicParsing 'https://raw.githubusercontent.com/shorebirdtech/install/main/install.ps1'|iex

This installs shorebird into ~/.shorebird/bin (or %USERPROFILE%\.shorebird\bin on Windows) and adds it to your PATH. It also installs a copy of Flutter and Dart inside ~/.shorebird/bin/cache/flutter (or %USERPROFILE%\.shorebird\bin\cache\flutter on Windows). The copy of Flutter is slightly modified to add Shorebird code push and is not intended to be added to your PATH. You can continue to use the versions of Flutter and Dart you already have installed.

Manually installing

Shorebird can also be manually installed, allowing users to choose where the installation will be placed.

In order to do so, in a terminal, inside the folder where Shorebird should be installed at, run:

git clone -b stable https://github.com/shorebirdtech/shorebird.git

Add the bin folder from the repository you just cloned into your PATH. For example:

Bash/Zsh
Windows PowerShell

# Add to shell profile (e.g., ~/.zshrc or ~/.bashrc)
export PATH="$PATH:/path/to/cloned/shorebird/bin"

# Add to User PATH variable
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\path\to\cloned\shorebird\bin", "User")

Once the installation has completed, shorebird should be available in your terminal:

$ shorebird
The shorebird command-line tool

Usage: shorebird <command> [arguments]

Global options:
-h, --help            Print this usage information.
    --version         Print the current version.
    --json            Output results in JSON format (implies non-interactive mode).
-v, --[no-]verbose    Noisy logging, including all shell commands executed.

Available commands:
  account    Manage your Shorebird account.
  cache      Manage the Shorebird cache.
  create     Create a new Flutter project with Shorebird.
  doctor     Show information about the installed tooling.
  flutter    Manage your Shorebird Flutter installation.
  init       Initialize Shorebird.
  login      Login as a new Shorebird user.
  logout     Logout of the current Shorebird user.
  patch      Creates a shorebird patch for the provided target platforms.
  patches    Manage Shorebird patches.
  preview    Preview a specific release on a device.
  release    Creates a shorebird release for the provided target platforms.
  releases   Manage Shorebird releases.
  upgrade    Upgrade your copy of Shorebird.

Run "shorebird help <command>" for more information about a command.

--json flag for CI scripting

All Shorebird commands accept a global --json flag that switches output to structured JSON instead of human-readable text. This is useful for parsing CLI results in shell scripts or CI pipelines:

shorebird account apps --json
shorebird releases list --json
shorebird patches list --json

You can use shorebird doctor to ensure things are set up correctly:

shorebird doctor

Example output:

$ shorebird doctor
Shorebird 1.5.1 • git@github.com:shorebirdtech/shorebird.git
Flutter 3.27.0 • revision 1e0e5760eeaf534c280cf59ee0504d0e2ba12a7b
Engine • revision 59571a1190752bc1740bff652ce5f0ba7c9413f8

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

✓ Shorebird is up-to-date (1.4s)
✓ Flutter install is correct (0.4s)

No issues detected!

Finally, you can log in to your Shorebird account on your machine:

shorebird login

Integrate Shorebird

You’re now ready to add Shorebird to your app.

You can start by creating a new Flutter app or navigating to the directory of your already created Flutter app.

To create a new Flutter app:

shorebird create my_shorebird_app
cd my_shorebird_app

Or, to enable Shorebird for an existing Flutter app, run:

shorebird init

This will create a shorebird.yaml file in the root of your project. This file contains your Shorebird app_id. Your app_id is not secret and can be checked into source control and freely shared.

This will also run shorebird doctor to ensure everything is set up correctly.

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 our samples:

Fintech Wallet Demo A professional, enterprise-grade Flutter architecture designed for Logic-Level Hotfixes.

Next Steps

Now that your account is set up and your app is initialized, you’re all set to begin.

Create a Release Build and submit your app to Shorebird.

Create a Patch Push over-the-air updates to your users.

Preview Locally Test your release on a local device before publishing.