diff --git a/src/mako/cli/docs/commands.md.mako b/src/mako/cli/docs/commands.md.mako
index e2d16908a5..d02b1f23c7 100644
--- a/src/mako/cli/docs/commands.md.mako
+++ b/src/mako/cli/docs/commands.md.mako
@@ -1,8 +1,8 @@
 <%namespace name="util" file="../../lib/util.mako"/>\
 <%
-    from util import (hash_comment, new_context, method_default_scope)
+    from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by)
     from cli import (subcommand_md_filename, new_method_context, SPLIT_START, SPLIT_END, pretty, SCOPE_FLAG,
-                     mangle_subcommand)
+                     mangle_subcommand, is_request_value_property)
 
     c = new_context(schemas, resources, context.get('methods'))
 %>\
@@ -12,7 +12,6 @@
     mc = new_method_context(resource, method, c)
 %>\
 ${SPLIT_START} ${subcommand_md_filename(resource, method)}
-# ${pretty(resource)}: ${pretty(method)}
 % if mc.m.description:
 ${mc.m.description}
 % endif # show method description
@@ -33,6 +32,16 @@ the *${mc.m.scopes[0]}* scope to make a valid call.
 If unset, the scope for this method defaults to *${method_default_scope(mc.m)}*.
 You can set the scope for this method like this: `${util.program_name()} --${SCOPE_FLAG} <scope> ${mangle_subcommand(resource)} ${mangle_subcommand(method)} ...`
 % endif # have method scopes
+<%
+    rprops = [p for p in mc.required_props if not is_request_value_property(mc, p)]
+%>\
+% if rprops:
+# Required Scalar ${len(rprops) > 1 and 'Arguments' or 'Argument'}
+% for p in rprops:
+* **<${mangle_subcommand(p.name)}\>**
+    - ${p.get('description') or 'No description provided' | indent_all_but_first_by(2)}
+% endfor  # each required property (which is not the request value)
+% endif # have required properties
 ${SPLIT_END}
 % endfor # each method
 % endfor # each resource
diff --git a/src/mako/cli/lib/cli.py b/src/mako/cli/lib/cli.py
index 22e59e6f0c..42ad102d2d 100644
--- a/src/mako/cli/lib/cli.py
+++ b/src/mako/cli/lib/cli.py
@@ -37,6 +37,9 @@ def pretty(n):
     return ' '.join(s.capitalize() for s in mangle_subcommand(n).split('-'))
 
 
+def is_request_value_property(mc, p):
+    return mc.request_value and mc.request_value.id == p.get(util.TREF)
+
 # transform name to be a suitable subcommand
 def mangle_subcommand(name):
     return util.camel_to_under(name).replace('_', '-').replace('.', '-')
diff --git a/src/mako/cli/lib/docopt.mako b/src/mako/cli/lib/docopt.mako
index 9224d734d6..cfef9b250c 100644
--- a/src/mako/cli/lib/docopt.mako
+++ b/src/mako/cli/lib/docopt.mako
@@ -2,7 +2,7 @@
 <%!
     from util import (put_and, supports_scopes)
     from cli import (mangle_subcommand, new_method_context, PARAM_FLAG, STRUCT_FLAG, UPLOAD_FLAG, OUTPUT_FLAG, VALUE_ARG,
-                     CONFIG_DIR, SCOPE_FLAG)
+                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property)
 
     v_arg = '<%s>' % VALUE_ARG
     file_arg = '<file>'
@@ -24,10 +24,11 @@ Usage:
     mc = new_method_context(resource, method, c)
 
     args = list()
-    if mc.optional_props or parameters is not UNDEFINED:
-        args.append('[-%s %s]...' % (PARAM_FLAG, v_arg))
-        param_used = True
-    # end paramters
+    for p in mc.required_props:
+        if is_request_value_property(mc, p):
+            continue
+        args.append('<%s>' % mangle_subcommand(p.name))
+    # end for each required property
 
     if mc.request_value:
         args.append('-%s %s...' % (STRUCT_FLAG, v_arg))
@@ -43,6 +44,11 @@ Usage:
         upload_protocols_used = upload_protocols_used|set(upload_protocols)
     # end upload handling
 
+    if mc.optional_props or parameters is not UNDEFINED:
+        args.append('[-%s %s]...' % (PARAM_FLAG, v_arg))
+        param_used = True
+    # end paramters
+    
     if mc.response_schema:
         args.append('[-%s %s]' % (OUTPUT_FLAG, out_arg))
         output_used = True
@@ -55,9 +61,6 @@ Usage:
 
 % if param_used|struct_used|output_used or upload_protocols_used:
 Options:
-% if param_used:
-    -${PARAM_FLAG} ${v_arg}  set optional request parameter; ${v_arg} is of form 'name=value'
-% endif
 % if struct_used:
     -${STRUCT_FLAG} ${v_arg}  set request structure field;
             ${v_arg} supports cursor form 'field[:subfield]...' to 
@@ -71,6 +74,9 @@ Options:
             ${mime_arg} the mime type, like 'application/octet-stream', 
             which is the default
 % endif
+% if param_used:
+    -${PARAM_FLAG} ${v_arg}  set optional request parameter; ${v_arg} is of form 'name=value'
+% endif
 % if output_used:
     -${OUTPUT_FLAG} ${out_arg}
             The `destination` to which to write the server result to.