diff --git a/.github/workflows/publish-cli-to-npm.yml b/.github/workflows/publish-cli-to-npm.yml
index 0b0f49fc..85ee7f80 100644
--- a/.github/workflows/publish-cli-to-npm.yml
+++ b/.github/workflows/publish-cli-to-npm.yml
@@ -1,36 +1,34 @@
-name: Publish to NPM
+name: Publish CLI to NPM
 
 on:
   release:
     types: [published]
-  workflow_dispatch:
 
 jobs:
-  build:
+  publish-cli:
     runs-on: ubuntu-latest
-    # use 'if' to prevent endless looping with npm package commit
-    if: "!startsWith(github.event.head_commit.message, '[RELEASE]')"
-    defaults:
-      run:
-        working-directory: ./cli
     steps:
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-      - run: git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
-      - run: git config user.name "$GITHUB_ACTOR"
-      # prepend '[RELEASE]' so that it can be detected above to prevent looping
-      #  this is a commit to main that can be ignored by this GitHub action
-      #  use 'patch' to update only the last digit in the version (e.g. 1.1.?)
-      # - run: npm version patch -m "[RELEASE] %s"
-      # - run: git push
-      # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@v4
+
+      # Checkout the code
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # Set up Node.js
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: "18.x"
-          registry-url: "https://registry.npmjs.org"
-      - run: npm ci
-      - run: npm run build
-      - run: npm publish --access=public
+          node-version: v20
+
+      # Install the workspace
+      - name: Install workspace
+        run: npm ci
+
+      # Build the entire workspace
+      - name: Build workspace
+        run: npm run build
+
+      # Publish the CLI module
+      - name: Publish CLI module
+        run: npm publish --workspace cli
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/cli/README.md b/cli/README.md
index 7982b5c5..92a54c97 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -209,10 +209,37 @@ npm run watch
 ```
 
 
-
 ### CLI Tests
 
 There are currently two types of tests;
 
 * `cli` tests - these are end-to-end and involve linking the package as part of the test so that we can assert on actual `calm X` invocations.
 * `shared` tests - these are where the core logic tests live, like how validation behaves etc.
+
+## Releasing the CLI
+
+Publishing of the CLI to NPM is controlled via [this action](https://github.com/finos/architecture-as-code/blob/main/.github/workflows/publish-cli-to-npm.yml) - this action is triggered whenever a GitHub release is created. To create a github release you can do one of the following;
+
+### Through the Github UI
+
+* Go to your repository on GitHub.
+* Click on the Releases tab (under "Code").
+* Click the Draft a new release button.
+* Fill in:
+  * Tag version: Enter the version number (e.g., v1.0.0).
+  * Release title: Name the release (e.g., "First Release").
+  * Description: Add details about what’s included in the release.
+  * Target: Leave as main (or your default branch).
+* Click Publish release to create the release and trigger the workflow.
+
+### Through the GitHub CLI (`gh`)
+
+```shell
+# Step 1: Authenticate with GitHub if you haven't already
+gh auth login
+
+# Step 2: Create the release.
+gh release create <version> --title "<release_title>" --notes "<release_description>"
+```
+
+