[james-project] 02/05: JAMES-3400 Add README.md for James CLI based on webadmin endpoints.

[bt...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit 170bf0dcc277210a159bddea90986cf5b14be26e
Author: QuanTH <hq...@linagora.com>
AuthorDate: Mon Oct 5 16:47:19 2020 +0700

    JAMES-3400 Add README.md for James CLI based on webadmin endpoints.
---
 server/protocols/webadmin-cli/README.md     | 126 ++++++++++++++++++++++++++++
 src/adr/0042-james-cli-based-on-webadmin.md |   7 +-
 2 files changed, 130 insertions(+), 3 deletions(-)

diff --git a/server/protocols/webadmin-cli/README.md b/server/protocols/webadmin-cli/README.md
new file mode 100644
index 0000000..3b4e5d0
--- /dev/null
+++ b/server/protocols/webadmin-cli/README.md
@@ -0,0 +1,126 @@
+# A WebAdmin based CLI for Apache James
+
+## Development
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface. It also aims at providing a more modern and intuitive interface.
+
+## Run the command line
+
+## Syntax
+
+General syntax to run the command line
+
+```   
+$ james-cli [OPTION] ENTITY ACTION {ARGUMENT}
+```
+
+where
+
+    OPTION: optional parameter when running the command line,
+  
+    ENTITY: represents the entity to perform action on,
+  
+    ACTION: name of the action to perform,
+  
+    ARGUMENT: arguments needed for the action.
+
+Example: 
+```
+$ james-cli --url http://127.0.0.1 --port 9999 domain list
+```
+
+The above command lists all domain names available on domain route at address http://127.0.0.1:9999. 
+It does not require any argument to execute. Options --url and --port are optional. Without them, the default value is http://127.0.0.0:8000.
+As for other commands, arguments might be required after the sub-command (ACTION such as list, add and remove).
+
+## Navigation menu
+
+- [Manage Domains](#manage-domains)
+   - [Create a domain](#create-a-domain)
+   - [Delete a domain](#delete-a-domain)
+   - [Check if a domain exists](#check-if-a-domain-exists)
+   - [Get the list of domains](#get-the-list-of-domains)
+- [Manage Users](#manage-users) 
+   - [Create an user](#create-a-user)
+   - [Test an user existence](#test-a-user-existence)
+   - [Delete an user](#delete-a-user)
+   - [Get users list](#get-users-list)
+   - [Update an user password](#update-a-user-password)
+
+## Manage Domains
+
+### Create a domain
+Add a domain to the domain list.
+```
+james-cli domain create <domainToBeCreated>
+```
+Resource name **domainToBeCreated**:
+
+- can not be null or empty
+- can not contain ‘@’
+- can not be more than 255 characters
+- can not contain ‘/’
+
+### Delete a domain
+
+Remove a domain from the domain list.
+```
+james-cli domain delete <domainToBeDeleted>
+```
+Note: Deletion of an auto-detected domain, default domain or of an auto-detected ip is not supported. We encourage you instead to review your [domain list configuration](https://james.apache.org/server/config-domainlist.html).
+
+### Check if a domain exists
+Check whether a domain exists on the domain list or not.
+```
+james-cli domain exist <domainToBeChecked>
+```
+
+### Get the list of domains
+Show all domains' name on the list.
+```
+james-cli domain list
+```
+
+
+
+## Manage Users
+
+### Create an user
+
+Add an user to the user list.
+```
+james-cli user create <username> <password>
+```
+Resource name <username> representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html)
+
+Note: if the user exists already, its password will be updated.
+
+### Test an user existence
+
+Check whether an user exists on the user list or not.
+```
+james-cli user exist <username>
+```
+Resource name <username> representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html)
+
+### Delete an user
+
+Remove an user from the user list.
+```
+james-cli user delete <username>
+```
+
+### Get users list
+
+Show all users' name on the list.
+
+```
+james-cli user list
+```
+
+### Update an user password
+Same as Create, but an user need to exist.
+
+If the user do not exist, then it will be created.
+
+
diff --git a/src/adr/0042-james-cli-based-on-webadmin.md b/src/adr/0042-james-cli-based-on-webadmin.md
index d7d0061..52b1c9d 100644
--- a/src/adr/0042-james-cli-based-on-webadmin.md
+++ b/src/adr/0042-james-cli-based-on-webadmin.md
@@ -43,7 +43,7 @@ We decided to write a new CLI client, running on top of the JVM, communicating w
 * We decided to adopt a more modern, modular CLI syntax:
 
 ```   
-$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
+$ james-cli [OPTION] ENTITY ACTION {ARGUMENT}
 ```
 where
 
@@ -59,7 +59,7 @@ where
 
 Add a domain to the domain list.
 ```
-$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated
+$ james-cli --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated
 ```
 
 In above command-line 
@@ -80,4 +80,5 @@ It aims at providing a more modern and more secure CLI, also bringing compatibil
 ## References
 * [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628)
 * [Picocli 2.0: Do More With Less](https://dzone.com/articles/whats-new-in-picocli-20)
-* [Picocli Homepage](https://picocli.info/)
\ No newline at end of file
+* [Picocli Homepage](https://picocli.info/)
+* [Native Image Maven Plugin](https://www.graalvm.org/reference-manual/native-image/NativeImageMavenPlugin/)
\ No newline at end of file


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org