From c739d9957c6257f5ec0e0d1da74dfc5120922a35 Mon Sep 17 00:00:00 2001
From: "Zaiming (Stone) Shi" <zmstone@gmail.com>
Date: Mon, 20 Mar 2023 18:25:35 +0100
Subject: [PATCH] docs: add readme for emqx_ctl app

---
 apps/emqx_ctl/README.md | 43 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/apps/emqx_ctl/README.md b/apps/emqx_ctl/README.md
index a91342606..2638031e6 100644
--- a/apps/emqx_ctl/README.md
+++ b/apps/emqx_ctl/README.md
@@ -1,4 +1,41 @@
-emqx_ctl
-=====
+# emqx_ctl
 
-Backend module for `emqx_ctl` command.
+This application accepts dynamic `emqx ctl` command registrations so plugins can add their own commands.
+Please note that the 'proxy' command `emqx_ctl` is considered deprecated, going forward, please use `emqx ctl` instead.
+
+## Add a new command
+
+To add a new command, the application must implement a callback function to handle the command, and register the command with `emqx_ctl:register_command/2` API.
+
+### Register
+
+To add a new command which can be executed from `emqx ctl`, the application must call `emqx_ctl:register_command/2` API to register the command.
+
+For example, to add a new command `myplugin` which is to be executed as `emqx ctl myplugin`, the application must call `emqx_ctl:register_command/2` API as follows:
+
+```erlang
+emqx_ctl:register_command(mypluin, {myplugin_cli, cmd}).
+```
+
+### Callback
+
+The callback function must be exported by the application and must have the following signature:
+
+```erlang
+cmd([Arg1, Arg2, ...]) -> ok.
+```
+
+It must also implement a special clause to handle the `usage` argument:
+
+```erlang
+cmd([usage]) -> "myplugin [arg1] [arg2] ...";
+```
+
+### Utility
+
+The `emqx_ctl` application provides some utility functions which help to format the output of the command.
+For example `emqx_ctl:print/2` and `emqx_ctl:usage/1`.
+
+## Reference
+
+[emqx_management_cli](../emqx_management/src/emqx_mgmt_cli.erl) can be taken as a reference for how to implement a command.