Merge pull request #3177 from bacongobbler/proposal-deis-client-plugins

Proposal: deis client plugins

Author: Matthew Fisher

client/deis.py

@@ -2208,7 +2208,17 @@ def main():
     if hasattr(cli, cmd):
         method = getattr(cli, cmd)
     else:
-        raise DocoptExit('Found no matching command, try `deis help`')
+        # split by : to execute the proper command
+        split_cmd = args['<command>'].split(':')
+        dash_separated_command = 'deis-{}'.format(split_cmd[0])
+        arglist = args['<args>']
+        if len(split_cmd) > 1:
+            # safety precaution in case users want to use more than one colon in their command
+            arglist = split_cmd[1:] + arglist
+        try:
+            sys.exit(subprocess.call([dash_separated_command] + arglist))
+        except OSError:
+            raise DocoptExit('Found no matching command, try `deis help`')
     # re-parse docopt with the relevant docstring
     docstring = trim(getattr(cli, cmd).__doc__)
     if 'Usage: ' in docstring:

docs/customizing_deis/cli-plugins.rst

@@ -0,0 +1,36 @@
+:title: CLI Plugins
+:description: How to manage plugins for the Deis CLI.
+
+.. _cli_plugins:
+
+CLI Plugins
+===========
+
+Plugins allow developers to extend the functionality of the :ref:`Deis Client <install-client>`,
+adding new commands or features.
+
+If an unknown command is specified, the Client will attempt to execute the command as a
+dash-separated command. In this case, ``deis resource:command`` will execute ``deis-resource`` with
+the argument list ``command``. In full form:
+
+.. code-block:: console
+
+    $ # these two are identical
+    $ deis accounts:list
+    $ deis-accounts list
+
+Any flags after the command will also be sent to the plugin as an argument:
+
+.. code-block:: console
+
+    $ # these two are identical
+    $ deis accounts:list --debug
+    $ deis-accounts list --debug
+
+But flags preceeding the command will not:
+
+.. code-block:: console
+
+    $ # these two are identical
+    $ deis --debug accounts:list
+    $ deis-accounts list

docs/customizing_deis/index.rst

@@ -11,6 +11,7 @@ Customizing Deis
 
 .. toctree::
 
+    cli-plugins
     builder_settings
     cache_settings
     controller_settings