changed cli options; improved alignment in list output

HISTORY.md

@@ -19,3 +19,7 @@
 
 ### release notes for 0.3.0
 - added command and filtering options for listing Healthchecks status
+
+### release notes for 0.4.0
+- changed command line flags for list
+- improved table alignment for the list command

README.md

@@ -21,6 +21,39 @@ $ which sch
 ``` console
 sch, version 0.2.1
 ```
+## Command line usage
+See the `--help` option for usage:
+``` console
+Usage: sch [OPTIONS] COMMAND [ARGS]...
+
+  sch - A cron shell wrapper for registering and updating cron jobs
+  automatically in Healthchecks. The Healthchecks project api_url and
+  api_key should be configured in /etc/sch.conf.
+
+Options:
+  --version                 Show the version and exit.
+  -c, --shell_command TEXT  Command to execute. This how Cron executes 'sch'
+                            when it is set as SHELL.
+  --help                    Show this message and exit.
+
+Commands:
+  list  List checks for the configured Healthchecks project.
+```
+
+### `list` command
+``` console
+Usage: sch list [OPTIONS]
+
+  List checks for the configured Healthchecks project.
+
+Options:
+  -l, --localhost / -a, --all     List checks that originate from this host
+                                  (default) or list all checks.
+  -s, --status [up|down|grace|started|pause|new]
+                                  Show only checks that have the specified
+                                  status.
+  --help                          Show this message and exit.
+```
 
 ## Configuration
 Create a configuration file `/etc/sch.conf` that looks like:

sch/cli.py

@@ -11,28 +11,33 @@ from sch import sch
 
 @click.group(invoke_without_command=True, no_args_is_help=True)
 @click.version_option()
-@click.option('-c', '--shell_command', help='command to execute')
+@click.option('-c', '--shell_command',
+              help='Command to execute. This how Cron'
+                   ' executes \'sch\' when it is set as SHELL.')
 def main(shell_command=None):
     """
     sch - A cron shell wrapper for registering and updating cron jobs
-    automatically in healthchecks
+    automatically in Healthchecks. The Healthchecks project api_url and
+    api_key should be configured in /etc/sch.conf.
     """
     if shell_command:
         sch.shell(shell_command)
 
 
 @main.command('list')
-@click.option('-a', '--all', 'host_filter', flag_value='all')
-@click.option('-l', '--local', 'host_filter', flag_value='local',
-              default=True)
+@click.option('--localhost/--all', '-l/-a', 'list_local', default=True,
+              help='List checks that originate from this host (default) or '
+              'list all checks.')
 @click.option('-s', '--status', 'status_filter',
-              type=click.Choice(['up', 'down', 'grace', 'pause', 'new']))
-def listchecks(host_filter, status_filter):
+              type=click.Choice(['up', 'down', 'grace',
+                                 'started', 'pause', 'new']),
+              help='Show only checks that have the specified status.')
+def listchecks(list_local, status_filter):
     """
-    list Healthchecks checks
+    List checks for the configured Healthchecks project.
     """
     healthchecks = sch.get_hc_api()
-    healthchecks.print_status(host_filter, status_filter)
+    healthchecks.print_status(list_local, status_filter)
 
 
 if __name__ == "__main__":

sch/sch.py

@@ -469,21 +469,25 @@ class Healthchecks:
         logging.debug("Successfully set grace_time to %s seconds", grace)
         return True
 
-    def print_status(self, host_filter, status_filter):
-        """Show status of monitored cron jobs"""
-        click.secho("{status:<6} {last_ping:<15} {name:<40}".format(
+    def print_status(self, list_local, status_filter):
+        """
+        Show status of monitored cron jobs
+        """
+        line_template = "{status:7.7} {last_ping:15.15} {name:40.40}"
+        click.secho(line_template.format(
             status="Status",
             name="Name",
             last_ping="Last ping"
         ))
-        click.secho("{status:-<6} {last_ping:-<15} {name:-<40}".format(
-            status="",
-            name="",
-            last_ping=""
+        dashes = '----------------------------------------'
+        click.secho(line_template.format(
+            status=dashes,
+            name=dashes,
+            last_ping=dashes
         ))
 
-        query = ''  # host_filter == all
-        if host_filter == 'local':
+        query = ''
+        if list_local:
             tag_for_host = 'host={hostname}'.format(hostname=socket.getfqdn())
             query = "?&tag={tag}".format(tag=quote_plus(tag_for_host))
 
@@ -515,7 +519,7 @@ class Healthchecks:
                 last_ping = ''
 
             click.secho(
-                "{status:<6} {last_ping:<15} {name:<40}".format(
+                line_template.format(
                     status=i['status'],
                     name=i['name'],
                     last_ping=last_ping