From 00f787206b1ee13a2af16e0a3eb75cc0623d1a5e Mon Sep 17 00:00:00 2001
From: Bardh Lohaj <b.lohaj@celonis.com>
Date: Wed, 11 Mar 2026 18:10:35 +0100
Subject: [PATCH] Add chalk as explicit dependency and improve README

chalk is imported in module-handler.ts and CustomHelp.ts but was never
listed in package.json dependencies. It only worked locally because it
was hoisted as a transitive dependency. A clean install from the
registry (npm install -g) fails with "Cannot find module 'chalk'".

- Add chalk@4.1.2 to dependencies (last CJS-compatible version)
- Restructure the local build section with prerequisites and clear steps
- Add a Troubleshooting section for common installation issues

Includes-AI-Code: true
Made-with: Cursor
---
 README.md    | 78 ++++++++++++++++++++++++++++++++++++++++++----------
 package.json |  1 +
 yarn.lock    | 16 +++++------
 3 files changed, 73 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 09f42763..e224d878 100644
--- a/README.md
+++ b/README.md
@@ -9,10 +9,11 @@ teams and execute commands in a profile's context.
 
 1. [Getting Started](#getting-started)
 2. [About the Project](#about-the-project)
-3. [Building the Project](#building-the-project)
-4. [Release Process](#release-process)
-5. [Contributing](#contributing)
-6. [License](#license)
+3. [Building the Project](#building-and-using-the-project-locally)
+4. [Troubleshooting](#troubleshooting)
+5. [Release Process](#release-process)
+6. [Contributing](#contributing)
+7. [License](#license)
 
 ## Getting Started
 
@@ -85,16 +86,65 @@ content-cli pull package -h
 ## Building and Using the Project locally 
 
 This tool is tightly connected with the Celonis Platform and all capabilities require to have access to a Celonis Platform Team. 
-After cloning the project, the next step is to install the project dependencies. We use `yarn` as our package manager, 
-so running `yarn install` on the project root folder should install all the necessary dependencies. After installing 
-the project dependencies, you can run `yarn build` to build the project artifact. To use the built artifact, you can 
-run `node content-cli.js` in the generated `dist` folder.
-
-If we want to use a specific local build of the tool globally, we can do this by:
-- Move to the root directory of the project.
-- Execute `cd dist`, to move to the `dist` directory.
-- Execute the `npm link` command. 
-This will create a symbolic link in the global `node_modules` directory, allowing you to run the CLI from anywhere on your machine.
+
+### Prerequisites
+
+- **Node.js** `>=18.20.5` (LTS recommended). Check with `node -v`.
+- **yarn** package manager. Install with `npm install -g yarn` if not already available.
+
+### Build steps
+
+```bash
+git clone https://github.com/celonis/content-cli.git
+cd content-cli
+yarn install
+yarn build
+```
+
+The build compiles TypeScript into the `dist/` folder and copies `package.json` there.
+
+### Running the built CLI
+
+You can run the built artifact directly from the `dist` folder:
+
+```bash
+node dist/content-cli.js -h
+```
+
+### Installing the local build globally
+
+To use your local build as the global `content-cli` command:
+
+```bash
+cd dist
+npm link
+```
+
+This creates a symbolic link in the global `node_modules` directory, allowing you to run `content-cli` from anywhere on your machine. To unlink later, run `npm unlink -g @celonis/content-cli`.
+
+## Troubleshooting
+
+### `Error: Cannot find module '...'`
+
+If you see a `Cannot find module` error when running `content-cli`, dependencies may not be installed correctly:
+
+- **Global install:** Try updating to the latest version: `npm install -g @celonis/content-cli@latest`.
+- **Local development:** Run `yarn install` from the project root before building.
+
+### `content-cli: command not found`
+
+- Ensure Node.js is installed and on your `PATH` (`node -v`).
+- If installed via `npm install -g`, check that npm's global `bin` directory is in your `PATH`. You can find it with `npm bin -g`.
+- If using `npm link`, make sure you ran it from the `dist/` directory (not the project root).
+
+### Node.js version errors
+
+Content CLI requires Node.js `>=18.20.5`. If you see compatibility errors, upgrade your Node.js installation. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions:
+
+```bash
+nvm install --lts
+nvm use --lts
+```
 
 ## Release Process
 
diff --git a/package.json b/package.json
index 968084cc..9f66d2eb 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "adm-zip": "0.5.14",
+    "chalk": "4.1.2",
     "uuid": "9.0.1",
     "axios": "1.13.5",
     "commander": "13.1.0",
diff --git a/yarn.lock b/yarn.lock
index 774fb866..1c7b643b 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -971,6 +971,14 @@ caniuse-lite@^1.0.30001688:
   resolved "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001695.tgz"
   integrity sha512-vHyLade6wTgI2u1ec3WQBxv+2BrTERV28UXQu9LO6lZ9pYeMk34vjXFLOxo1A4UBA8XTL4njRQZdno/yYaSmWw==
 
+chalk@4.1.2, chalk@^4.0.0, chalk@^4.0.2:
+  version "4.1.2"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.2.tgz#aac4e2b7734a740867aeb16bf02aad556a1e7a01"
+  integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==
+  dependencies:
+    ansi-styles "^4.1.0"
+    supports-color "^7.1.0"
+
 chalk@^2.3.0:
   version "2.4.2"
   resolved "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz"
@@ -980,14 +988,6 @@ chalk@^2.3.0:
     escape-string-regexp "^1.0.5"
     supports-color "^5.3.0"
 
-chalk@^4.0.0, chalk@^4.0.2:
-  version "4.1.2"
-  resolved "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz"
-  integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==
-  dependencies:
-    ansi-styles "^4.1.0"
-    supports-color "^7.1.0"
-
 chalk@~5.4.1:
   version "5.4.1"
   resolved "https://registry.npmjs.org/chalk/-/chalk-5.4.1.tgz"