MXS-1390: Add detailed MaxCtrl documentation

Added a more detailed description for commands that needed it.

maxctrl/lib/alter.js

@@ -12,32 +12,69 @@
  */
 require('./common.js')()
 
+// TODO: Somehow query these lists from MaxScale
+
+// List of service parameters that can be altered at runtime
+const service_params = [
+    'user',
+    'passwd',
+    'enable_root_user',
+    'max_connections',
+    'connection_timeout',
+    'auth_all_servers',
+    'optimize_wildcard',
+    'strip_db_esc',
+    'localhost_match_wildcard_host',
+    'max_slave_connections',
+    'max_slave_replication_lag'
+]
+
+// List of maxscale parameters that can be altered at runtime
+const maxscale_params = [
+    'auth_connect_timeout',
+    'auth_read_timeout',
+    'auth_write_timeout',
+    'admin_auth'
+]
+
 exports.command = 'alter <command>'
 exports.desc = 'Alter objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('server <server> <key> <value>', 'Alter server parameters', {}, function(argv) {
+        .command('server <server> <key> <value>', 'Alter server parameters', function(yargs) {
+            return yargs.epilog('To display the server parameters, execute `show server <server>`');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return updateValue(host, 'servers/' + argv.server, 'data.attributes.parameters.' + argv.key, argv.value)
             })
         })
-        .command('monitor <monitor> <key> <value>', 'Alter monitor parameters', {}, function(argv) {
+        .command('monitor <monitor> <key> <value>', 'Alter monitor parameters', function(yargs) {
+            return yargs.epilog('To display the monitor parameters, execute `show monitor <monitor>`');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return updateValue(host, 'monitors/' + argv.monitor, 'data.attributes.parameters.' + argv.key, argv.value)
             })
         })
-        .command('service <service> <key> <value>', 'Alter service parameters', {}, function(argv) {
+        .command('service <service> <key> <value>', 'Alter service parameters', function(yargs) {
+            return yargs.epilog('To display the service parameters, execute `show service <service>`. ' +
+                                'The following list of parameters can be altered at runtime:\n\n' + JSON.stringify(service_params, null, 4));
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return updateValue(host, 'services/' + argv.service, 'data.attributes.parameters.' + argv.key, argv.value)
             })
         })
-        .command('logging <key> <value>', 'Alter logging parameters', {}, function(argv) {
+        .command('logging <key> <value>', 'Alter logging parameters', function(yargs) {
+            return yargs.epilog('To display the logging parameters, execute `show logging`');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return updateValue(host, 'maxscale/logs', 'data.attributes.parameters.' + argv.key, argv.value)
             })
         })
