help command

src/etc/command_help.txt

@@ -1,30 +1,23 @@
-COMMANDS
-========
+Commands for Operation:
+    up          Bring up the whole instance, a project or service(s) inside a project
+    down        Bring down the whole instance, a project or service(s) inside a project
+    update      Update the whole instance, a project or service(s) inside a project
+    clean       Cleanly sync all configs to target folder, then relaunch affected projects
+    purge       Remove all running docker artifacts of this instance
 
-# operation
+Commands for Instance Management:
+    config      Create or configure kiwi-config instance
+    inspect     Inspect projects in this instance, services inside a project or service(s) inside a project
+    cmd         Run raw docker-compose command in a project
 
-config
-up
-down
-update
-clean
+Commands for Project and Service Management:
+    new         Create new empty project(s) in this instance
+    enable      Enable project(s) in this instance
+    disable     Disable project(s) in this instance
+    logs        Show logs of a project or service(s) inside a project
+    shell       Spawn shell inside a service inside a project
 
-# management
-
-new
-enable
-disable
-cmd
-purge
-
-# inspection
-
-inspect
-logs
-shell
-
-# imaging
-
-build
-pull
-push
+Commands for Image Handling:
+    build       Build images for the whole instance, a project or service(s) inside a project
+    pull        Pull images for the whole instance, a project or service(s) inside a project
+    push        Push images for the whole instance, a project or service(s) inside a project

src/etc/usage.txt

@@ -0,0 +1,6 @@
+
+  %(prog)s {up,down,update,clean,purge} [ARGS...]
+  %(prog)s {config,inspect,cmd} [ARGS...]
+  %(prog)s {new,enable,disable,logs,shell} [ARGS...]
+  %(prog)s {build,pull,push} [ARGS...]
+  %(prog)s -h|--help

src/kiwi/_constants.py

@@ -20,6 +20,7 @@ DEFAULT_KIWI_CONF_NAME = f"{KIWI_ROOT}/etc/kiwi_default.yml"
 VERSION_TAG_NAME = f"{KIWI_ROOT}/etc/version_tag"
 DEFAULT_DOCKER_COMPOSE_NAME = f"{KIWI_ROOT}/etc/docker-compose_default.yml"
 COMMAND_HELP_TEXT_NAME = f"{KIWI_ROOT}/etc/command_help.txt"
+USAGE_TEXT_NAME = f"{KIWI_ROOT}/etc/usage.txt"
 
 # special config directory in projects
 CONF_DIRECTORY_NAME = 'conf'

src/kiwi/parser.py

@@ -2,7 +2,7 @@
 import argparse
 
 # local
-from ._constants import COMMAND_HELP_TEXT_NAME
+from ._constants import COMMAND_HELP_TEXT_NAME, USAGE_TEXT_NAME
 
 
 class Parser:
@@ -19,12 +19,15 @@ class Parser:
         def __init__(self):
             # add version data from separate file (keeps default config cleaner)
             with open(COMMAND_HELP_TEXT_NAME, 'r') as stream:
-                command_help_text = stream.read().strip()
+                command_help_text = stream.read()
+
+            with open(USAGE_TEXT_NAME, 'r') as stream:
+                usage_text = stream.read()
 
             # create main parser
             self.__parser = argparse.ArgumentParser(
                 description='kiwi-config',
-                usage='%(prog)s [command]',
+                usage=usage_text,
                 epilog=command_help_text,
             )
             self.__parser.formatter_class = argparse.RawDescriptionHelpFormatter

src/kiwi/subcommands/config.py

@@ -15,7 +15,7 @@ class ConfigCommand(SubCommand):
         super().__init__(
             'config',
             action=f"Configuring '{KIWI_CONF_NAME}' in",
-            description="Configure kiwi-config instance"
+            description="Create or configure kiwi-config instance"
         )
 
         # -f switch: Initialize with default config

src/kiwi/subcommands/disable.py

@@ -9,7 +9,7 @@ class DisableCommand(ProjectCommand):
         super().__init__(
             'disable', num_projects='+',
             action="Disabling",
-            description="Disable whole project(s) in this instance"
+            description="Disable project(s) in this instance"
         )
 
     def _run_projects(self, runner, args, projects):

src/kiwi/subcommands/enable.py

@@ -9,7 +9,7 @@ class EnableCommand(ProjectCommand):
         super().__init__(
             'enable', num_projects='+',
             action="Enabling",
-            description="Enable whole project(s) in this instance"
+            description="Enable project(s) in this instance"
         )
 
     def _run_projects(self, runner, args, projects):

src/kiwi/subcommands/logs.py

@@ -9,7 +9,7 @@ class LogsCommand(ServiceCommand):
         super().__init__(
             'logs', num_projects=1, num_services='*',
             action="Showing logs of",
-            description="Show logs of a project or service(s) of a project"
+            description="Show logs of a project or service(s) inside a project"
         )
 
         # -f switch: Follow logs

src/kiwi/subcommands/purge.py

@@ -17,7 +17,7 @@ class PurgeCommand(SubCommand):
         super().__init__(
             'purge',
             action="Tearing down",
-            description="Remove all ephemeral artifacts of this instance"
+            description="Remove all running docker artifacts of this instance"
         )
 
     def _run_instance(self, runner, args):