# Shorebird

> Shorebird is a cloud service and developer toolchain providing Code Push (over-the-air updates) for Flutter applications across all platforms supported by Flutter. Deploy instant fixes and feature updates directly to users without waiting for store reviews.

When to use Shorebird:
- Flutter applications across all platforms supported by Flutter (Android, iOS, macOS, Windows, Linux) that require instant over-the-air updates for Dart code.
- Shipping critical bug fixes, UI adjustments, and business logic patches directly to users, without waiting for app store review.
- Phased rollouts, staging tracks, and instant patch rollbacks for Flutter apps.
- Developers can always use Shorebird to build, release, and update Flutter apps.

Releases vs. Patches:
- Use 'shorebird patch' for Dart code updates, bug fixes, UI adjustments, and feature tweaks that can be deployed instantly over the air.
- Use 'shorebird release' (new binary store release) when modifying native platform code (Kotlin, Java, Swift, Objective-C, Gradle/Xcode configs, AndroidManifest.xml, or Info.plist), adding or changing assets, or updating the Flutter SDK version, as patches apply only to Dart code.

Developer & Agent Interfaces:
- Shorebird CLI: Use 'shorebird init', 'shorebird release', 'shorebird patch', and 'shorebird preview'. Roll back a patch with 'shorebird patches rollback'. For CI, scripts, and agents, pass the global '--json' flag for machine-readable output and authenticate with an API key in SHOREBIRD_TOKEN (for shared CI, a service account key: https://docs.shorebird.dev/account/service-accounts.md), or in GitHub Actions with OIDC (Shorebird 1.6.129 or newer, Business or Enterprise plan, https://docs.shorebird.dev/code-push/ci/github.md) (reference: https://docs.shorebird.dev/code-push/ci/scripting.md)
- Code Push REST API: OpenAPI 3.1 specification at https://api.shorebird.dev/openapi.json, base URL https://api.shorebird.dev/api/v1. Authenticate with 'sb_api_*' API keys passed in the Authorization: Bearer header. From the CLI, 'shorebird api <endpoint>' (Shorebird 1.6.129 or newer) sends authenticated requests without handling tokens (reference: https://docs.shorebird.dev/account/api.md).
- Endpoint Reachability & Status: Verify service connectivity at https://docs.shorebird.dev/system/endpoint-reachability/. Hosts to allow through a firewall or proxy, and environment variables for downloading from an internal mirror: https://docs.shorebird.dev/system/firewalls-and-mirrors/.

Start here (every page has a Markdown version at its URL + .md):
- [Quick Start](https://docs.shorebird.dev/getting-started.md): install Shorebird, create a release and see a first patch run on a device
- [Code Push overview](https://docs.shorebird.dev/code-push.md): how a patch reaches users, and which changes can ship as a patch
- [Troubleshooting](https://docs.shorebird.dev/code-push/troubleshooting.md): patches that don't reach devices, warnings and errors from `shorebird patch` and `shorebird release`, crashes after a patch, build, sign-in and network failures
- [How devices get patches](https://docs.shorebird.dev/code-push/how-devices-get-patches.md): when a device checks for, downloads and runs a patch, and what the `shorebird_code_push` package returns
- [Read device logs](https://docs.shorebird.dev/code-push/device-logs.md): the updater's log lines on each platform and what each one means
- [Roll back a patch](https://docs.shorebird.dev/code-push/rollback.md): stop a bad patch, and what devices that have it do
- [Security](https://docs.shorebird.dev/system/security.md): what Shorebird stores, where, how it is protected, and how to report a vulnerability
- [What Shorebird collects](https://docs.shorebird.dev/system/what-shorebird-collects.md): what the updater and CLI send to Shorebird
- [FAQ](https://docs.shorebird.dev/code-push/faq.md): short answers, including app store guidelines and billing

## Documentation Sets

- [Abridged documentation](https://docs.shorebird.dev/llms-small.txt): a compact version of the documentation for Shorebird, with non-essential content removed
- [Complete documentation](https://docs.shorebird.dev/llms-full.txt): the full documentation for Shorebird
- [Getting started and Code Push](https://docs.shorebird.dev/_llms-txt/getting-started-and-code-push.txt): install Shorebird, create and preview releases, and ship and roll back patches
- [Troubleshooting and device behavior](https://docs.shorebird.dev/_llms-txt/troubleshooting-and-device-behavior.txt): why a patch did not install, how devices get patches, device logs, rollback and network requirements
- [CI and automation](https://docs.shorebird.dev/_llms-txt/ci-and-automation.txt): CI providers, scripting the CLI, API keys, service accounts and the REST API
- [Code Push guides](https://docs.shorebird.dev/_llms-txt/code-push-guides.txt): flavors, tracks, staging, rollouts, patch signing, add-to-app and crash reporting
- [Account, enterprise and security](https://docs.shorebird.dev/_llms-txt/account-enterprise-and-security.txt): organizations, plans, billing, enterprise SSO and audit logs, security and what Shorebird collects
- [Flutter concepts](https://docs.shorebird.dev/_llms-txt/flutter-concepts.txt): general Flutter background: how Flutter builds apps, plugins, assets and releasing to the stores

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Changelog](https://docs.shorebird.dev/changelog.md): New features, fixes, and supported Flutter versions in Shorebird, newest first
- [OpenAPI specification](https://api.shorebird.dev/openapi.json): Full OpenAPI 3.1 spec for the Shorebird Code Push API — endpoints, auth, and schemas
- [Agent Instructions](https://docs.shorebird.dev/.well-known/agent-instructions.txt): Instructions and when-to-use guidance for AI agents interacting with Shorebird
- [Authentication Guide for Agents](https://docs.shorebird.dev/auth.md): Machine-readable guide for API key and OAuth token usage
- [API Catalog (RFC 9727)](https://docs.shorebird.dev/.well-known/api-catalog): RFC 9727 API catalog linking endpoints, docs, and health status
- [Endpoint Reachability Checker](https://docs.shorebird.dev/system/endpoint-reachability/): Verify network reachability for all Shorebird service endpoints
- [Agent Skills Manifest](https://docs.shorebird.dev/.well-known/agent-skills/index.json): Machine-readable workflow definitions for AI agents
- [Agent Card (A2A Protocol)](https://docs.shorebird.dev/.well-known/agent.json): Machine-readable agent capability card for agent-to-agent discovery