From f0c3af8b967bc39825ebd79dc19336ab3a935125 Mon Sep 17 00:00:00 2001
From: Felix Angelov <felix@shorebird.dev>
Date: Thu, 2 Mar 2023 21:21:41 -0600
Subject: [PATCH] docs: various README updates

---
 README.md                                  | 18 ++++++--
 packages/shorebird_cli/README.md           | 39 ++++++++++++++++--
 packages/shorebird_code_push_api/README.md | 48 ++++++++++++++++++++--
 3 files changed, 95 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 46ca1734..7fbeb5bf 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-## shorebird
+## Shorebird 🐦
 
-Home of the Shorebird Tools 🐦
+Home of the Shorebird Tools
 
 ## Status
 
@@ -8,9 +8,19 @@ We're in the process of converting the quick demos written by one person, into a
 multi-contributor project usable by others. Previous demo code can be found at:
 https://github.com/shorebirdtech/old_repo
 
-## Usage
+## Overview
 
-Instructions coming soon.
+This repository is a monorepo containing the following packages:
+
+| Package                                                                             |
+| ----------------------------------------------------------------------------------- |
+| [shorebird_cli](packages/shorebird_cli/README.md)                                   |
+| [shorebird_code_push_api](packages/shorebird_code_push_api/README.md)               |
+| [shorebird_code_push_api_client](packages/shorebird_code_push_api_client/README.md) |
+
+For more information, please refer to the documentation for each package.
+
+**❗️ Note: This project is under heavy development and things will change frequently. We will do our best to keep the documentation up-to-date.**
 
 ## Contributing
 
diff --git a/packages/shorebird_cli/README.md b/packages/shorebird_cli/README.md
index ba16cd79..60a0b5ce 100644
--- a/packages/shorebird_cli/README.md
+++ b/packages/shorebird_cli/README.md
@@ -1,5 +1,38 @@
-## shorebird_cli
+## Shorebird CLI
 
-The Shorebird command-line tool.
+**🚧 This project is under heavy development 🚧**
 
-🚧 Under construction... 🚧
+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.
+
+### Installing 🧑‍💻
+
+```sh
+dart pub global activate --source git https://github.com/shorebirdtech/shorebird --git-path packages/shorebird_cli
+```
+
+## Publish
+
+The publish command allows developers to publish new releases of their Flutter application to the Shorebird CodePush API. These updates are then pushed directly to users' devices.
+
+```
+shorebird publish <path/to/libapp.so>
+```
+
+### Usage
+
+```
+The shorebird command-line tool
+
+Usage: shorebird <command> [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:
+  publish   Publish an update.
+  update    Update the CLI.
+
+Run "shorebird help <command>" for more information about a command.
+```
diff --git a/packages/shorebird_code_push_api/README.md b/packages/shorebird_code_push_api/README.md
index 895da96e..3bd67725 100644
--- a/packages/shorebird_code_push_api/README.md
+++ b/packages/shorebird_code_push_api/README.md
@@ -1,5 +1,47 @@
-## shorebird_code_push_api
+## Shorebird CodePush API
 
-The Shorebird CodePush API
+**🚧 This project is under heavy development 🚧**
 
-🚧 Under construction... 🚧
+The Shorebird CodePush API is a server which exposes endpoints to support CodePush for Flutter applications.
+
+## Getting Started 🚀
+
+The Shorebird CodePush API is written in [Dart](https://dart.dev) and uses [Shelf](https://pub.dev/packages/shelf).
+
+### Running Locally ☁️💻
+
+To run the server locally, run the following command from the current directory:
+
+```sh
+dart bin/server.dart
+```
+
+This will start the server on [localhost:8080](http://localhost:8080).
+
+### Running in Docker 🐳
+
+To run the server in Docker, make sure you have [Docker installed](https://docs.docker.com/get-docker/).
+
+You can create an image:
+
+```sh
+docker build -q .
+```
+
+Once you have created an image, you can run the image via:
+
+```sh
+docker run -d -p 8080:8080 --rm <IMAGE>
+```
+
+To kill the container:
+
+```sh
+docker kill <CONTAINER>
+```
+
+If you wish to delete an image you can run:
+
+```sh
+docker rmi <IMAGE>
+```