From e61d89280c0c372ecb5148e781ce507e6e9730c9 Mon Sep 17 00:00:00 2001
From: Hafiz Muhammad Moaz <hafizmoazkhalid@gmail.com>
Date: Fri, 28 Aug 2026 03:45:39 +0500
Subject: [PATCH] docs: add step by step custom command guide to README (fixes
 #7)

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/README.md b/README.md
index df1a34c..7334e2d 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,64 @@ Discovers, registers and runs commands:
 - Unknown commands fall back to `Index` (which lists available commands) and suggest the closest matching command name
 - `getArgument()`, `getArguments()`, `getOption()` and `getOptions()` expose the parsed command line
 
+## Creating a Custom Command
+
+1. Create a command by extending `Framework\CLI\Command` and implementing `run()`:
+
+```php
+<?php
+
+use Framework\CLI\CLI;
+use Framework\CLI\Command;
+
+class GreetCommand extends Command
+{
+    protected string $name = 'greet';
+
+    public function getDescription() : string
+    {
+        return 'Greets the user.';
+    }
+
+    public function getOptions() : array
+    {
+        return ['-s' => 'Shout the greeting.']; // options the command accepts
+    }
+
+    public function run() : void
+    {
+        $name = $this->getConsole()->getArgument(0) ?? 'world';
+        $message = "Hello, {$name}!";
+
+        if ($this->getConsole()->getOption('s')) {
+            $message = \strtoupper($message);
+        }
+
+        CLI::write($message);
+    }
+}
+```
+
+2. Register the command with a `Console` and run it. Pass a Command instance or its class name:
+
+```php
+use Framework\CLI\Console;
+
+$console = new Console();
+$console->addCommand(GreetCommand::class);
+$console->run();
+```
+
+3. Call it from the terminal:
+
+```bash
+php app greet Alice          # Hello, Alice!
+php app greet Alice -s       # HELLO, ALICE!
+php app help greet           # auto generated usage output
+```
+
+`run()` is invoked automatically. The `Console` parses argv for you: everything before the first option is available via `getArgument()`, and `--option=value` or `-o value` style options via `getOption()`. Commands can also declare `setAliases()` to be reachable by multiple names and `setGroup()` to organize them in the `index` listing.
+
 ## Installation
 ```bash
 composer require webisters/cli