minor improvements to wording of inline command help

12 files changed, 50 insertions, 48 deletions

diff --git a/lib/leap_cli/commands/ca.rb b/lib/leap_cli/commands/ca.rb
index 7c6fc4d..d3f864a 100644
--- a/lib/leap_cli/commands/ca.rb
+++ b/lib/leap_cli/commands/ca.rb
@@ -9,6 +9,7 @@ module LeapCli; module Commands
   command :cert do |cert|
 
     cert.desc 'Creates two Certificate Authorities (one for validating servers and one for validating clients).'
+    cert.long_desc 'See see what values are used in the generation of the certificates (like name and key size), run `leap inspect provider` and look for the "ca" property. To see the details of the created certs, run `leap inspect <file>`.'
     cert.command :ca do |ca|
       ca.action do |global_options,options,args|
         assert_config! 'provider.ca.name'
@@ -17,7 +18,7 @@ module LeapCli; module Commands
       end
     end
 
-    cert.desc 'Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed'
+    cert.desc 'Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed.'
     cert.long_desc 'This command will a generate new certificate for a node if some value in the node has changed ' +
                    'that is included in the certificate (like hostname or IP address), or if the old certificate will be expiring soon. ' +
                    'Sometimes, you might want to force the generation of a new certificate, ' +
@@ -45,7 +46,7 @@ module LeapCli; module Commands
       end
     end
 
-    cert.desc 'Creates a Diffie-Hellman parameter file' # (needed for server-side of some TLS connections)
+    cert.desc 'Creates a Diffie-Hellman parameter file.' # (needed for server-side of some TLS connections)
     cert.command :dh do |dh|
       dh.action do |global_options,options,args|
         long_running do
@@ -79,7 +80,8 @@ module LeapCli; module Commands
     # nice details about CSRs:
     #   http://www.redkestrel.co.uk/Articles/CSR.html
     #
-    cert.desc 'Creates a CSR for use in buying a commercial X.509 certificate'
+    cert.desc "Creates a CSR for use in buying a commercial X.509 certificate."
+    cert.long_desc "The CSR created is for the for the provider's primary domain. The properties used for this CSR come from `provider.ca.server_certificates`."
     cert.command :csr do |csr|
       #c.switch 'sign', :desc => 'additionally creates a cert that is signed by your own CA (recommended only for testing)', :negatable => false
       csr.action do |global_options,options,args|
diff --git a/lib/leap_cli/commands/clean.rb b/lib/leap_cli/commands/clean.rb
index 8847b7d..a9afff5 100644
--- a/lib/leap_cli/commands/clean.rb
+++ b/lib/leap_cli/commands/clean.rb
@@ -1,7 +1,7 @@
 module LeapCli
   module Commands
 
-    desc 'Removes all files generated with the "compile" command'
+    desc 'Removes all files generated with the "compile" command.'
     command :clean do |c|
       c.action do |global_options,options,args|
         Dir.glob(path([:hiera, '*'])).each do |file|
diff --git a/lib/leap_cli/commands/compile.rb b/lib/leap_cli/commands/compile.rb
index 0e645d6..3cdd5dd 100644
--- a/lib/leap_cli/commands/compile.rb
+++ b/lib/leap_cli/commands/compile.rb
@@ -2,7 +2,7 @@
 module LeapCli
   module Commands
 
-    desc 'Compiles node configuration files into hiera files used for deployment'
+    desc 'Compiles node configuration files into hiera files used for deployment.'
     command :compile do |c|
       c.action do |global_options,options,args|
         compile_hiera_files
diff --git a/lib/leap_cli/commands/deploy.rb b/lib/leap_cli/commands/deploy.rb
index 115f06c..024e8d0 100644
--- a/lib/leap_cli/commands/deploy.rb
+++ b/lib/leap_cli/commands/deploy.rb
@@ -4,9 +4,9 @@ module LeapCli
 
     DEFAULT_TAGS = ['leap_base','leap_service']
 
-    desc 'Apply recipes to a node or set of nodes'
-    long_desc 'The node-filter can be the name of a node, service, or tag.'
-    arg_name 'node-filter'
+    desc 'Apply recipes to a node or set of nodes.'
+    long_desc 'The FILTER can be the name of a node, service, or tag.'
+    arg_name 'FILTER'
     command :deploy do |c|
 
       # --fast
diff --git a/lib/leap_cli/commands/inspect.rb b/lib/leap_cli/commands/inspect.rb
index 97d0b20..0c40356 100644
--- a/lib/leap_cli/commands/inspect.rb
+++ b/lib/leap_cli/commands/inspect.rb
@@ -1,11 +1,11 @@
 module LeapCli; module Commands
 
-  desc 'Prints information about a file or node.'
-  arg_name '<file-or-node>', :optional => false
+  desc 'Prints details about a file. Alternately, the argument FILE can be the name of a node, service or tag.'
+  arg_name 'FILE'
   command :inspect do |c|
     c.action do |global_options,options,args|
       object = args.first
-      assert! object, 'A file path or node name is required'
+      assert! object, 'A file path or node/service/tag name is required'
       method = inspection_method(object)
       if method && defined?(method)
         self.send(method, object, options)
diff --git a/lib/leap_cli/commands/list.rb b/lib/leap_cli/commands/list.rb
index 02389e7..4ff2367 100644
--- a/lib/leap_cli/commands/list.rb
+++ b/lib/leap_cli/commands/list.rb
@@ -4,13 +4,13 @@ module LeapCli; module Commands
 
   desc 'List nodes and their classifications'
   long_desc 'Prints out a listing of nodes, services, or tags. ' +
-            'The node-filter can be a list of names of nodes, services, or tags. ' +
+            'If present, the FILTER can be a list of names of nodes, services, or tags. ' +
             'If the name is prefixed with +, this acts like an AND condition. ' +
             "For example:\n\n" +
-            " * node1 node2    -> matches all nodes named \"node1\" OR \"node2\"\n\n" +
-            " * openvpn +local -> matches all nodes with service \"openvpn\" AND tag \"local\""
+            "`leap list node1 node2` matches all nodes named \"node1\" OR \"node2\"\n\n" +
+            "`leap list openvpn +local` matches all nodes with service \"openvpn\" AND tag \"local\""
 
-  arg_name '[node-filter]', :optional => true
+  arg_name 'FILTER', :optional => true
   command :list do |c|
     c.flag 'print', :desc => 'What attributes to print (optional)'
     c.action do |global_options,options,args|
diff --git a/lib/leap_cli/commands/new.rb b/lib/leap_cli/commands/new.rb
index b6eb4f1..bf8e7f1 100644
--- a/lib/leap_cli/commands/new.rb
+++ b/lib/leap_cli/commands/new.rb
@@ -6,10 +6,10 @@ module LeapCli; module Commands
   arg_name 'DIRECTORY'
   skips_pre
   command :new do |c|
-    c.flag 'name', :desc => "The name of the provider" #, :default_value => 'Example'
-    c.flag 'domain', :desc => "The primary domain of the provider" #, :default_value => 'example.org'
-    c.flag 'platform', :desc => "File path of the leap_platform directory" #, :default_value => '../leap_platform'
-    c.flag 'contacts', :desc => "Default email address contacts" #, :default_value => 'root'
+    c.flag 'name', :desc => "The name of the provider." #, :default_value => 'Example'
+    c.flag 'domain', :desc => "The primary domain of the provider." #, :default_value => 'example.org'
+    c.flag 'platform', :desc => "File path of the leap_platform directory." #, :default_value => '../leap_platform'
+    c.flag 'contacts', :desc => "Default email address contacts." #, :default_value => 'root'
 
     c.action do |global, options, args|
       directory = File.expand_path(args.first)
diff --git a/lib/leap_cli/commands/node.rb b/lib/leap_cli/commands/node.rb
index bb02fa9..e8f2c73 100644
--- a/lib/leap_cli/commands/node.rb
+++ b/lib/leap_cli/commands/node.rb
@@ -10,13 +10,13 @@ module LeapCli; module Commands
 
   desc 'Node management'
   command :node do |node|
-    node.desc 'Create a new configuration file for a node'
-    node.long_desc ["If specified, the optional argument seed-options can be used to seed values in the node configuration file.",
+    node.desc 'Create a new configuration file for a node named NAME.'
+    node.long_desc ["If specified, the optional argument SEED can be used to seed values in the node configuration file.",
                     "The format is property_name:value.",
                     "For example: `leap node add web1 ip_address:1.2.3.4 services:webapp`.",
                     "To set nested properties, property name can contain '.', like so: `leap node add web1 ssh.port:44`",
-                    "To set multiple values for a single property, use ',', like so: `leap node add mynode services:webapp,dns`"].join("\n\n")
-    node.arg_name '<node-name> [seed-options]' # , :optional => false, :multiple => false
+                    "Separeate multiple values for a single property with a comma, like so: `leap node add mynode services:webapp,dns`"].join("\n\n")
+    node.arg_name 'NAME [SEED]' # , :optional => false, :multiple => false
     node.command :add do |add|
       add.switch :local, :desc => 'Make a local testing node (by automatically assigning the next available local IP address). Local nodes are run as virtual machines on your computer.', :negatable => false
       add.action do |global_options,options,args|
@@ -48,7 +48,7 @@ module LeapCli; module Commands
                    "copying the authorized_keys file, and installing packages that are required for deploying. " +
                    "Node init must be run before deploying to a server, and the server must be running and available via the network. " +
                    "This command only needs to be run once, but there is no harm in running it multiple times."
-    node.arg_name '<node-filter>' #, :optional => false, :multiple => false
+    node.arg_name 'FILTER' #, :optional => false, :multiple => false
     node.command :init do |init|
       init.switch 'echo', :desc => 'If set, passwords are visible as you type them (default is hidden)', :negatable => false
       init.action do |global,options,args|
@@ -68,8 +68,8 @@ module LeapCli; module Commands
       end
     end
 
-    node.desc 'Renames a node file, and all its related files'
-    node.arg_name '<old-name> <new-name>'
+    node.desc 'Renames a node file, and all its related files.'
+    node.arg_name 'OLD_NAME NEW_NAME'
     node.command :mv do |mv|
       mv.action do |global_options,options,args|
         node = get_node_from_args(args)
@@ -82,8 +82,8 @@ module LeapCli; module Commands
       end
     end
 
-    node.desc 'Removes a node file, and all its related files'
-    node.arg_name '<node-name>' #:optional => false #, :multiple => false
+    node.desc 'Removes all the files related to the node named NAME.'
+    node.arg_name 'NAME' #:optional => false #, :multiple => false
     node.command :rm do |rm|
       rm.action do |global_options,options,args|
         node = get_node_from_args(args)
diff --git a/lib/leap_cli/commands/shell.rb b/lib/leap_cli/commands/shell.rb
index 5d8fc66..cc17408 100644
--- a/lib/leap_cli/commands/shell.rb
+++ b/lib/leap_cli/commands/shell.rb
@@ -1,7 +1,7 @@
 module LeapCli; module Commands
 
-  desc 'Log in to the specified node with an interactive shell'
-  arg_name '<node-name>', :optional => false, :multiple => false
+  desc 'Log in to the specified node with an interactive shell.'
+  arg_name 'NAME' #, :optional => false, :multiple => false
   command :ssh do |c|
     c.action do |global_options,options,args|
       node = get_node_from_args(args)
diff --git a/lib/leap_cli/commands/test.rb b/lib/leap_cli/commands/test.rb
index e895a5e..80a6333 100644
--- a/lib/leap_cli/commands/test.rb
+++ b/lib/leap_cli/commands/test.rb
@@ -1,23 +1,23 @@
 module LeapCli; module Commands
 
-  desc 'Run tests'
-  command :test do |c|
-    c.desc 'Creates files needed to run tests'
-    c.command :init do |c|
-      c.action do |global_options,options,args|
+  desc 'Run tests.'
+  command :test do |test|
+    test.desc 'Creates files needed to run tests.'
+    test.command :init do |init|
+      init.action do |global_options,options,args|
         generate_test_client_cert
         generate_test_client_openvpn_config
       end
     end
 
-    c.desc 'Run tests'
-    c.command :run do |c|
-      c.action do |global_options,options,args|
+    test.desc 'Run tests.'
+    test.command :run do |run|
+      run.action do |global_options,options,args|
         log 'not yet implemented'
       end
     end
 
-    c.default_command :run
+    test.default_command :run
   end
 
   private
diff --git a/lib/leap_cli/commands/user.rb b/lib/leap_cli/commands/user.rb
index aed29b7..d0146b6 100644
--- a/lib/leap_cli/commands/user.rb
+++ b/lib/leap_cli/commands/user.rb
@@ -15,7 +15,7 @@ module LeapCli
   module Commands
 
     desc 'Adds a new trusted sysadmin'
-    arg_name '<username>', :optional => false, :multiple => false
+    arg_name 'USERNAME' #, :optional => false, :multiple => false
     command :'add-user' do |c|
 
       c.switch 'self', :desc => 'lets you choose among your public keys', :negatable => false
diff --git a/lib/leap_cli/commands/vagrant.rb b/lib/leap_cli/commands/vagrant.rb
index 5aeed74..56e887a 100644
--- a/lib/leap_cli/commands/vagrant.rb
+++ b/lib/leap_cli/commands/vagrant.rb
@@ -3,11 +3,11 @@ require 'fileutils'
 
 module LeapCli; module Commands
 
-  desc "Manage local virtual machines"
-  long_desc "This command provides a convient way to manage Vagrant-based virtual machines. If node-filter argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in 'test/Vagrantfile'. If you want to run vagrant commands manually, cd to 'test'."
+  desc "Manage local virtual machines."
+  long_desc "This command provides a convient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in 'test/Vagrantfile'. If you want to run vagrant commands manually, cd to 'test'."
   command :local do |local|
     local.desc 'Starts up the virtual machine(s)'
-    local.arg_name 'node-filter', :optional => true #, :multiple => false
+    local.arg_name 'FILTER', :optional => true #, :multiple => false
     local.command :start do |start|
       start.action do |global_options,options,args|
         vagrant_command(["up", "sandbox on"], args)
@@ -15,7 +15,7 @@ module LeapCli; module Commands
     end
 
     local.desc 'Shuts down the virtual machine(s)'
-    local.arg_name 'node-filter', :optional => true #, :multiple => false
+    local.arg_name 'FILTER', :optional => true #, :multiple => false
     local.command :stop do |stop|
       stop.action do |global_options,options,args|
         if global_options[:yes]
@@ -27,7 +27,7 @@ module LeapCli; module Commands
     end
 
     local.desc 'Destroys the virtual machine(s), reclaiming the disk space'
-    local.arg_name 'node-filter', :optional => true #, :multiple => false
+    local.arg_name 'FILTER', :optional => true #, :multiple => false
     local.command :destroy do |destroy|
       destroy.action do |global_options,options,args|
         if global_options[:yes]
@@ -39,7 +39,7 @@ module LeapCli; module Commands
     end
 
     local.desc 'Print the status of local virtual machine(s)'
-    local.arg_name 'node-filter', :optional => true #, :multiple => false
+    local.arg_name 'FILTER', :optional => true #, :multiple => false
     local.command :status do |status|
       status.action do |global_options,options,args|
         vagrant_command("status", args)
@@ -47,7 +47,7 @@ module LeapCli; module Commands
     end
 
     local.desc 'Saves the current state of the virtual machine as a new snapshot'
-    local.arg_name 'node-filter', :optional => true #, :multiple => false
+    local.arg_name 'FILTER', :optional => true #, :multiple => false
     local.command :save do |status|
       status.action do |global_options,options,args|
         vagrant_command("sandbox commit", args)
@@ -55,7 +55,7 @@ module LeapCli; module Commands
     end
 
     local.desc 'Resets virtual machine(s) to the last saved snapshot'
-    local.arg_name 'node-filter', :optional => true #, :multiple => false
+    local.arg_name 'FILTER', :optional => true #, :multiple => false
     local.command :reset do |reset|
       reset.action do |global_options,options,args|
         vagrant_command("sandbox rollback", args)