diff --git a/packages/shorebird_cli/README.md b/packages/shorebird_cli/README.md index f2d821cf..27c1b8cf 100644 --- a/packages/shorebird_cli/README.md +++ b/packages/shorebird_cli/README.md @@ -1,418 +1,9 @@ # Shorebird CLI -**🚧 This project is under heavy development 🚧** +The Shorebird command-line allows developers to interact with various Shorebird services. -**❗️ Currently, only Android release builds are supported but we are working on expanding to other platforms/architectures.** +See https://docs.shorebird.dev for more information. -The Shorebird command-line allows developers to interact with various Shorebird services. We're currently focusing on CodePush but the Shorebird CLI will continue to expand as we add more capabilities. +`shorebird help` shows high-level help on available commands. -## Installing - -``` -curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | sh -``` - -## Commands - -### Init - -Get started by initializing shorebird in your current project. - -```bash -# 1. Creates a new app (if one doesn't exist) with a stable channel. -# 2. Generates a shorebird.yaml (if one doesn't exist). -# 3. Adds the shorebird.yaml to the pubspec.yaml flutter assets. -shorebird init -``` - -**Sample** - -``` -shorebird init -βœ“ Initialized Shorebird (27ms) - -🐦 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 run your project use: "shorebird run". -πŸ“¦ To create a new release use: "shorebird release". -πŸš€ To push a new update use: "shorebird patch". - -For more information, visit https://shorebird.dev -``` - -### Login - -Request an API key and use `shorebird login` to authenticate: - -```bash -shorebird login -``` - -**Sample** - -``` -shorebird login -The Shorebird CLI needs your authorization to manage apps, releases, and patches on your behalf. - -In a browser, visit this URL to log in: - -https://accounts.google.com/o/oauth2/v2/auth... - -Waiting for your authorization... - -πŸŽ‰ Welcome to Shorebird! You are now logged in as . - -πŸ”‘ Credentials are stored in ./path/to/credentials.json. -πŸšͺ To logout use: "shorebird logout". -``` - -### Logout - -To sign out and remove an existing session, use the `shorebird logout` command: - -```bash -shorebird logout -``` - -**Sample** - -``` -shorebird logout -βœ“ Logging out of shorebird.dev (1ms) -``` - -### Create Account - -To create a new Shorebird account use the `shorebird account create` command: - -```bash -shorebird account create -``` - -**Sample** - -``` -$ shorebird account create -Shorebird currently requires a Google account for authentication. If you'd like to use a different kind of auth, please let us know: https://github.com/shorebirdtech/shorebird/issues/335. - -Follow the link below to authenticate: - -https://accounts.google.com/o/oauth2/v2/auth... - -Waiting for your authorization... -Tell us your name to finish creating your account: Jane Doe - -πŸŽ‰ Welcome to Shorebird, Jane Doe! -πŸ”‘ Credentials are stored in ./path/to/credentials.json. -πŸšͺ To logout, use: "shorebird logout". -⬆️ To upgrade your account, use: "shorebird account subscribe". - -Enjoy! Please let us know via Discord if we can help. -``` - -### Upgrade to Paid Account - -To use Shorebird, you must upgrade to a paid account using the `shorebird account subscribe` command. Once you have paid, your account will be automatically upgraded and you will be able to use Shorebird to build and deploy apps. - -**Sample** - -``` -$ shorebird account subscribe -βœ“ Link generated! (0.8s) - -To purchase a Shorebird subscription, please visit the following link: -https://buy.stripe.com/... - -Once Stripe has processed your payment, you will be able to use Shorebird to create and publish apps. - -Note: This payment link is specifically for your account. Do not share it with others. -``` - -### Doctor - -To check your environment for common issues, use the `shorebird doctor` command. - -```bash -shorebird doctor -``` - -**Sample** - -``` -$ shorebird doctor - -Shorebird v0.0.8 -Shorebird Engine β€’ revision d470ae25d21f583abe128f7b838476afd5e45bde - -βœ“ Shorebird is up-to-date (0.7s) -βœ“ Flutter install is correct (0.1s) -βœ“ AndroidManifest.xml files contain INTERNET permission (26ms) - -No issues detected! -``` - -### Create App - -To create an app use the `shorebird apps create` command. An app id can be specified as a CLI option but shorebird will default to the `app_id` defined in the `shorebird.yaml` - -```bash -# Create an app using default app id -shorebird apps create - -# Create an app using an explicit app id -shorebird apps create --app-id "my-app-id" -``` - -**Sample** - -``` -shorebird apps create -? Enter the App ID (default_id) my_app_id -Created new app: my_app_id -``` - -### Delete App - -To delete an existing app on Shorebird, use the `shorebird apps delete` command. An app-id can be specified as a CLI option but shorebird will default to the app_id defined in the `shorebird.yaml` - -```bash -# Create an app using default app id -shorebird apps delete - -# Create an app using an explicit app id -shorebird apps delete --app-id "my-app-id" -``` - -**Sample** - -``` -shorebird apps delete -? Enter the App ID (default_id) my_app_id -Deleting an app is permanent. Continue? (y/N) Yes -Deleted app: my_app_id -``` - -### List Apps - -List all existing apps in Shorebird using the `shorebird apps list` command: - -```bash -shorebird apps list -``` - -**Sample** - -``` -shorebird apps list -πŸ“± Apps -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Name β”‚ ID β”‚ Release β”‚ Patch β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Shorebird Counter β”‚ 30370f27-dbf1-4673-8b20-fb096e38dffa β”‚ 1.0.0 β”‚ 1 β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Shorebird Clock β”‚ 05b45471-a5f3-48cd-b26a-da29d95914a7 β”‚ -- β”‚ -- β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -### Run - -Run an existing application using the Shorebird Engine via the `shorebird run` command: - -```bash -shorebird run -``` - -**❗️Note**: If it's the first time using shorebird, `shorebird run` will download and build the shorebird engine which may take some time. The shorebird engine will be cached for subsequent runs. - -### Release - -Builds and submits your app to Shorebird. Shorebird saves the compiled Dart code from your application in order to make smaller updates to your app. - -```bash -# 1. Generate a release build. -# 2. Create a release in Shorebird -# 3. Upload the release artifact to Shorebird. -shorebird release -``` - -**Sample** - -``` -$ shorebird release -βœ“ Building release (5.1s) -βœ“ Fetching apps (0.2s) - -What is the version of this release? (1.0.0) 1.0.0 - -πŸš€ Ready to create a new release! - -πŸ“± App: My App (30370f27-dbf1-4673-8b20-fb096e38dffa) -πŸ“¦ Release Version: 1.0.0 -πŸ•ΉοΈ Platform: android (arm64, arm32, x86) - -Would you like to continue? (y/N) Yes -βœ“ Fetching releases (55ms) -βœ“ Creating release (45ms) -βœ“ Creating artifacts (4.6s) - -βœ… Published Release! - -Your next step is to upload the app bundle to the Play Store. -./build/app/outputs/bundle/release/app-release.aab - -See the following link for more information: -https://support.google.com/googleplay/android-developer/answer/9859152?hl=en -``` - -### Patch - -The patch command allows developers to upload new patches (updates) of their Flutter application to the Shorebird CodePush API. These updates are then pushed directly to users' devices. - -```bash -# Publish the artifacts -# 1. Builds the artifacts (equivalent to a shorebird build) -# 2. Creates a new patch if one does not exist -# 3. Uploads the artifacts as part of the patch -# 4. Promotes the patch to the "stable" channel -shorebird patch -``` - -**Sample** - -``` -shorebird patch -βœ“ Building patch (16.2s) -βœ“ Fetching apps (0.1s) - -Which release is this patch for? (0.1.0) 0.1.0 - -πŸš€ Ready to publish a new patch! - -πŸ“± App: My App (61fc9c16) -πŸ“¦ Release Version: 0.1.0 -πŸ“Ί Channel: stable -πŸ•ΉοΈ Platform: android (arm64, arm32, x86) - -Would you like to continue? (y/N) Yes -βœ“ Fetching release (41ms) -βœ“ Fetching release artifacts (43ms) -βœ“ Downloading release artifacts (0.2s) -βœ“ Creating artifacts (0.3s) -βœ“ Uploading artifacts (43ms) -βœ“ Fetching channels (40ms) -βœ“ Promoting patch to stable (43ms) - -βœ… Published Patch! -``` - -### Build - -Build a new release of your application using the `shorebird build` command: - -```bash -# Build an AppBundle -shorebird build appbundle - -# Build an APK -shorebird build apk -``` - -### List Channels - -See all available channels for your application using the `shorebird channels list` command: - -```bash -shorebird channels list -``` - -**Sample** - -``` -shorebird channels list -πŸ“± App ID: 61fc9c16-3c4a-4825-a155-9765993614aa -πŸ“Ί Channels -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Name β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ stable β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ development β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -### Create Channels - -Create a new channel for your application using the `shorebird channels create` command: - -```bash -shorebird channels create --name MyChannel -``` - -**Sample** - -``` -shorebird channels create --name MyChannel - -πŸš€ Ready to create a new channel! - -πŸ“± App ID: 485df03f-f522-4242-bf3d-31c0869bacac -πŸ“Ί Channel: MyChannel - -Would you like to continue? (y/N) Yes -βœ“ Creating channel (0.2s) - -βœ… New Channel Created! -``` - -### Cancel Subscription - -Cancel your Shorebird subscription using `shorebird subscription cancel` command: - -```bash -shoreburd subscription cancel -``` - -**Sample** - -```bash -$ shorebird subscription cancel -This will cancel your Shorebird subscription. Are you sure? (y/N) Yes -Your subscription has been canceled. -``` - -### Usage - -``` -The shorebird command-line tool - -Usage: shorebird [arguments] - -Global options: --h, --help Print this usage information. --v, --version Print the current version. - --[no-]verbose Noisy logging, including all shell commands executed. - -Available commands: - account Manage your Shorebird account. - apps Manage your Shorebird apps. - build Build a new release of your application. - cache Manage the Shorebird cache. - channels Manage the channels for your Shorebird app. - doctor Show information about the installed tooling. - init Initialize Shorebird. - login Login as a new Shorebird user. - logout Logout of the current Shorebird user - patch Publish new patches for a specific release to Shorebird. - release Builds and submits your app to Shorebird. - run Run the Flutter application. - subscription Manage your Shorebird subscription. - upgrade Upgrade your copy of Shorebird. - -Run "shorebird help " for more information about a command. -``` +`shorebird --help` can show information about a specific command.