From 6e2df89cc7a73eaa08a7aa27fd7112ed7192d768 Mon Sep 17 00:00:00 2001
From: zgjimhaziri <z.haziri@celonis.com>
Date: Wed, 18 Jun 2025 14:59:07 +0200
Subject: [PATCH 1/2] TA-3753: Add guide on how to add new commands

---
 docs/how-to-add-command.md | 129 +++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 docs/how-to-add-command.md

diff --git a/docs/how-to-add-command.md b/docs/how-to-add-command.md
new file mode 100644
index 00000000..557a38dd
--- /dev/null
+++ b/docs/how-to-add-command.md
@@ -0,0 +1,129 @@
+# CLI – How to Add a New Command in Content CLI
+
+## Overview
+
+This guide explains how to add a new command in Content CLI. It covers both adding commands to existing groups and creating entirely new command groups. It also lays down expectations for documentation, folder structure, and ownership.
+
+---
+
+## Adding a New Command to an Existing Group
+
+### 1. Locate the Command Group
+
+Command groups are located under the `src/commands/` directory. Each group contains a `module.ts` file where its commands are registered.
+
+---
+
+### 2. Register the Command in `module.ts`
+
+Use the `Configurator` API to define your command. There are three common command types:
+
+#### **Command Type A: Top Command (Not callable on its own)**
+
+Use this type when a command is intended only as a top-level command for a group of subcommands. When called on its own, this will:
+
+- Not have any action taken.
+- Show a description. This description should be configured in the command.
+- Show a list of subcommands.
+
+```ts
+const listCommand = configurator.command("listCommand")
+  .description("Commands that do listing");
+```
+
+---
+
+#### **Command Type B: Top-Level Callable Command**
+
+Use this type when a command is intended as a top-level command that can be executed directly.
+
+```ts
+configurator.command("export")
+  .description("Export everything")
+  .option("--keys <realm>", "What to export")
+  .action(exportHandlerMethod);
+```
+
+---
+
+#### **Command Type C: Subcommand Definition**
+
+To define a subcommand on top of an existing command, use the existing top command (e.g. `listCommand`), and configure the subcommand similarly.
+
+```ts
+const listPackagesCommand = listCommand.command("packages")
+  .description("Lists packages")
+  .action(handlePackageListing);
+```
+
+---
+
+### 3. Document the Command
+
+Add documentation for the command in the `DOCUMENTATION.md` file in the repo.
+
+Each command must include:
+
+- A clear **description**
+- At least one **usage example**
+
+---
+
+## Adding a New Command Group
+
+### When Should You Create a New Group?
+
+Create a new command group if:
+
+- The commands don't logically belong in any existing group.
+- Another team will be the primary maintainer/owner.
+
+---
+
+### Steps to Create a New Group
+
+1. **Create a new directory** under `src/commands/`  
+   Example: `src/commands/example-area`
+
+2. **Add an entry to `CODEOWNERS`**  
+   Point the path to the owning team:
+   ```
+   src/commands/example-area/ @owning-team
+   ```
+
+3. **Create a `module.ts` file** in the new folder  
+   This file must implement the `IModule` interface and configure the new command inside the `register()` method.
+
+4. **Implement the command logic**  
+   Add the necessary services/APIs/interfaces in the newly created directory.
+
+---
+
+## Recommended Folder Structure
+
+To promote maintainability, follow this structure where appropriate:
+
+```
+src/commands/example/
+├── module.ts                   # Command configuration and entry point
+├── example.command.service     # Main command logic
+├── api/                        # API definitions
+├── interface/                  # Interfaces and transports
+├── service/                    # Supporting services
+```
+
+You are free to adapt the structure based on complexity.
+
+---
+
+## Ownership and Documentation
+
+- Command-level documentation (description, options, examples) is the responsibility of the **command-owning team**.
+- Framework documentation, utilities, and shared patterns are maintained by the **CLI foundation team**.
+
+---
+
+## Useful Examples
+
+Example group: `configuration-management`  
+(*Link to be added after merging changes into the main branch*)

From c3197991d69b3a632676092cc0ed3092aa4de982 Mon Sep 17 00:00:00 2001
From: Zgjim Haziri <37958277+ZgjimHaziri@users.noreply.github.com>
Date: Thu, 19 Jun 2025 15:15:12 +0200
Subject: [PATCH 2/2] Update docs/how-to-add-command.md

Co-authored-by: Kastriot Salihu <108934335+ksalihu@users.noreply.github.com>
---
 docs/how-to-add-command.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/how-to-add-command.md b/docs/how-to-add-command.md
index 557a38dd..6d3ee262 100644
--- a/docs/how-to-add-command.md
+++ b/docs/how-to-add-command.md
@@ -40,7 +40,7 @@ Use this type when a command is intended as a top-level command that can be exec
 ```ts
 configurator.command("export")
   .description("Export everything")
-  .option("--keys <realm>", "What to export")
+  .option("--keys <key>", "What to export")
   .action(exportHandlerMethod);
 ```