diff --git a/tools/assets/mermaid-preview.png b/tools/assets/mermaid-preview.png
new file mode 100644
index 000000000..cbfc5bcf6
Binary files /dev/null and b/tools/assets/mermaid-preview.png differ
diff --git a/tools/assets/mermaid-settings.png b/tools/assets/mermaid-settings.png
new file mode 100644
index 000000000..e36dad93c
Binary files /dev/null and b/tools/assets/mermaid-settings.png differ
diff --git a/tools/cds-cli.md b/tools/cds-cli.md
index c7bd739f0..8344de11f 100644
--- a/tools/cds-cli.md
+++ b/tools/cds-cli.md
@@ -20,7 +20,8 @@ synopsis: >
   .plan { color: gray; font-size:90% }
   .contrib { color: gray; font-size:90% }
 
-  .add::before { content: 'cds add '; color: #999 }
+  .add::before     { content: 'cds add '; color: #999 }
+  .compile::before { content: 'cds compile --to '; color: #999 }
 </style>
 
 # CDS Command Line Interface (CLI) {#cli}
@@ -420,6 +421,64 @@ Use `cds env` to inspect currently effective config settings:
 </pre>
 
 
+## cds compile
+
+### mermaid <Since version="8.0.0" of="@sap/cds-dk" /> {.compile}
+
+This produces text for a [Mermaid class diagram](https://mermaid.js.org/syntax/classDiagram.html):
+
+```sh
+cds compile db/schema.cds --to mermaid
+```
+
+Output:
+
+```log
+classDiagram
+  namespace sap_fe_cap_travel {
+    class `sap.fe.cap.travel.Travel`["Travel"]
+    class `sap.fe.cap.travel.Booking`["Booking"]
+    class `sap.fe.cap.travel.Airline`["Airline"]
+    class `sap.fe.cap.travel.Airport`["Airport"]
+    class `sap.fe.cap.travel.Flight`["Flight"]
+  }
+```
+
+If wrapped in a markdown code fence of type `mermaid`, such diagram text is supported by many markdown renderers, for example, on [GitHub](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams).
+
+````md
+```mermaid
+classDiagram
+  namespace sap_fe_cap_travel {
+    class `sap.fe.cap.travel.Travel`["Travel"]
+    ...
+  }
+```
+````
+
+To customize the diagram layout, use these environment variables when calling `cds compile`:
+
+```sh
+CDS_MERMAID_ASSOCNAMES=false|true    # show association/composition names
+CDS_MERMAID_ELEMENTS=false|all|keys  # no, all, or only key elements
+CDS_MERMAID_MIN=false|true           # remove unused entities
+CDS_MERMAID_NAMESPACES=false|true    # group entities by namespace
+CDS_MERMAID_QUERIES=false|true       # show queries/projections
+```
+
+<div id="mermaid-cli-more" />
+
+#### Interactively in VS Code
+
+To visualize your CDS model as a diagram in VS Code, open a `.cds` file and use the dropdown in the editor toolbar or the command _CDS: Preview as diagram_:
+
+![The screenshot is described in the accompanying text.](assets/mermaid-preview.png) {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"}
+
+To customize the diagram layout, use these settings:
+
+![The screenshot shows the following setting for the CDS Code Editor: Cds>Preview>Diagram: Associations, Cds>Preview>Diagram: Elements, Cds>Preview>Diagram: Minify, Cds>Preview>Diagram: Namespaces, and Cds>Preview>Diagram: Queries](assets/mermaid-settings.png){style="height:400px;"} {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"}
+
+
 ## cds repl
 
 Use `cds repl` to live-interact with Node.js APIs: