decent user-facing documentation for the "autoca" tool

autoca/ca_tool.py

@@ -19,28 +19,65 @@ def writeout(output, data):
 
 
 def main():
-    parser = optparse.OptionParser()
-    parser.add_option('--url', dest='url',
+    parser = optparse.OptionParser(usage='''%prog [<OPTIONS>] <COMMAND>
+
+Known commands:
+
+init
+        Initialize a new local CA. You must provide the --ca-path
+        and --ca-subject options.
+
+get-ca
+        Outputs the CA certificate in PEM format.
+
+get-crl
+        Outputs the CA Certificate Revocation List. It is possible
+        to request a specific output format by passing the desired
+        format as second argument ("pem" or "der").
+
+sign
+        Create a new certificate request and sign it. If the --server
+        option is not specified, a client certificate will be
+        generated by default.
+
+The tool can operate either with a local CA or a remote one. Use the
+--ca-path option in the former case, or specify the server location
+with --url in the latter. Accessing a remote CA might require
+authentication: use the --secret option for puny shared-secret HTTP
+auth (the default). Other authentication methods may be available on
+your system.
+
+X509 subjects, where applicable, must be specified as key=value pairs
+separated by slashes ('/'), for example:
+
+    CN=example.com/OU=Web/O=Example
+
+''')
+    g = parser.add_option_group('Connection options')
+    g.add_option('--url', dest='url',
                  help='autoca API endpoint')
-    parser.add_option('--ca-path', dest='ca_path',
+    g.add_option('--ca-path', dest='ca_path',
                  help='local CA directory')
-    parser.add_option('--output', dest='output', metavar='FILE',
+    g = parser.add_option_group('Output options')
+    g.add_option('--output', dest='output', metavar='FILE',
                  help='write output to this file')
-    parser.add_option('--outkey', dest='outkey', metavar='FILE',
+    g.add_option('--outkey', dest='outkey', metavar='FILE',
                  help='write private key to this file (only '
                  'useful with the "sign" command)')
-    parser.add_option('--server', dest='server', action='store_true',
+    g = parser.add_option_group('Options for the "init" command')
+    g.add_option('--ca-subject', dest='ca_subject',
+                      help='CA X.509 subject (only on initialization)')
+    g.add_option('--ca-bits', dest='ca_bits', type='int', default=1024,
+                      help='CA key size (only on initialization)')
+    g = parser.add_option_group('Options for the "sign" command')
+    g.add_option('--server', dest='server', action='store_true',
                       help='create a server certificate (for "sign")')
-    parser.add_option('--subject', dest='subject',
+    g.add_option('--subject', dest='subject',
                       help='specify the X.509 subject as a set of '
                       'comma-separated ATTR=VALUE assignments')
-    parser.add_option('--ca-subject', dest='ca_subject',
-                      help='CA X.509 subject (only on initialization)')
-    parser.add_option('--ca-bits', dest='ca_bits', type='int', default=1024,
-                      help='CA key size (only on initialization)')
-    parser.add_option('--secret', dest='secret',
+    g.add_option('--secret', dest='secret',
                       help='shared secret for authentication')
-    parser.add_option('--days', dest='days', type='int', default=7,
+    g.add_option('--days', dest='days', type='int', default=7,
                       help='certificate validity')
     opts, args = parser.parse_args()
     if len(args) < 1: