Document upcoming features

gl-sak

@@ -4,6 +4,36 @@
 
 A general-purpose GitLab tool for batch access to and manipulation of
 entities (issues, labels, milestones, etc) in a GitLab project.
+
+Usage
+
+  $ ./gl-sak --root OWNER[/PROJECT_PATH] COMMAND [ARGS...]
+
+OWNER/PROJECT_PATH is something like "jrandom/foo/bar/myproj".
+
+TBD: Document some commands, some of which take further arguments.
+
+GitLab authentication and authorization
+---------------------------------------
+
+Each time you run this script, you will be prompted for a GitLab
+authorization token.  If you don't want to be prompted, put the token
+as the first line of a file (you might want to restrict that file's
+permissions so that only you can read it) and pass the file with the
+'--authn-token-file' option, like so:
+
+  $ ./gl-sak --authn-token-file FILE_CONTAINING_TOKEN [...]
+
+You could also pass the token directly via the command line with the
+'--auth-token' option, like this:
+
+  $ ./gl-sak --authn-token TOKEN [...]
+
+However, be careful about that: the token could then leak via 'ps'
+listings, shell history, etc.  Only you can decide whether using
+'--authn-token' is a reasonable choice given the security properties
+of your runtime environment, but if you are in any doubt, just use
+'--authn-token-file' instead.
 """
 
 # To get started:
@@ -29,13 +59,18 @@ def main():
         # here would be RawDescriptionHelpFormatter.
         formatter_class=argparse.RawTextHelpFormatter)
     arg_parser.add_argument(
-        '-t', '--access-token',
+        '-T', '--authn-token',
+        # TBD: This next one is not implemented yet.  Also, how to
+        # tell argparse that two options are mutually incompatible?
+        # Do we just have to do that with post-parsing code, or does
+        # argparse have a built-in way to handle it?
+        '-F', '--authn-token-file',
         help="The GitLab access token to use for this operation")
     args = arg_parser.parse_args()
 
     # Set up the GitLab instance.
     lhq = gitlab.Gitlab(url='https://code.librehq.com', 
-                        private_token=args.access_token)
+                        private_token=args.authn_token)
     lhq.auth()
 
     # WARNING: Turning on debugging can cause credentials and other