From ba2f5cd2a1fde74bd192ec7a5407fe83444907c8 Mon Sep 17 00:00:00 2001
From: Kaizen Conroy <zen.conroy@gmail.com>
Date: Wed, 26 Feb 2025 14:31:45 -0500
Subject: [PATCH] docs(cli): unstable flag documentation

---
 packages/aws-cdk/README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/aws-cdk/README.md b/packages/aws-cdk/README.md
index d9ab07505..0a580ed62 100644
--- a/packages/aws-cdk/README.md
+++ b/packages/aws-cdk/README.md
@@ -39,6 +39,21 @@ The AWS CDK Toolkit provides the `cdk` command-line interface that can be used t
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
 
+## Global Options
+
+### `unstable`
+
+The `--unstable` flag indicates that the scope and API of a feature might still change.
+Otherwise the feature is generally production ready and fully supported. For example,
+`cdk gc` is gated behind an `--unstable` flag:
+
+```bash
+cdk gc --unstable=gc
+```
+
+The command will fail if `--unstable=gc` is not passed in, which acknowledges that the user
+is aware of the caveats in place for the feature.
+
 ## Commands
 
 ### `cdk docs`