From 01f7c48328821057b0bdd6e55f29ea4a02fcd20f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Y=C3=BCce=20Tekol?= Date: Wed, 19 Apr 2023 12:37:35 +0300 Subject: [PATCH] More consistent command help and docs (#218) --- base/commands/config/config.go | 2 +- base/commands/config/config_add.go | 2 +- base/commands/config/config_import.go | 2 +- base/commands/map/map_clear.go | 2 +- base/commands/map/map_entry_set.go | 2 +- base/commands/map/map_get.go | 2 +- base/commands/map/map_set.go | 2 +- base/commands/map/map_size.go | 2 +- docs/modules/ROOT/pages/clc-completion.adoc | 7 +- docs/modules/ROOT/pages/clc-config.adoc | 106 +++++++++++++++++++- docs/modules/ROOT/pages/clc-home.adoc | 2 +- docs/modules/ROOT/pages/clc-map.adoc | 96 +++++++++++------- docs/modules/ROOT/pages/clc-object.adoc | 11 +- docs/modules/ROOT/pages/clc-sql.adoc | 2 +- docs/modules/ROOT/pages/clc-version.adoc | 11 +- docs/modules/ROOT/pages/overview.adoc | 4 + 16 files changed, 191 insertions(+), 64 deletions(-) diff --git a/base/commands/config/config.go b/base/commands/config/config.go index fe01118f..f175c853 100644 --- a/base/commands/config/config.go +++ b/base/commands/config/config.go @@ -13,7 +13,7 @@ type Cmd struct{} func (cm Cmd) Init(cc plug.InitContext) error { cc.SetTopLevel(true) - cc.SetCommandUsage("config [command]") + cc.SetCommandUsage("config [command] [flags]") help := "Show, add or change configuration" cc.SetCommandHelp(help, help) return nil diff --git a/base/commands/config/config_add.go b/base/commands/config/config_add.go index 39949e88..cbd8ae73 100644 --- a/base/commands/config/config_add.go +++ b/base/commands/config/config_add.go @@ -18,7 +18,7 @@ import ( type AddCmd struct{} func (cm AddCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage("add [configuration-name]") + cc.SetCommandUsage("add [configuration-name] [flags]") short := "Adds a configuration" long := `Adds a configuration with the given name/path and KEY=VALUE pairs diff --git a/base/commands/config/config_import.go b/base/commands/config/config_import.go index 6c4efc85..8deab688 100644 --- a/base/commands/config/config_import.go +++ b/base/commands/config/config_import.go @@ -15,7 +15,7 @@ import ( type ImportCmd struct{} func (cm ImportCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage("import [configuration-name] [source]") + cc.SetCommandUsage("import [configuration-name] [source] [flags]") short := "Imports configuration from an arbitrary source" long := `Imports configuration from an arbitrary source diff --git a/base/commands/map/map_clear.go b/base/commands/map/map_clear.go index 1cde355f..881e9163 100644 --- a/base/commands/map/map_clear.go +++ b/base/commands/map/map_clear.go @@ -19,7 +19,7 @@ type MapClearCommand struct{} func (mc *MapClearCommand) Init(cc plug.InitContext) error { help := "Delete all entries of a Map" cc.SetCommandHelp(help, help) - cc.SetCommandUsage("clear [-n map-name] [flags]") + cc.SetCommandUsage("clear") return nil } diff --git a/base/commands/map/map_entry_set.go b/base/commands/map/map_entry_set.go index 0059f62e..16ca19d3 100644 --- a/base/commands/map/map_entry_set.go +++ b/base/commands/map/map_entry_set.go @@ -21,7 +21,7 @@ type MapEntrySetCommand struct{} func (mc *MapEntrySetCommand) Init(cc plug.InitContext) error { help := "Get all entries of a Map" cc.SetCommandHelp(help, help) - cc.SetCommandUsage("entry-set [-n map-name] [flags]") + cc.SetCommandUsage("entry-set") cc.SetPositionalArgCount(0, 0) return nil } diff --git a/base/commands/map/map_get.go b/base/commands/map/map_get.go index d9bde220..7cc5a99f 100644 --- a/base/commands/map/map_get.go +++ b/base/commands/map/map_get.go @@ -22,7 +22,7 @@ func (mc *MapGetCommand) Init(cc plug.InitContext) error { addKeyTypeFlag(cc) help := "Get a value from the given Map" cc.SetCommandHelp(help, help) - cc.SetCommandUsage("get [-n map-name] [key] [flags]") + cc.SetCommandUsage("get [key] [flags]") cc.SetPositionalArgCount(1, 1) return nil } diff --git a/base/commands/map/map_set.go b/base/commands/map/map_set.go index ee8d8ce0..97a14c3c 100644 --- a/base/commands/map/map_set.go +++ b/base/commands/map/map_set.go @@ -24,7 +24,7 @@ func (mc *MapSetCommand) Init(cc plug.InitContext) error { cc.SetPositionalArgCount(2, 2) help := "Set a value in the given Map" cc.SetCommandHelp(help, help) - cc.SetCommandUsage("set [-n MAP] [key] [value] [flags]") + cc.SetCommandUsage("set [key] [value] [flags]") return nil } diff --git a/base/commands/map/map_size.go b/base/commands/map/map_size.go index 05462184..74dcb9ce 100644 --- a/base/commands/map/map_size.go +++ b/base/commands/map/map_size.go @@ -20,7 +20,7 @@ type MapSizeCommand struct{} func (mc *MapSizeCommand) Init(cc plug.InitContext) error { help := "Return the size of the given Map" cc.SetCommandHelp(help, help) - cc.SetCommandUsage("size [-n map-name]") + cc.SetCommandUsage("size") cc.SetPositionalArgCount(0, 0) return nil } diff --git a/docs/modules/ROOT/pages/clc-completion.adoc b/docs/modules/ROOT/pages/clc-completion.adoc index 8437155d..40c7fd6e 100644 --- a/docs/modules/ROOT/pages/clc-completion.adoc +++ b/docs/modules/ROOT/pages/clc-completion.adoc @@ -7,7 +7,7 @@ Usage: [source,bash] ---- -clc completion [shell] [--no-descriptions] +clc completion [shell] ---- Parameters: @@ -25,11 +25,6 @@ Parameters: * powershell * zsh -|All types - -|`--no-descriptions` -|Optional -|Disables completion descriptions |N/A |=== diff --git a/docs/modules/ROOT/pages/clc-config.adoc b/docs/modules/ROOT/pages/clc-config.adoc index c7ed170a..b1ea4ae8 100644 --- a/docs/modules/ROOT/pages/clc-config.adoc +++ b/docs/modules/ROOT/pages/clc-config.adoc @@ -6,7 +6,7 @@ Usage: [source,bash] ---- -clc config [command] [options] +clc config [command] [flags] ---- == Commands @@ -25,9 +25,87 @@ Usage: [source,bash] ---- -clc config add [target] [source] [key=value...] +clc config add [target] [source] [flags] [key=value...] ---- +Configuration keys: + +[cols="1m,1a,1a,1"] +|=== +|Key|Value|Default Value|Note + +|cluster.name +|Any string +|dev +| + +|cluster.address +|HOST:PORT / HOST / :PORT +|localhost:5701 +| + +|cluster.user +|Any string +| +| Hazelcast Enterprise only + +|cluster.password +|Any string +| +| Hazelcast Enterprise only + +|cluster.discovery-token +|Any string +| +|Viridian only + +|ssl.enabled +|true / false +|false +|Viridian or Hazelcast Enterprise + +|ssl.server +|DOMAIN_NAME (must match SSL certificate) +| +|Viridian (automatically set) or Hazelcast Enterprise + +|ssl.skip-verify +|true / false +|false +|Viridian or Hazelcast Enterprise. Disables SSL host name and client-side verification. Never set to true in production. + +|ssl.ca-path +|An absolute or relative path +| +|Viridian or Hazelcast Enterprise. Sets the path to the CA certificate. + +|ssl.key-path +|An absolute or relative path +| +|Viridian or Hazelcast Enterprise. Sets the path to the certificate key. + +|ssl.key-password +|Any sring +| +|Viridian or Hazelcast Enterprise. Sets the passwor the certificate key. + +|log.path +|An absolute or relative path or `stderr` to log to stderr. +|`$CLC_HOME/logs/YYYY-MM-DD.log` where the date is today. +| + +|log.level +|One of: + +. `error` +. `warn` +. `info` +. `debug` +| `info` +| + +|=== + Parameters: [cols="1m,1a,2a,1a"] @@ -57,11 +135,26 @@ clc config add dev cluster.name=dev cluster.address=localhost:5701 Imports configuration from an arbitrary source. +Currently importing only Viridian connection configuration is supported. + +1. On Viridian console, visit: ++ +Dashboard -> Connect Client -> Quick connection guide -> Go + +2. Copy the text in box 1 and pass it as the second parameter. +Make sure the text is quoted before running: ++ + clc config import my-config "curl https://api.viridian.hazelcast.com ... default.zip" ++ +Alternatively, you can use an already downloaded Go client sample: ++ + clc config import my-config /home/me/Downloads/hazelcast-cloud-go-sample....zip + Usage: [source,bash] ---- -clc config import [target] [source] +clc config import [configuration-name] [source] [flags] ---- Parameters: @@ -70,7 +163,7 @@ Parameters: |=== |Parameter|Required|Description|Default -|`target` +|`configuration-name` |Required |Name of the configuration or its path. If a name is used, the configuration is saved to `$CLC_HOME/configs/NAME` |N/A @@ -97,11 +190,14 @@ clc config import production ~/Downloads/hazelcast-cloud-go-sample-client-pr-381 Lists the known configurations. +A known configuration is a directory at `$CLC_HOME/configs` that contains config.yaml. +Directory names which start with dot (`.`) or underscore (`_`) are ignored. + Usage: [source,bash] ---- -clc config list +clc config list [flags] ---- Example output: diff --git a/docs/modules/ROOT/pages/clc-home.adoc b/docs/modules/ROOT/pages/clc-home.adoc index 9facfebf..a59c64d4 100644 --- a/docs/modules/ROOT/pages/clc-home.adoc +++ b/docs/modules/ROOT/pages/clc-home.adoc @@ -8,7 +8,7 @@ Usage: [source,bash] ---- -clc home [subdirectory ...] +clc home [subdirectory ...] [flags] ---- Parameters: diff --git a/docs/modules/ROOT/pages/clc-map.adoc b/docs/modules/ROOT/pages/clc-map.adoc index fe189aa9..cd995621 100644 --- a/docs/modules/ROOT/pages/clc-map.adoc +++ b/docs/modules/ROOT/pages/clc-map.adoc @@ -6,7 +6,7 @@ Usage: [source,bash] ---- -clc map [command] [options] +clc map [command] [flags] ---- == Commands @@ -26,7 +26,7 @@ Usage: [source,bash] ---- -clc map clear --name +clc map [flags] ---- Parameters: @@ -36,7 +36,7 @@ Parameters: |Parameter|Required|Description|Default |`--name`, `-n` -|Required +|Optional |Name of the map. |`default` @@ -50,9 +50,7 @@ Usage: [source,bash] ---- -clc map get --name - [--key-type {string (default), bool, json, i8, i16, i32, i64, f32, f64}] - [key] +clc map get [key] [flags] ---- Parameters: @@ -62,9 +60,9 @@ Parameters: |Parameter|Required|Description|Default |`--name`, `-n` -|Required +|Optional |Name of the map. -|`dev` +|`default` |`key` |Required @@ -73,8 +71,18 @@ Parameters: |`--key-type`, `-k` |Optional -|Data type of the key. -|String +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`. +|string + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. |=== @@ -93,14 +101,7 @@ Usage: [source,bash] ---- -clc map set --name - [key] - [value] - [--key-type {string (default), bool, json, i8, i16, i32, i64, f32, f64}] - [--value-type {string (default), bool, json, i8, i16, i32, i64, f32, f64}] - [--ttl {ns, us, ms, s, m, h (nanosecond, microsecond, millisecond, second, minute, hour)}] - [--max-idle {ns, us, ms, s, m, h (nanosecond, microsecond, millisecond, second, minute, hour)}] - +clc map set [key] [value] [flags] ---- Parameters: @@ -110,28 +111,28 @@ Parameters: |Parameter|Required|Description|Default |`--name`, `-n` -|Required +|Optional |Name of the map. -|`dev` +|`default` |`key` |Required |Key of the map entry. |N/A -|`value` +|`value`, |Required -|Value to set for the key. Mutually exclusive with `--value-file`. +|Value to set for the key. |N/A |`--key-type`, `-k` |Optional -|Data type of the key. +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` |String |`--value-type`, `-v` |Optional -|Data type of the value. +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` |String |`--ttl` @@ -150,7 +151,7 @@ Example: [source,bash] ---- -clc map set --key-type string hello --value-type f32 19.94 --name myMap --ttl 1300ms +clc map set --key-type string hello --value-type f32 19.94 --name myMap --ttl 1300 ---- == clc map entry-set @@ -161,7 +162,7 @@ Usage: [source,bash] ---- -clc map entry-set --name +clc map entry-set [flags] ---- Parameters: @@ -171,9 +172,19 @@ Parameters: |Parameter|Required|Description|Default |`--name`, `-n` -|Required +|Optional |Name of the map. -|`dev` +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. |=== @@ -192,7 +203,7 @@ Usage: [source,bash] ---- -clc map size --name +clc map size [flags] ---- Parameters: @@ -202,23 +213,21 @@ Parameters: |Parameter|Required|Description|Default |`--name`, `-n` -|Required +|Optional |Name of the map. -|`dev` +|`default` |=== == clc map remove -Deletes the value of a given key in a map. +Deletes the value of a given key in a map and returns the key. Usage: [source,bash] ---- -clc map remove --name - [key] - [--key-type {string (default), bool, json, i8, i16, i32, i64, f32, f64}] +clc map remove [flags] [key] ---- Parameters: @@ -228,9 +237,9 @@ Parameters: |Parameter|Required|Description|Default |`--name`, `-n` -|Required +|Optional |Name of the map. -|`dev` +|`default` |`key` |Required @@ -239,9 +248,19 @@ Parameters: |`--key-type`, `-k` |Optional -|Data type of the key. +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` |String +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + |=== Example: @@ -249,4 +268,5 @@ Example: [source,bash] ---- clc map remove --name myMap --key-type string k1 +k1 ---- diff --git a/docs/modules/ROOT/pages/clc-object.adoc b/docs/modules/ROOT/pages/clc-object.adoc index c4a62b4f..d8cfae6b 100644 --- a/docs/modules/ROOT/pages/clc-object.adoc +++ b/docs/modules/ROOT/pages/clc-object.adoc @@ -21,9 +21,13 @@ Usage: [source,bash] ---- -clc object list [type] [--show-hidden] +clc object list [object-type] [flags] ---- +Available object types (_case insensitive_): + + + Parameters: [cols="1m,1a,2a,1a"] @@ -34,13 +38,10 @@ Parameters: |Optional |Type of the objects to be listed. If not specified, the command lists all the objects. Available types (_case insensitive_): -* atomicLong -* atomicReference * cache * cardinalityEstimator * countdownLatch * eventJournal -* fencedLock * flakeIdGenerator * list * map @@ -53,6 +54,8 @@ Parameters: * set * topic +Note that CP subsystem objects cannot be listed. + |All types |`--show-hidden` diff --git a/docs/modules/ROOT/pages/clc-sql.adoc b/docs/modules/ROOT/pages/clc-sql.adoc index 614540e5..02e70d32 100644 --- a/docs/modules/ROOT/pages/clc-sql.adoc +++ b/docs/modules/ROOT/pages/clc-sql.adoc @@ -7,7 +7,7 @@ Usage: [source,bash] ---- -clc sql "[query]" [--format OUTPUT-FORMAT] +clc sql [query] [flags] ---- Parameters: diff --git a/docs/modules/ROOT/pages/clc-version.adoc b/docs/modules/ROOT/pages/clc-version.adoc index 4ff22307..fe725714 100644 --- a/docs/modules/ROOT/pages/clc-version.adoc +++ b/docs/modules/ROOT/pages/clc-version.adoc @@ -3,7 +3,9 @@ {description} -The following are printed: +Without any flags, only the version of the Hazelcast CLC is printed. + +With the `--verbose` flag, the following are printed: * The Hazelcast CLC version * Latest Git commit hash to the Hazelcast CLC @@ -12,6 +14,13 @@ The following are printed: Usage: +[source,bash] +---- +clc version [flags] +---- + +Example: + [source,bash] ---- clc version --verbose diff --git a/docs/modules/ROOT/pages/overview.adoc b/docs/modules/ROOT/pages/overview.adoc index 3eccccb0..5fe0a6ff 100644 --- a/docs/modules/ROOT/pages/overview.adoc +++ b/docs/modules/ROOT/pages/overview.adoc @@ -6,6 +6,10 @@ The Hazelcast CLC simplifies the client setup process for Windows and Unix-like local environments. Within minutes of installation, you can start to perform common tasks on clusters. +== Install + +See xref:install-clc.adoc[installation documentation]. + == Use Cases Example use cases for the Hazelcast CLC.