diff --git a/packages/upgrade/README.md b/packages/upgrade/README.md
index a34a777b703f..499479ccbcc3 100644
--- a/packages/upgrade/README.md
+++ b/packages/upgrade/README.md
@@ -25,7 +25,7 @@ You can install `@carbon/upgrade` in your project, or use a tool like
 by running the following command in your project:
 
 ```bash
-npx @carbon/upgrade -d
+npx @carbon/upgrade
 ```
 
 Below is a full output of the options and commands available:
@@ -33,19 +33,35 @@ Below is a full output of the options and commands available:
 ```bash
 Usage: @carbon/upgrade [options]
 
+Commands:
+  @carbon/upgrade upgrade                   upgrade your project       [default]
+  @carbon/upgrade migrate <migration>       run a Carbon migration on your
+  [paths...]                                source files
+  @carbon/upgrade migrate list              list all available migrations
+
 Options:
       --help     Show help                                             [boolean]
       --version  Show version number                                   [boolean]
       --force    force execution if the cli encounters an error while doing
                  safety checks                        [boolean] [default: false]
   -w, --write    update the files with changes found by running the migration
-                                                                [default: false]
+                                                      [boolean] [default: false]
   -v, --verbose  optionally include additional logs, useful for debugging
                                                       [boolean] [default: false]
 ```
 
+### Migrations
+
+Included within the CLI are a number of migrations available to you to be ran on your project's source files.
+
+Migrations are automated scripts (codemods) ran using the [jscodeshift](https://github.com/facebook/jscodeshift) runner, that will apply intelligent transformations to your code.
+
+These migrations range from simple automations like a find and replace of import statements, to more sophisticated migrations that rewrite component prop usage, configuration, and set up. The source of these migrations can be viewed within the [transforms folder](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade/transforms). Each is tested against a series of test fixtures to ensure transforms are predictable and consistently provide the intended output.
+
 ## 🙌 Contributing
 
+If you have ideas on how we could make your migration experience easier, please reach out by [opening a new discussion](https://github.com/carbon-design-system/carbon/discussions/new).
+
 We're always looking for contributors to help us fix bugs, build new features,
 or help us improve the project documentation. If you're interested, definitely
 check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