-        .command('maxscale <key> <value>', 'Alter MaxScale parameters', {}, function(argv) {
+        .command('maxscale <key> <value>', 'Alter MaxScale parameters', function(yargs) {
+            return yargs.epilog('To display the MaxScale parameters, execute `show maxscale`. ' +
+                                'The following list of parameters can be altered at runtime:\n\n' + JSON.stringify(maxscale_params, null, 4));
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return updateValue(host, 'maxscale', 'data.attributes.parameters.' + argv.key, argv.value)
             })

maxctrl/lib/call.js

@@ -17,7 +17,9 @@ exports.desc = 'Call module commands'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('command <module> <command> [parameters...]', 'Call a module command', {}, function(argv) {
+        .command('command <module> <command> [params...]', 'Call a module command', function(yargs) {
+            return yargs.epilog('To inspect the list of module commands, execute `list commands`');
+        }, function(argv) {
             // First we have to find the correct method to use
             maxctrl(argv, function(host) {
                 return doRequest(host, 'maxscale/modules/' + argv.module + '/', function(resp) {
@@ -31,7 +33,7 @@ exports.builder = function(yargs) {
                         }
                     })
 
-                    return doAsyncRequest(host, 'maxscale/modules/' + argv.module + '/' + argv.command + '?' + argv.parameters.join('&'),
+                    return doAsyncRequest(host, 'maxscale/modules/' + argv.module + '/' + argv.command + '?' + argv.params.join('&'),
                                           function(resp) {
                                               return JSON.stringify(resp, null, 4)
                                           }, { method: verb })

maxctrl/lib/clear.js

@@ -17,7 +17,9 @@ exports.desc = 'Clear object state'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('server <server> <state>', 'Clear server state', {}, function(argv) {
+        .command('server <server> <state>', 'Clear server state', function(yargs) {
+            return yargs.epilog('This command clears a server state set by the `set server <server> <state>` command');
+        }, function(argv) {
             var target = 'servers/' + argv.server + '/clear?state=' + argv.state
             maxctrl(argv, function(host) {
                 return doRequest(host, target, null, {method: 'PUT'})

maxctrl/lib/cluster.js

@@ -125,8 +125,11 @@ exports.desc = 'Cluster objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('diff <target>', 'Show difference between host servers and <target>. ' +
+        .command('diff <target>', 'Show difference between host servers and <target>.', function(yargs) {
-                 'Value must be in HOST:PORT format', {}, function(argv) {
+            return yargs.epilog('The list of host servers is controlled with the --hosts option. ' +
+                                'The target server should not be in the host list. Value of <target> ' +
+                                'must be in HOST:PORT format');
+        }, function(argv) {
 
                      maxctrl(argv, function(host) {
                          return getDiffs(host, argv.target)
@@ -172,7 +175,15 @@ exports.builder = function(yargs) {
                              })
                      })
                  })
-        .command('sync <target>', 'Synchronize the cluster with target MaxScale server.', {}, function(argv) {
+        .command('sync <target>', 'Synchronize the cluster with target MaxScale server.', function(yargs) {
+            return yargs.epilog('This command will alter all MaxScale instances given in the --hosts ' +
+                                'option to represent the <target> MaxScale. If the synchronization of ' +
+                                'a MaxScale instance fails, it will be disabled by executing the `stop maxscale` ' +
+                                'command on that instance. Synchronization can be attempted again if a previous ' +
+                                'attempt failed due to a network failure or some other ephemeral error. Any other ' +
+                                'errors require manual synchronization of the MaxScale configuration files and a ' +
+                                'restart of the failed Maxscale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getDiffs(argv.target, host)
                     .then(function(diffs) {

maxctrl/lib/create.js

@@ -42,7 +42,12 @@ exports.builder = function(yargs) {
             describe: 'Link the created server to these monitors',
             type: 'array'
         })
-        .command('server <name> <host> <port>', 'Create a new server', {}, function(argv) {
+        .command('server <name> <host> <port>', 'Create a new server', function(yargs) {
+            return yargs.epilog('The created server will not be used by any services or monitors ' +
+                                'unless the --services or --monitors options are given. The list ' +
+                                'of servers a service or a monitor uses can be altered with the ' +
+                                '`link` and `unlink` commands.');
+        }, function(argv) {
             var server = {
                 'data': {
                     'id': argv.name,
@@ -90,7 +95,10 @@ exports.builder = function(yargs) {
             describe: 'Password for the monitor user',
             type: 'string'
         })
-        .command('monitor <name> <module>', 'Create a new monitor', {}, function(argv) {
+        .command('monitor <name> <module>', 'Create a new monitor', function(yargs) {
+            return yargs.epilog('The list of servers given with the --servers option should not ' +
+                                'contain any servers that are already monitored by another monitor.');
+        }, function(argv) {
 
             var monitor = {
                 'data': {
@@ -147,7 +155,9 @@ exports.builder = function(yargs) {
             describe: 'TLS certificate verification depth',
             type: 'string'
         })
-        .command('listener <service> <name> <port>', 'Create a new listener', {}, function(argv) {
+        .command('listener <service> <name> <port>', 'Create a new listener', function(yargs) {
+            return yargs.epilog('The new listener will be taken into use immediately.');
+        }, function(argv) {
 
             var listener = {
                 'data': {
@@ -181,7 +191,12 @@ exports.builder = function(yargs) {
             default: 'basic',
             choices: ['admin', 'basic']
         })
-        .command('user <name> <password>', 'Create a new network user', {}, function(argv) {
+        .command('user <name> <password>', 'Create a new network user', function(yargs) {
+            return yargs.epilog('The created user can be used with the MaxScale REST API as ' +
+                                'well as the MaxAdmin network interface. By default the created ' +
+                                'user will have administrative privileges. To limit the user to ' +
+                                'read-only operations, use the `--type=basic` option.');
+        }, function(argv) {
 
             var user = {
                 'data': {

maxctrl/lib/destroy.js

@@ -17,22 +17,36 @@ exports.desc = 'Destroy objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('server <name>', 'Destroy an unused server', {}, function(argv) {
+        .command('server <name>', 'Destroy an unused server', function(yargs) {
+            return yargs.epilog('The server must be unlinked from all services and monitor before it can be destroyed.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'servers/' + argv.name, null, {method: 'DELETE'})
             })
         })
-        .command('monitor <name>', 'Destroy an unused monitor', {}, function(argv) {
+        .command('monitor <name>', 'Destroy an unused monitor', function(yargs) {
+            return yargs.epilog('The monitor must be unlinked from all servers before it can be destroyed.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'monitors/' + argv.name, null, {method: 'DELETE'})
             })
         })
-        .command('listener <service> <name>', 'Destroy an unused listener', {}, function(argv) {
+        .command('listener <service> <name>', 'Destroy an unused listener', function(yargs) {
+            return yargs.epilog('Destroying a monitor causes it to be removed on the next restart. ' +
+                                'Destroying a listener at runtime stops it from accepting new ' +
+                                'connections but it will still be bound to the listening socket. This ' +
+                                'means that new listeners cannot be created to replace destroyed listeners ' +
+                                'without restarting MaxScale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'services/' + argv.service + '/listeners/' + argv.name, null, {method: 'DELETE'})
             })
         })
-        .command('user <name>', 'Remove a network user', {}, function(argv) {
+        .command('user <name>', 'Remove a network user', function(yargs) {
+            return yargs.epilog('The last remaining administrative user cannot be removed. ' +
+                                'Create a replacement administrative user before attempting ' +
+                                'to remove the last administrative user.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'users/inet/' + argv.name, null, {method: 'DELETE'})
             })

maxctrl/lib/disable.js

@@ -24,7 +24,9 @@ exports.desc = 'Disable functionality'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('log-priority <log>', 'Disable log priority [warning|notice|info|debug]', {}, function(argv) {
+        .command('log-priority <log>', 'Disable log priority [warning|notice|info|debug]', function(yargs) {
+            return yargs.epilog('The `debug` log priority is only available for debug builds of MaxScale.');
+        }, function(argv) {
             if (log_levels.indexOf(argv.log) != -1) {
                 maxctrl(argv, function(host) {
                     return updateValue(host, 'maxscale/logs', 'data.attributes.parameters.log_' + argv.log, false)
@@ -35,7 +37,9 @@ exports.builder = function(yargs) {
                 })
             }
         })
-        .command('account <name>', 'Disable a Linux user account from administrative use', {}, function(argv) {
+        .command('account <name>', 'Disable a Linux user account from administrative use', function(yargs) {
+            return yargs.epilog('The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'users/unix/' + argv.name, null, { method: 'DELETE'})
             })

maxctrl/lib/enable.js

@@ -24,7 +24,9 @@ exports.desc = 'Enable functionality'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('log-priority <log>', 'Enable log priority [warning|notice|info|debug]', {}, function(argv) {
+        .command('log-priority <log>', 'Enable log priority [warning|notice|info|debug]', function(yargs) {
+            return yargs.epilog('The `debug` log priority is only available for debug builds of MaxScale.');
+        }, function(argv) {
             if (log_levels.indexOf(argv.log) != -1) {
                 maxctrl(argv, function(host) {
                     return updateValue(host, 'maxscale/logs', 'data.attributes.parameters.log_' + argv.log, true)
@@ -42,7 +44,9 @@ exports.builder = function(yargs) {
             default: 'basic',
             choices: ['admin', 'basic']
         })
-        .command('account <name>', 'Activate a Linux user account for administrative use', {}, function(argv) {
+        .command('account <name>', 'Activate a Linux user account for administrative use', function(yargs) {
+            return yargs.epilog('The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface');
+        }, function(argv) {
             var req_body = {
                 data: {
                     id: argv.name,

maxctrl/lib/link.js

@@ -35,10 +35,21 @@ exports.desc = 'Link objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('service <name> <server...>', 'Link servers to a service', {}, function(argv) {
+        .command('service <name> <server...>', 'Link servers to a service', function(yargs) {
+            return yargs.epilog('This command links servers to a service, making them available ' +
+                                'for any connections that use the service. Before a server is ' +
+                                'linked to a service, it should be linked to a monitor so that ' +
+                                'the server state is up to date. Newly linked server are only ' +
+                                'available to new connections, existing connections will use the ' +
+                                'old list of servers.');
+        }, function(argv) {
             addServer(argv, 'services/' + argv.name, argv.server)
         })
-        .command('monitor <name> <server...>', 'Link servers to a monitor', {}, function(argv) {
+        .command('monitor <name> <server...>', 'Link servers to a monitor', function(yargs) {
+            return yargs.epilog('Linking a server to a monitor will add it to the list of servers ' +
+                                'that are monitored by that monitor. A server can be monitored by ' +
+                                'only one monitor at a time.');
+        }, function(argv) {
             addServer(argv, 'monitors/' + argv.name, argv.server)
         })
         .usage('Usage: link <command>')

maxctrl/lib/list.js

@@ -18,7 +18,9 @@ exports.desc = 'List objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('servers', 'List servers', {}, function(argv) {
+        .command('servers', 'List servers', function(yargs) {
+            return yargs.epilog('List all servers in MaxScale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'servers', [
                     {'Server': 'id'},
@@ -29,7 +31,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('services', 'List services', {}, function(argv) {
+        .command('services', 'List services', function(yargs) {
+            return yargs.epilog('List all services and the servers they use.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'services',[
                     {'Service': 'id'},
@@ -40,7 +44,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('listeners <service>', 'List listeners of a service', {}, function(argv) {
+        .command('listeners <service>', 'List listeners of a service', function(yargs) {
+            return yargs.epilog('List listeners for a service.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getSubCollection(host, 'services/' + argv.service, 'attributes.listeners', [
                     {'Name': 'id'},
@@ -49,7 +55,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('monitors', 'List monitors', {}, function(argv) {
+        .command('monitors', 'List monitors', function(yargs) {
+            return yargs.epilog('List all monitors in MaxScale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'monitors', [
                     {'Monitor': 'id'},
@@ -58,7 +66,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('sessions', 'List sessions', {}, function(argv) {
+        .command('sessions', 'List sessions', function(yargs) {
+            return yargs.epilog('List all client sessions.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'sessions',[
                     {'Id': 'id'},
@@ -68,7 +78,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('filters', 'List filters', {}, function(argv) {
+        .command('filters', 'List filters', function(yargs) {
+            return yargs.epilog('List all filters in MaxScale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'filters', [
                     {'Filter': 'id'},
@@ -77,7 +89,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('modules', 'List loaded modules', {}, function(argv) {
+        .command('modules', 'List loaded modules', function(yargs) {
+            return yargs.epilog('List all currently loaded modules.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'maxscale/modules',[
                     {'Module':'id'},
@@ -86,14 +100,18 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('users', 'List created network users', {}, function(argv) {
+        .command('users', 'List created network users', function(yargs) {
+            return yargs.epilog('List the users that can be used to connect to the MaxScale REST API.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'users/inet',[
                     {'Name':'id'}
                 ])
             })
         })
-        .command('commands', 'List module commands', {}, function(argv) {
+        .command('commands', 'List module commands', function(yargs) {
+            return yargs.epilog('List all available module commands.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getCollection(host, 'maxscale/modules',[
                     {'Module':'id'},

maxctrl/lib/rotate.js

@@ -17,7 +17,9 @@ exports.desc = 'Rotate log files'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('logs', 'Rotate log files by closing and reopening the files', {}, function(argv) {
+        .command('logs', 'Rotate log files by closing and reopening the files', function(yargs) {
+            return yargs.epilog('This command is intended to be used with the `logrotate` command.');
+        }, function(argv) {
             maxctrl(argv, function(host){
                 return doRequest(host, 'maxscale/logs/flush/', null, {method: 'POST'})
             })

maxctrl/lib/set.js

@@ -17,7 +17,14 @@ exports.desc = 'Set object state'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('server <server> <state>', 'Set server state', {}, function(argv) {
+        .command('server <server> <state>', 'Set server state', function(yargs) {
+            return yargs.epilog('If <server> is monitored by a monitor, this command should ' +
+                                'only be used to set the server into the `maintenance` state. ' +
+                                'Any other states will be overridden by the monitor on the next ' +
+                                'monitoring interval. To manually control server states, use the ' +
+                                '`stop monitor <name>` command to stop the monitor before setting ' +
+                                'the server states manually.');
+        }, function(argv) {
             var target = 'servers/' + argv.server + '/set?state=' + argv.state
             maxctrl(argv, function(host) {
                 return doRequest(host, target, null, {method: 'PUT'})

maxctrl/lib/show.js

@@ -18,7 +18,12 @@ exports.desc = 'Show objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('server <server>', 'Show server', {}, function(argv) {
+        .command('server <server>', 'Show server', function(yargs) {
+            return yargs.epilog('Show detailed information about a server. The `Parameters` ' +
+                                'field contains the currently configured parameters for this ' +
+                                'server. See `help alter server` for more details about altering ' +
+                                'server parameters.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'servers/' + argv.server, [
                     {'Server': 'id'},
@@ -35,7 +40,12 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('service <service>', 'Show service', {}, function(argv) {
+        .command('service <service>', 'Show service', function(yargs) {
+            return yargs.epilog('Show detailed information about a service. The `Parameters` ' +
+                                'field contains the currently configured parameters for this ' +
+                                'service. See `help alter service` for more details about altering ' +
+                                'service parameters.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'services/' + argv.service, [
                     {'Service': 'id'},
@@ -50,7 +60,12 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('monitor <monitor>', 'Show monitor', {}, function(argv) {
+        .command('monitor <monitor>', 'Show monitor', function(yargs) {
+            return yargs.epilog('Show detailed information about a monitor. The `Parameters` ' +
+                                'field contains the currently configured parameters for this ' +
+                                'monitor. See `help alter monitor` for more details about altering ' +
+                                'monitor parameters.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'monitors/' + argv.monitor, [
                     {'Monitor': 'id'},
@@ -61,7 +76,12 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('session <session>', 'Show session', {}, function(argv) {
+        .command('session <session>', 'Show session', function(yargs) {
+            return yargs.epilog('Show detailed information about a single session. ' +
+                                'The list of sessions can be retrieved with the ' +
+                                '`list sessions` command. The <session> is the session ' +
+                                'ID of a particular session.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'sessions/' + argv.session, [
                     {'Id': 'id'},
@@ -74,7 +94,9 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('filter <filter>', 'Show filter', {}, function(argv) {
+        .command('filter <filter>', 'Show filter', function(yargs) {
+            return yargs.epilog('The list of services that use this filter is show in the `Services` field.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'filters/' + argv.filter, [
                     {'Filter': 'id'},
@@ -84,7 +106,10 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('module <module>', 'Show loaded module', {}, function(argv) {
+        .command('module <module>', 'Show loaded module', function(yargs) {
+            return yargs.epilog('This command shows all available parameters as well as ' +
+                                'detailed version information of a loaded module.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'maxscale/modules/' + argv.module, [
                     {'Module': 'id'},
@@ -97,7 +122,10 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('maxscale', 'Show MaxScale information', {}, function(argv) {
+        .command('maxscale', 'Show MaxScale information', function(yargs) {
+            return yargs.epilog('See `help alter maxscale` for more details about altering ' +
+                                'MaxScale parameters.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'maxscale', [
                     {'Version': 'attributes.version'},
@@ -108,7 +136,10 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('logging', 'Show MaxScale logging information', {}, function(argv) {
+        .command('logging', 'Show MaxScale logging information', function(yargs) {
+            return yargs.epilog('See `help alter logging` for more details about altering ' +
+                                'logging parameters.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getResource(host, 'maxscale/logs', [
                     {'Current Log File': 'attributes.log_file'},
@@ -117,7 +148,10 @@ exports.builder = function(yargs) {
                 ])
             })
         })
-        .command('commands <module>', 'Show module commands of a module', {}, function(argv) {
+        .command('commands <module>', 'Show module commands of a module', function(yargs) {
+            return yargs.epilog('This command shows the parameters the command expects with ' +
+                                'the parameter descriptions.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return getSubCollection(host, 'maxscale/modules/' + argv.module, 'attributes.commands', [
                     {'Command': 'id'},

maxctrl/lib/start.js

@@ -17,17 +17,24 @@ exports.desc = 'Start objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('service <name>', 'Start a service', {}, function(argv) {
+        .command('service <name>', 'Start a service', function(yargs) {
+            return yargs.epilog('This starts a service stopped by `stop service <name>`');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'services/' + argv.name + '/start', null, {method: 'PUT'})
             })
         })
-        .command('monitor <name>', 'Start a monitor', {}, function(argv) {
+        .command('monitor <name>', 'Start a monitor', function(yargs) {
+            return yargs.epilog('This starts a monitor stopped by `stop monitor <name>`');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'monitors/' + argv.name + '/start', null, {method: 'PUT'})
             })
         })
-        .command('maxscale', 'Start MaxScale by starting all services', {}, function(argv) {
+        .command('maxscale', 'Start MaxScale by starting all services', function(yargs) {
+            return yargs.epilog('This command will execute the `start service` command for ' +
+                                'all services in MaxScale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'services/', function(res) {
                     var promises = []

maxctrl/lib/stop.js

@@ -17,17 +17,28 @@ exports.desc = 'Stop objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('service <name>', 'Stop a service', {}, function(argv) {
+        .command('service <name>', 'Stop a service', function(yargs) {
+            return yargs.epilog('Stopping a service will prevent all the listeners for that service ' +
+                                'from accepting new connections. Existing connections will still be ' +
+                                'handled normally until they are closed.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'services/' + argv.name + '/stop', null, {method: 'PUT'})
             })
         })
-        .command('monitor <name>', 'Stop a monitor', {}, function(argv) {
+        .command('monitor <name>', 'Stop a monitor', function(yargs) {
+            return yargs.epilog('Stopping a monitor will pause the monitoring of the servers. ' +
+                                'This can be used to manually control server states with the ' +
+                                '`set server` command.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'monitors/' + argv.name + '/stop', null, {method: 'PUT'})
             })
         })
-        .command('maxscale', 'Stop MaxScale by stopping all services', {}, function(argv) {
+        .command('maxscale', 'Stop MaxScale by stopping all services', function(yargs) {
+            return yargs.epilog('This command will execute the `stop service` command for ' +
+                                'all services in MaxScale.');
+        }, function(argv) {
             maxctrl(argv, function(host) {
                 return doRequest(host, 'services/', function(res) {
                     var promises = []

maxctrl/lib/unlink.js

@@ -35,10 +35,19 @@ exports.desc = 'Unlink objects'
 exports.handler = function() {}
 exports.builder = function(yargs) {
     yargs
-        .command('service <name> <server...>', 'Unlink servers from a service', {}, function(argv) {
+        .command('service <name> <server...>', 'Unlink servers from a service', function(yargs) {
+            return yargs.epilog('This command unlinks servers from a service, removing them from ' +
+                                'the list of available servers for that service. New connections to ' +
+                                'the service will not use the unlinked servers but existing ' +
+                                'connections can still use the servers.');
+        }, function(argv) {
             removeServer(argv, 'services/' + argv.name, argv.server)
         })
-        .command('monitor <name> <server...>', 'Unlink servers from a monitor', {}, function(argv) {
+        .command('monitor <name> <server...>', 'Unlink servers from a monitor', function(yargs) {
+            return yargs.epilog('This command unlinks servers from a monitor, removing them from ' +
+                                'the list of monitored servers. The servers will be left in their ' +
+                                'current state when they are unlinked from a monitor.');
+        }, function(argv) {
             removeServer(argv, 'monitors/' + argv.name, argv.server)
         })
         .usage('Usage: unlink <command>')