diff --git a/README.md b/README.md
index 55f36fb2..56852f24 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ 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
 
-## Overview
+## Packages
 
 This repository is a monorepo containing the following packages:
 
@@ -23,7 +23,7 @@ This repository is a monorepo containing the following packages:
 | [shorebird_cli](packages/shorebird_cli/README.md)                                   | Command-line which allows developers to interact with various Shorebird services        |
 | [shorebird_code_push_api](packages/shorebird_code_push_api/README.md)               | Server which exposes endpoints to support CodePush for Flutter applications             |
 | [shorebird_code_push_api_client](packages/shorebird_code_push_api_client/README.md) | Dart library which allows Dart applications to interact with the ShoreBird CodePush API |
-| [shorebird_code_push_updater](packages/shorebird_code_push_updater/README.md)       | Rust library which handles the CodePush logic and does the real update work         |
+| [shorebird_code_push_updater](updater/README.md)                                    | Rust library which handles the CodePush logic and does the real update work             |
 
 For more information, please refer to the documentation for each package.
 
diff --git a/packages/shorebird_cli/README.md b/packages/shorebird_cli/README.md
index 60a0b5ce..16b65411 100644
--- a/packages/shorebird_cli/README.md
+++ b/packages/shorebird_cli/README.md
@@ -1,20 +1,78 @@
-## Shorebird CLI
+# Shorebird CLI
 
 **🚧 This project is under heavy development 🚧**
 
+**❗️ Currently, only Android arm64 release builds are supported but we are working on expanding to other platforms/architectures.**
+
 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 🧑‍💻
+## Installing
 
 ```sh
 dart pub global activate --source git https://github.com/shorebirdtech/shorebird --git-path packages/shorebird_cli
 ```
 
-## Publish
+## Commands
+
+### Login
+
+Get started by requesting an API key and using `shorebird login` to authenticate:
+
+```bash
+shorebird login
+```
+
+**Sample**
+
+```bash
+shorebird login
+? Please enter your API Key: <API-KEY>
+✓ Logging into shorebird.dev (7ms)
+You are now logged in.
+```
+
+### Logout
+
+To sign out and remove an existing session, use the `shorebird logout` command:
+
+```bash
+shorebird logout
+```
+
+**Sample**
+
+```bash
+shorebird logout
+✓ Logging out of shorebird.dev (1ms)
+```
+
+### Run
+
+Run an existing application using the Shorebird Engine via the `shorebird run` command:
+
+```bash
+shorebird run
+```
+
+**❗️Note**: If it's the first time, `shorebird run` will download and build the shorebird engine which may take some time. The shorebird engine will be cached for subsequent runs.
+
+### Build
+
+Build a new release of your application using the `shorebird build` command:
+
+```bash
+shorebird build
+```
+
+### 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.
 
-```
+```bash
+# Publish the default release
+shorebird publish
+
+# Publish a specific release
 shorebird publish <path/to/libapp.so>
 ```
 
@@ -31,7 +89,11 @@ Global options:
     --[no-]verbose    Noisy logging, including all shell commands executed.
 
 Available commands:
+  build     Build a new release of your application.
+  login     Login as a new Shorebird user.
+  logout    Logout of the current Shorebird user
   publish   Publish an update.
+  run       Run the Flutter application.
   update    Update the CLI.
 
 Run "shorebird help <command>" for more information about a command.